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 { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
import { EventEmitter } from 'node:events';
import { PassThrough } from 'stream';
import { request } from '../lib/testHelper.js';
import { errorMiddleware, ServerError } from '../lib/errorHandler.js';
vi.mock('../services/backup.js', () => ({
getState: vi.fn(),
getNextRunTime: vi.fn(),
runBackup: vi.fn(),
listSnapshots: vi.fn(),
openSnapshotStream: vi.fn(),
restoreSnapshot: vi.fn(),
restorePostgres: vi.fn(),
deleteSnapshot: vi.fn(),
DEFAULT_EXCLUDES: [
{ path: '/browser-profile/', reason: 'test', overridable: false },
{ path: '/loras/*.safetensors', reason: 'test', overridable: true }
]
}));
vi.mock('../services/backupRestoreRecovery.js', () => ({
getDatabaseRestoreRecoveryStatus: vi.fn(() => ({ pending: false })),
resumeDatabaseRestore: vi.fn(),
}));
vi.mock('../services/settings.js', () => ({
getSettings: vi.fn(),
settingsEvents: new EventEmitter()
}));
vi.mock('../services/auth.js', () => ({
isAuthEnabled: vi.fn(),
verifyPassword: vi.fn(),
verifyRequestSession: vi.fn(),
}));
vi.mock('../services/instanceIdentity.js', () => ({ loadData: vi.fn() }));
import { isAuthEnabled, verifyPassword, verifyRequestSession } from '../services/auth.js';
import { loadData } from '../services/instanceIdentity.js';
import { authGate, hostControlRouteGate } from '../services/authGate.js';
import { derivePeerAuthToken, PEER_AUTH_HEADER, PEER_INSTANCE_HEADER } from '../lib/peerHttpClient.js';
import { DEV_PROXY_CLIENT_ADDRESS_HEADER } from '../../lib/portosAuthCore.js';
import * as backup from '../services/backup.js';
import { getDatabaseRestoreRecoveryStatus, resumeDatabaseRestore } from '../services/backupRestoreRecovery.js';
import { getSettings } from '../services/settings.js';
import backupRoutes from './backup.js';
const buildApp = () => {
const app = express();
app.use(express.json());
app.use('/api/backup', backupRoutes);
app.use(errorMiddleware);
return app;
};
describe('backup routes', () => {
beforeEach(() => {
vi.clearAllMocks();
});
describe('GET /api/backup/status', () => {
it('returns merged state, configured destPath, and nextRun', async () => {
backup.getState.mockResolvedValue({ lastRun: '2026-04-01T00:00:00Z', success: true });
backup.getNextRunTime.mockReturnValue('2026-04-08T00:00:00Z');
getSettings.mockResolvedValue({ backup: { destPath: '/backup/target' } });
const res = await request(buildApp()).get('/api/backup/status');
expect(res.status).toBe(200);
expect(res.body).toEqual({
lastRun: '2026-04-01T00:00:00Z',
success: true,
destPath: '/backup/target',
nextRun: '2026-04-08T00:00:00Z',
defaultExcludes: [
{ path: '/browser-profile/', reason: 'test', overridable: false },
{ path: '/loras/*.safetensors', reason: 'test', overridable: true }
],
restoreRecovery: { pending: false },
});
});
it('reports a committed restore awaiting recovery (#9725)', async () => {
backup.getState.mockResolvedValue({});
getSettings.mockResolvedValue({ backup: {} });
const pending = { pending: true, id: '00000000-0000-4000-8000-000000000001', stage: 'repairing', snapshotId: 'snap-1', createdAt: '2026-01-01T00:00:00.000Z' };
getDatabaseRestoreRecoveryStatus.mockReturnValueOnce(pending);
const res = await request(buildApp()).get('/api/backup/status');
expect(res.body.restoreRecovery).toEqual(pending);
});
it('serves a process-local persistence failure without hiding the last successful snapshot', async () => {
const state = {
status: 'error', lastSnapshotId: 'previous-snapshot',
lastRun: '2026-01-02T00:00:00.000Z', pgBackup: null,
error: 'Backup failed; status persistence failed (EACCES). See server logs.',
};
backup.getState.mockResolvedValue(state);
backup.getNextRunTime.mockReturnValue(null);
getSettings.mockResolvedValue({ backup: { destPath: '/backup/target' } });
const res = await request(buildApp()).get('/api/backup/status');
expect(res.status).toBe(200);
expect(res.body).toMatchObject(state);
});
it('returns null destPath when backup is not configured', async () => {
backup.getState.mockResolvedValue({});
backup.getNextRunTime.mockReturnValue(null);
getSettings.mockResolvedValue({});
const res = await request(buildApp()).get('/api/backup/status');
expect(res.status).toBe(200);
expect(res.body.destPath).toBeNull();
});
});
describe('POST /api/backup/run', () => {
it('returns 400 when no destination is configured', async () => {
getSettings.mockResolvedValue({ backup: {} });
const res = await request(buildApp()).post('/api/backup/run');
expect(res.status).toBe(400);
// Standard error envelope: machine code in `code`, human text in `error`.
expect(res.body.code).toBe('BACKUP_NOT_CONFIGURED');
expect(res.body.error).toBe('No backup destination configured in settings');
expect(backup.runBackup).not.toHaveBeenCalled();
});
it('runs the backup and forwards excludePaths', async () => {
getSettings.mockResolvedValue({
// Anchored is the canonical spelling; the second entry is deliberately
// not, to pin that the route forwards STORED settings verbatim — anchoring
// is a read-time concern inside computeEffectiveExcludes (#7241).
backup: { destPath: '/dest', excludePaths: ['/node_modules', '.git'] }
});
backup.runBackup.mockResolvedValue({ success: true, files: 100 });
const res = await request(buildApp()).post('/api/backup/run');
expect(res.status).toBe(200);
expect(res.body).toEqual({ success: true, files: 100 });
expect(backup.runBackup).toHaveBeenCalledWith(
'/dest',
undefined,
{ excludePaths: ['/node_modules', '.git'], disabledDefaultExcludes: [], retentionCount: null }
);
});
it('passes empty excludePaths when not configured', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.runBackup.mockResolvedValue({ success: true });
await request(buildApp()).post('/api/backup/run');
expect(backup.runBackup).toHaveBeenCalledWith(
'/dest',
undefined,
{ excludePaths: [], disabledDefaultExcludes: [], retentionCount: null }
);
});
it('forwards disabledDefaultExcludes when configured', async () => {
getSettings.mockResolvedValue({
backup: { destPath: '/dest', disabledDefaultExcludes: ['/loras/*.safetensors'] }
});
backup.runBackup.mockResolvedValue({ success: true });
await request(buildApp()).post('/api/backup/run');
expect(backup.runBackup).toHaveBeenCalledWith(
'/dest',
undefined,
{ excludePaths: [], disabledDefaultExcludes: ['/loras/*.safetensors'], retentionCount: null }
);
});
it('forwards the resolved retentionCount', async () => {
getSettings.mockResolvedValue({
backup: { destPath: '/dest', retentionCount: 14 }
});
backup.runBackup.mockResolvedValue({ success: true });
await request(buildApp()).post('/api/backup/run');
expect(backup.runBackup).toHaveBeenCalledWith(
'/dest',
undefined,
{ excludePaths: [], disabledDefaultExcludes: [], retentionCount: 14 }
);
});
});
describe('GET /api/backup/snapshots', () => {
it('returns classified inventory failures through the centralized boundary', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/backup/target' } });
backup.listSnapshots.mockRejectedValueOnce(new ServerError(
'Backup inventory unavailable: read-namespace (EIO)',
{ code: 'BACKUP_INVENTORY_UNAVAILABLE', context: { operation: 'read-namespace', filesystemCode: 'EIO' } },
));
const res = await request(buildApp()).get('/api/backup/snapshots');
expect(res.status).toBe(500);
expect(res.body).toMatchObject({
error: 'Backup inventory unavailable: read-namespace (EIO)',
code: 'BACKUP_INVENTORY_UNAVAILABLE',
});
expect(JSON.stringify(res.body)).not.toContain('/backup/target');
});
it('returns the list of snapshots from the configured destPath', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.listSnapshots.mockResolvedValue([{ id: 's1' }, { id: 's2' }]);
const res = await request(buildApp()).get('/api/backup/snapshots');
expect(res.status).toBe(200);
expect(res.body).toHaveLength(2);
expect(backup.listSnapshots).toHaveBeenCalledWith('/dest');
});
});
describe('GET /api/backup/snapshots/:snapshotId/download', () => {
it('streams a gzip attachment for the requested snapshot', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.openSnapshotStream.mockImplementation(async () => {
const stream = new PassThrough();
process.nextTick(() => stream.end(Buffer.from('tarball')));
return stream;
});
const res = await request(buildApp()).get('/api/backup/snapshots/snap-1/download');
expect(res.status).toBe(200);
expect(res.headers['content-type']).toMatch(/^application\/gzip/);
expect(res.headers['content-disposition']).toBe('attachment; filename="portos-snapshot-snap-1.tar.gz"');
expect(res.body.toString()).toBe('tarball');
expect(backup.openSnapshotStream).toHaveBeenCalledWith('/dest', 'snap-1');
});
it('validates and forwards the selected snapshot source', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.openSnapshotStream.mockImplementation(async () => {
const stream = new PassThrough();
process.nextTick(() => stream.end(Buffer.from('tarball')));
return stream;
});
const res = await request(buildApp())
.get('/api/backup/snapshots/snap-1/download?source=previous-machine');
expect(res.status).toBe(200);
expect(res.headers['content-disposition'])
.toBe('attachment; filename="portos-snapshot-previous-machine-snap-1.tar.gz"');
expect(backup.openSnapshotStream)
.toHaveBeenCalledWith('/dest', 'snap-1', { source: 'previous-machine' });
});
it('rejects a traversing source before opening the snapshot', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
const res = await request(buildApp())
.get('/api/backup/snapshots/snap-1/download?source=..%2Fother-machine');
expect(res.status).toBe(400);
expect(res.body.code).toBe('VALIDATION_ERROR');
expect(backup.openSnapshotStream).not.toHaveBeenCalled();
});
it('returns 400 when the backup destination is not configured', async () => {
getSettings.mockResolvedValue({ backup: {} });
const res = await request(buildApp()).get('/api/backup/snapshots/snap-1/download');
expect(res.status).toBe(400);
expect(res.body.code).toBe('BACKUP_NOT_CONFIGURED');
expect(backup.openSnapshotStream).not.toHaveBeenCalled();
});
});
describe('DELETE /api/backup/snapshots/:snapshotId', () => {
it('deletes a snapshot on the current machine by default', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.deleteSnapshot.mockResolvedValue({ deleted: true, snapshotId: 'snap-1', source: 'this-machine' });
const res = await request(buildApp()).delete('/api/backup/snapshots/snap-1');
expect(res.status).toBe(200);
expect(res.body).toEqual({ deleted: true, snapshotId: 'snap-1', source: 'this-machine' });
expect(backup.deleteSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', { source: undefined });
});
it('forwards an explicitly selected source', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.deleteSnapshot.mockResolvedValue({ deleted: true, snapshotId: 'snap-1', source: 'previous-machine' });
const res = await request(buildApp())
.delete('/api/backup/snapshots/snap-1?source=previous-machine');
expect(res.status).toBe(200);
expect(backup.deleteSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', { source: 'previous-machine' });
});
it('rejects a traversing source before deleting anything', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
const res = await request(buildApp())
.delete('/api/backup/snapshots/snap-1?source=..%2Fother-machine');
expect(res.status).toBe(400);
expect(res.body.code).toBe('VALIDATION_ERROR');
expect(backup.deleteSnapshot).not.toHaveBeenCalled();
});
it('surfaces the structured conflict when a restore or download is reading the snapshot (#10898)', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.deleteSnapshot.mockRejectedValueOnce(new ServerError(
'Snapshot is in use by a restore or download: snap-1. Retry when it finishes.',
{ status: 409, code: 'SNAPSHOT_IN_USE', context: { snapshotId: 'snap-1' } },
));
const res = await request(buildApp()).delete('/api/backup/snapshots/snap-1');
expect(res.status).toBe(409);
expect(res.body).toMatchObject({ code: 'SNAPSHOT_IN_USE', context: { snapshotId: 'snap-1' } });
});
it('returns 400 when the backup destination is not configured', async () => {
getSettings.mockResolvedValue({ backup: {} });
const res = await request(buildApp()).delete('/api/backup/snapshots/snap-1');
expect(res.status).toBe(400);
expect(res.body.code).toBe('BACKUP_NOT_CONFIGURED');
expect(backup.deleteSnapshot).not.toHaveBeenCalled();
});
});
describe('POST /api/backup/restore', () => {
it.each([
{ description: 'missing backup settings', settings: {}, dryRun: true },
{ description: 'missing backup settings', settings: {}, dryRun: false },
{ description: 'missing destination', settings: { backup: {} }, dryRun: true },
{ description: 'missing destination', settings: { backup: {} }, dryRun: false },
{ description: 'empty destination', settings: { backup: { destPath: '' } }, dryRun: true },
{ description: 'empty destination', settings: { backup: { destPath: '' } }, dryRun: false },
])('returns a structured 400 without invoking restore for $description (dryRun=$dryRun)', async ({ settings, dryRun }) => {
getSettings.mockResolvedValue(settings);
const res = await request(buildApp())
.post('/api/backup/restore')
.send({ snapshotId: 'snap-1', dryRun });
expect(res.status).toBe(400);
expect(res.body).toMatchObject({
error: 'No backup destination configured in settings',
code: 'BACKUP_NOT_CONFIGURED',
});
expect(backup.restoreSnapshot).not.toHaveBeenCalled();
});
it('returns 400 when snapshotId is missing', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
const res = await request(buildApp()).post('/api/backup/restore').send({});
expect(res.status).toBe(400);
expect(res.body.code).toBe('VALIDATION_ERROR');
expect(backup.restoreSnapshot).not.toHaveBeenCalled();
});
it('forwards a valid restore request to the service', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restoreSnapshot.mockResolvedValue({
success: true,
restored: 42,
verification: { status: 'verified', checkedFiles: 42 },
});
const res = await request(buildApp())
.post('/api/backup/restore')
.send({ snapshotId: 'snap-1', subdirFilter: 'data', dryRun: false });
expect(res.status).toBe(200);
expect(res.body).toEqual({
success: true,
restored: 42,
verification: { status: 'verified', checkedFiles: 42 },
});
expect(backup.restoreSnapshot).toHaveBeenCalledWith(
'/dest',
'snap-1',
{ dryRun: false, subdirFilter: 'data', adoptIdentity: false }
);
});
it('forwards an explicit identity adoption and refuses a non-boolean one (#12596)', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restoreSnapshot.mockResolvedValue({ changedFiles: [] });
const adopted = await request(buildApp())
.post('/api/backup/restore')
.send({ snapshotId: 'snap-1', dryRun: false, adoptIdentity: true });
expect(adopted.status).toBe(200);
expect(backup.restoreSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', expect.objectContaining({ adoptIdentity: true }));
backup.restoreSnapshot.mockClear();
const refused = await request(buildApp())
.post('/api/backup/restore')
.send({ snapshotId: 'snap-1', dryRun: false, adoptIdentity: 'yes' });
expect(refused.status).toBe(400);
expect(backup.restoreSnapshot).not.toHaveBeenCalled();
});
it('refuses a restore of a snapshot whose deletion is in progress with a structured conflict (#10898)', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restoreSnapshot.mockRejectedValueOnce(new ServerError(
'Snapshot is being deleted: snap-1',
{ status: 409, code: 'SNAPSHOT_DELETING', context: { snapshotId: 'snap-1' } },
));
const res = await request(buildApp())
.post('/api/backup/restore')
.send({ snapshotId: 'snap-1', dryRun: false });
expect(res.status).toBe(409);
expect(res.body).toMatchObject({ code: 'SNAPSHOT_DELETING', context: { snapshotId: 'snap-1' } });
});
it('forwards source with file restore preview and execution requests', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restoreSnapshot.mockResolvedValue({ changedFiles: [] });
const res = await request(buildApp())
.post('/api/backup/restore')
.send({ snapshotId: 'snap-1', source: '@legacy', subdirFilter: null, dryRun: true });
expect(res.status).toBe(200);
expect(backup.restoreSnapshot).toHaveBeenCalledWith('/dest', 'snap-1', {
dryRun: true,
subdirFilter: null,
adoptIdentity: false,
source: '@legacy',
});
});
it('defaults dryRun to true when omitted', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restoreSnapshot.mockResolvedValue({ success: true });
await request(buildApp())
.post('/api/backup/restore')
.send({ snapshotId: 'snap-2' });
expect(backup.restoreSnapshot).toHaveBeenCalledWith(
'/dest',
'snap-2',
expect.objectContaining({ dryRun: true })
);
});
});
describe('POST /api/backup/restore-db/recover', () => {
it('resumes exactly the named pending operation', async () => {
const id = '00000000-0000-4000-8000-000000000001';
resumeDatabaseRestore.mockResolvedValue({ status: 'ok', outcome: 'repaired', syncCursorsRewound: 1 });
const res = await request(buildApp()).post('/api/backup/restore-db/recover').send({ id });
expect(res.status).toBe(200);
expect(res.body).toEqual({ status: 'ok', outcome: 'repaired', syncCursorsRewound: 1 });
expect(resumeDatabaseRestore).toHaveBeenCalledWith(id);
});
it('rejects a missing or malformed operation id without resuming', async () => {
for (const body of [{}, { id: 'snap-1' }, { id: '00000000-0000-4000-8000-000000000001', dryRun: false }]) {
const res = await request(buildApp()).post('/api/backup/restore-db/recover').send(body);
expect(res.status).toBe(400);
}
expect(resumeDatabaseRestore).not.toHaveBeenCalled();
});
});
describe('POST /api/backup/restore-db', () => {
it('calls restorePostgres with the validated body (dryRun default true)', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restorePostgres.mockResolvedValue({ status: 'ok', dryRun: true, sizeBytes: 10, tableCount: 1 });
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: '2026-06-05T00-00-00' });
expect(res.status).toBe(200);
expect(res.body).toEqual({ status: 'ok', dryRun: true, sizeBytes: 10, tableCount: 1 });
expect(backup.restorePostgres).toHaveBeenCalledWith(
'/dest',
'2026-06-05T00-00-00',
{ dryRun: true }
);
});
it('reports a refused preflight and a concurrent maintenance request without success', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restorePostgres.mockResolvedValueOnce({ status: 'failed', reason: 'restore_preflight' });
const refused = await request(buildApp()).post('/api/backup/restore-db').send({ snapshotId: 'snap-1' });
expect(refused.body).toMatchObject({ status: 'failed', reason: 'restore_preflight' });
backup.restorePostgres.mockRejectedValueOnce(Object.assign(new Error('Restore in progress'), {
status: 503, code: 'DATABASE_MAINTENANCE',
}));
const busy = await request(buildApp()).post('/api/backup/restore-db').send({ snapshotId: 'snap-1', dryRun: false });
expect(busy.status).toBe(503);
});
it('forwards source with database restore preview and execution requests', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restorePostgres.mockResolvedValue({ status: 'ok', dryRun: true });
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: 'snap-1', source: 'previous-machine', dryRun: true });
expect(res.status).toBe(200);
expect(backup.restorePostgres).toHaveBeenCalledWith('/dest', 'snap-1', {
dryRun: true,
source: 'previous-machine',
});
});
it.each(['../other-machine', 'machine/name', '', 42])(
'rejects invalid snapshot source %j before database restore',
async (source) => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: 'snap-1', source });
expect(res.status).toBe(400);
expect(res.body.code).toBe('VALIDATION_ERROR');
expect(backup.restorePostgres).not.toHaveBeenCalled();
},
);
it('forwards dryRun=false when explicitly requested', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restorePostgres.mockResolvedValue({ status: 'ok', dryRun: false });
await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: 'snap-9', dryRun: false });
expect(backup.restorePostgres).toHaveBeenCalledWith(
'/dest',
'snap-9',
{ dryRun: false }
);
});
it('returns 400 when snapshotId is missing', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
const res = await request(buildApp()).post('/api/backup/restore-db').send({});
expect(res.status).toBe(400);
expect(res.body.code).toBe('VALIDATION_ERROR');
expect(backup.restorePostgres).not.toHaveBeenCalled();
});
it('returns 400 when no destination is configured', async () => {
getSettings.mockResolvedValue({ backup: {} });
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: 'snap-1' });
expect(res.status).toBe(400);
expect(res.body.code).toBe('BACKUP_NOT_CONFIGURED');
expect(backup.restorePostgres).not.toHaveBeenCalled();
});
// `restoreDbRequestSchema` types snapshotId as a non-empty string. A client
// that sends a number, object, array, null, or '' must get the structured
// 400 VALIDATION_ERROR envelope — never a coerced snapshot id reaching the
// service, and never a generic 500.
it.each([
['a number', 12345],
['an object', { id: 'snap-1' }],
['an array', ['snap-1']],
['null', null],
['an empty string', ''],
['a boolean', true]
])('returns 400 VALIDATION_ERROR when snapshotId is %s', async (_label, snapshotId) => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId });
expect(res.status).toBe(400);
expect(res.body.code).toBe('VALIDATION_ERROR');
expect(backup.restorePostgres).not.toHaveBeenCalled();
});
// dryRun is the safety switch between "report what would happen" and
// "replay the dump over the live database". Zod must NOT coerce a truthy/
// falsy lookalike — a client sending the string 'false' has to be rejected
// outright rather than silently arriving as `true` and wiping the DB.
it.each([
['the string "false"', 'false'],
['the string "true"', 'true'],
['the number 0', 0],
['the number 1', 1],
['null', null],
['an object', {}]
])('returns 400 VALIDATION_ERROR when dryRun is %s', async (_label, dryRun) => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: 'snap-1', dryRun });
expect(res.status).toBe(400);
expect(res.body.code).toBe('VALIDATION_ERROR');
expect(backup.restorePostgres).not.toHaveBeenCalled();
});
// Bypass probe: the rejections above must come from the schema rejecting
// those specific values, not from the request never reaching the handler.
it('accepts a well-formed body so the rejections above are not vacuous', async () => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restorePostgres.mockResolvedValue({ status: 'ok', dryRun: false });
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: 'snap-1', dryRun: false });
expect(res.status).toBe(200);
expect(backup.restorePostgres).toHaveBeenCalledWith('/dest', 'snap-1', { dryRun: false });
});
// restorePostgres reports domain failures in its resolved value rather than
// by throwing. The route must serialize those verbatim at 200 so the client
// can surface the reason — collapsing them into a 500 envelope would hide
// which check refused the restore.
it.each([
['manifest_unreadable', { status: 'failed', reason: 'manifest_unreadable' }],
['manifest_mismatch', { status: 'failed', reason: 'manifest_mismatch' }],
['restore_schema_reconciliation', { status: 'failed', reason: 'restore_schema_reconciliation', error: 'The database dump was applied, but schema recovery is incomplete. Restart PortOS.' }],
['restore_error', { status: 'failed', reason: 'restore_error', error: 'psql: exited 1' }],
['no_dump', { status: 'skipped', reason: 'no_dump' }],
['not_configured', { status: 'skipped', reason: 'not_configured' }]
])('returns the %s service result verbatim with a 200 status', async (_label, serviceResult) => {
getSettings.mockResolvedValue({ backup: { destPath: '/dest' } });
backup.restorePostgres.mockResolvedValue(serviceResult);
const res = await request(buildApp())
.post('/api/backup/restore-db')
.send({ snapshotId: 'snap-1', dryRun: false });
expect(res.status).toBe(200);
expect(res.body).toEqual(serviceResult);
});
});
});
// These requests exercise the production authorization chain before the real
// router. Mocking restore services prevents all rsync/psql, maintenance and
// settings-reload effects, and proves denied requests never reach those sinks.
describe('backup restore operator authority (#8772)', () => {
const peer = { id: 'example-peer', instanceId: 'example-instance', enabled: true, syncSecret: 'synthetic-pair-secret-for-tests-only' };
const buildGuardedApp = (remoteAddress) => {
const app = express();
app.use((req, res, next) => {
Object.defineProperty(req.socket, 'remoteAddress', { value: remoteAddress, configurable: true });
next();
});
app.use(authGate);
app.use(hostControlRouteGate);
app.use(express.json());
app.use('/api/backup', backupRoutes);
app.use(errorMiddleware);
return app;
};
beforeEach(() => {
vi.clearAllMocks();
isAuthEnabled.mockResolvedValue(false);
verifyRequestSession.mockImplementation(async (req) => ['Bearer example-operator', 'Bearer example-agent'].includes(req.headers.authorization));
verifyPassword.mockResolvedValue(false);
loadData.mockResolvedValue({ peers: [peer] });
getSettings.mockResolvedValue({ backup: { destPath: '/example-backups' } });
backup.restoreSnapshot.mockResolvedValue({ success: true });
backup.restorePostgres.mockResolvedValue({ success: true });
});
// Regression: the raw archive, its creation/deletion and deferred recovery
// must not be reachable merely because a network peer can reach PortOS.
describe.each([
['get', '/snapshots/snap-1/download', 'openSnapshotStream'],
['head', '/snapshots/snap-1/download', 'openSnapshotStream'],
['post', '/run', 'runBackup'],
['delete', '/snapshots/snap-1', 'deleteSnapshot'],
['post', '/restore-db/recover', 'resumeDatabaseRestore'],
])('%s %s operator authority', (method, path, service) => {
const sink = () => service === 'resumeDatabaseRestore' ? resumeDatabaseRestore : backup[service];
const body = method === 'post' ? { id: '00000000-0000-4000-8000-000000000001' } : undefined;
it('refuses remote and scoped-peer callers before backup effects', async () => {
for (const enabled of [false, true]) {
isAuthEnabled.mockResolvedValue(enabled);
const pending = request(buildGuardedApp('192.0.2.10'))[method]('/api/backup' + path)
.set(PEER_AUTH_HEADER, derivePeerAuthToken(peer.syncSecret, peer.instanceId))
.set(PEER_INSTANCE_HEADER, peer.instanceId);
const res = await (body ? pending.send(body) : pending);
expect(res.status).toBe(403);
expect(sink()).not.toHaveBeenCalled();
}
});
it('preserves local, human-session and delegated-agent operations', async () => {
for (const token of [null, 'example-operator', 'example-agent']) {
isAuthEnabled.mockResolvedValue(token !== null);
if (service === 'openSnapshotStream') {
const stream = new PassThrough();
stream.end('synthetic snapshot');
sink().mockResolvedValueOnce(stream);
} else sink().mockResolvedValueOnce({ success: true });
const pending = request(buildGuardedApp(token ? '192.0.2.10' : '127.0.0.1'))[method]('/api/backup' + path);
if (token) pending.set('Authorization', `Bearer ${token}`);
const res = await (body ? pending.send(body) : pending);
expect(res.status).toBe(200);
expect(sink()).toHaveBeenCalledTimes(token === null ? 1 : token === 'example-operator' ? 2 : 3);
}
});
});
describe.each([
['restore', 'restoreSnapshot'],
['restore-db', 'restorePostgres'],
])('%s', (route, service) => {
it.each([true, false])('rejects unauthorized callers before restore, dryRun=%s', async (dryRun) => {
const cases = [
{ address: '192.0.2.10', headers: {}, enabled: false, status: 403, code: 'HOST_CONTROL_FORBIDDEN' },
{ address: '192.0.2.10', headers: { 'X-Forwarded-For': '127.0.0.1', [DEV_PROXY_CLIENT_ADDRESS_HEADER]: '127.0.0.1' }, enabled: false, status: 403, code: 'HOST_CONTROL_FORBIDDEN' },
{ address: '127.0.0.1', headers: { [DEV_PROXY_CLIENT_ADDRESS_HEADER]: '192.0.2.10', 'X-Forwarded-For': '127.0.0.1' }, enabled: false, status: 403, code: 'HOST_CONTROL_FORBIDDEN' },
{ address: '127.0.0.1', headers: {}, enabled: true, status: 401, code: 'AUTH_REQUIRED' },
{ address: '192.0.2.10', headers: { [PEER_AUTH_HEADER]: derivePeerAuthToken(peer.syncSecret, peer.instanceId), [PEER_INSTANCE_HEADER]: peer.instanceId }, enabled: true, status: 403, code: 'PEER_SCOPE_FORBIDDEN' },
{ address: '127.0.0.1', headers: { Authorization: 'Basic ' + Buffer.from(':example-password').toString('base64') }, enabled: true, status: 403, code: 'HOST_CONTROL_FORBIDDEN', basic: true },
];
for (const scenario of cases) {
isAuthEnabled.mockResolvedValue(scenario.enabled);
verifyPassword.mockResolvedValue(scenario.basic === true);
const pending = request(buildGuardedApp(scenario.address)).post('/api/backup/' + route);
for (const [header, value] of Object.entries(scenario.headers)) pending.set(header, value);
const res = await pending.send({ snapshotId: 'snap-1', dryRun });
expect(res.status).toBe(scenario.status);
expect(res.body.code).toBe(scenario.code);
expect(backup.restoreSnapshot).not.toHaveBeenCalled();
expect(backup.restorePostgres).not.toHaveBeenCalled();
}
});
it.each([undefined, true, false])('preserves operator restores and dry-run defaults, dryRun=%s', async (dryRun) => {
for (const scenario of [
{ address: '127.0.0.1', headers: {}, enabled: false },
{ address: '127.0.0.1', headers: { [DEV_PROXY_CLIENT_ADDRESS_HEADER]: '::1' }, enabled: false },
{ address: '192.0.2.10', headers: { Authorization: 'Bearer example-operator' }, enabled: true },
]) {
isAuthEnabled.mockResolvedValue(scenario.enabled);
const pending = request(buildGuardedApp(scenario.address)).post('/api/backup/' + route);
for (const [header, value] of Object.entries(scenario.headers)) pending.set(header, value);
const res = await pending.send({ snapshotId: 'snap-1', dryRun });
expect(res.status).toBe(200);
expect(res.body).toEqual({ success: true });
expect(backup[service]).toHaveBeenLastCalledWith('/example-backups', 'snap-1',
expect.objectContaining({ dryRun: dryRun ?? true }));
}
});
});
});