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 { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { createHmac, randomUUID } from 'node:crypto';
import { writeFileSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import express from 'express';
import { EventEmitter } from 'node:events';
import { request } from '../lib/testHelper.js';
import { mockPathsDataRoot } from '../lib/mockPathsDataRoot.js';
const { tempRoot, makeProxy, cleanup } = mockPathsDataRoot({ prefix: 'peer-admin-' });
vi.mock('../lib/fileUtils.js', async () => ({
...makeProxy(await vi.importActual('../lib/fileUtils.js')),
dataPath: (...segments) => join(tempRoot, ...segments),
}));
const auth = vi.hoisted(() => ({ enabled: true }));
vi.mock('../services/auth.js', () => ({
isAuthEnabled: async () => auth.enabled,
verifyRequestSession: async req => req.headers.authorization === 'Bearer test-operator',
verifyPassword: async () => true,
}));
vi.mock('../services/settings.js', () => ({ getSettings: async () => ({}), settingsEvents: new EventEmitter() }));
// Unit CI deliberately has no database; default-deny must not consult it.
vi.mock('../lib/db.js', async () => ({
...await vi.importActual('../lib/db.js'), query: vi.fn(async () => { throw new Error('Fixture database unavailable'); }),
}));
vi.mock('../lib/peerHttpClient.js', async () => ({
...await vi.importActual('../lib/peerHttpClient.js'), peerFetch: vi.fn(),
}));
// Spies sit on the seams production executors really call (see peerExecutionAdapters.js
// launchUpdate/launchRestart/installCatalog); any accidental executor integration fails
// the no-active-interruption contract. The restart and install doubles spread the actual
// module so a removed export fails here instead of passing as a phantom double.
const execution = vi.hoisted(() => ({ update: vi.fn(), restart: vi.fn(), install: vi.fn() }));
vi.mock('../services/portosSelfUpdate.js', () => ({ startPortosSelfUpdate: execution.update }));
vi.mock('../lib/detachedSpawn.js', async () => ({
...await vi.importActual('../lib/detachedSpawn.js'), spawnDetached: execution.restart,
}));
vi.mock('../services/peerCatalogInstaller.js', async () => ({
...await vi.importActual('../services/peerCatalogInstaller.js'), installPeerCatalog: execution.install,
}));
const { authGate, hostControlRouteGate } = await import('../services/authGate.js');
const { default: receiver } = await import('./peerAdministration.js');
const { default: peerAdminOperatorRoutes } = await import('./peerAdminOperator.js');
const { errorMiddleware } = await import('../lib/errorHandler.js');
const { query } = await import('../lib/db.js');
const { derivePeerAuthToken, peerFetch } = await import('../lib/peerHttpClient.js');
// Fixture peers sign the wire envelope independently of the receiving service.
const signPeerAdmin = (peer, purpose, payload) => createHmac('sha256', peer.syncSecret)
.update(`portos-peer-admin:v1:${purpose}:${JSON.stringify(payload)}`).digest('hex');
const ROOT = '/api/federation/admin/v1';
let identity;
const app = express();
app.use((req, _res, next) => {
Object.defineProperty(req.socket, 'remoteAddress', { value: '192.0.2.20', configurable: true });
next();
});
app.use(express.json());
app.use(authGate);
app.use(hostControlRouteGate);
app.use(ROOT, receiver);
app.use('/api/peer-administration', peerAdminOperatorRoutes);
app.post('/api/update/execute', (_req, res) => res.json({ unexpected: true }));
app.use(errorMiddleware);
const persistIdentity = () => writeFileSync(join(tempRoot, 'instances.json'), JSON.stringify(identity));
const operator = (path, body) => request(app).post(path).set('Authorization', 'Bearer test-operator').send(body);
const peerRequest = (endpoint, body, peer = identity.peers[0]) => request(app).post(`${ROOT}/${endpoint}`)
.set('X-PortOS-Instance-Id', peer.instanceId)
.set('X-PortOS-Peer-Auth', derivePeerAuthToken(peer.syncSecret, peer.instanceId)).send(body);
const intent = { action: 'portos.restart' };
async function grant(action = intent.action, extra = {}) {
return operator('/api/peer-administration/grants', {
peerId: identity.peers[0].id, action,
confirmedHostInstanceId: identity.self.instanceId, confirmedPeerInstanceId: identity.peers[0].instanceId,
previousGrantId: null, expiresInMinutes: 60, allowPlanning: true, ...extra,
});
}
async function preflight(target = intent) {
const response = await peerRequest('preflight', { protocolVersion: 1, challenge: randomUUID(), intent: target });
expect(response.status).toBe(200);
return response.body.payload;
}
async function plan(target = intent) {
const snapshot = await preflight(target);
const input = { protocolVersion: 1, requestId: randomUUID(), preflightId: snapshot.preflightId, grantId: snapshot.grantId, intent: target };
const response = await peerRequest('plans', input);
expect(response.status).toBe(200);
return { input, receipt: response.body.payload };
}
beforeEach(() => {
vi.restoreAllMocks();
vi.clearAllMocks();
auth.enabled = true;
identity = { self: { instanceId: randomUUID() }, peers: [
{ id: randomUUID(), instanceId: randomUUID(), name: 'Example peer', enabled: true, syncSecret: 'a'.repeat(64), address: '192.0.2.10', port: 5555 },
{ id: randomUUID(), instanceId: randomUUID(), name: 'Example peer', enabled: true, syncSecret: 'b'.repeat(64) },
] };
persistIdentity();
writeFileSync(join(tempRoot, 'peer-admin-grants.json'), JSON.stringify({ schemaVersion: 1, grants: [] }));
});
afterAll(cleanup);
describe('bounded administration through the real authority boundary', () => {
it('keeps planning grants powerless on the independently authenticated execution surface', async () => {
await grant();
const input = { protocolVersion: 1, requestId: randomUUID(), intent };
const denied = await peerRequest('execution/preflight', input);
expect(denied.status, JSON.stringify(denied.body)).toBe(403);
expect(denied.body.code).toBe('PEER_EXECUTION_GRANT_REQUIRED');
expect(query).not.toHaveBeenCalled();
expect((await request(app).post(`${ROOT}/execution/preflight`).send(input)).status).toBe(401);
expect((await peerRequest('execution/dispatch', { ...input, command: 'fixture-injection' })).status).toBe(400);
expect(execution.restart).not.toHaveBeenCalled();
expect(execution.update).not.toHaveBeenCalled();
expect(execution.install).not.toHaveBeenCalled();
});
it('defaults to deny and never elevates a peer to existing host control', async () => {
const body = { protocolVersion: 1, challenge: randomUUID(), intent };
expect((await peerRequest('preflight', body)).body.code).toBe('PEER_ADMIN_GRANT_REQUIRED');
expect((await grant()).status).toBe(200);
const peer = identity.peers[0];
const denied = await request(app).post('/api/update/execute')
.set('X-PortOS-Instance-Id', peer.instanceId)
.set('X-PortOS-Peer-Auth', derivePeerAuthToken(peer.syncSecret, peer.instanceId)).send({});
expect(denied.body.code).toBe('PEER_SCOPE_FORBIDDEN');
expect((await peerRequest('preflight', body, identity.peers[1])).body.code).toBe('PEER_ADMIN_GRANT_REQUIRED');
expect((await peerRequest('preflight', { ...body, intent: { action: 'portos.update' } })).body.code).toBe('PEER_ADMIN_GRANT_REQUIRED');
});
it('refuses anonymous, Basic, forged and peer setup callers with password on and off', async () => {
for (const enabled of [true, false]) {
auth.enabled = enabled;
const body = { protocolVersion: 1, challenge: randomUUID(), intent };
expect((await request(app).post(`${ROOT}/preflight`).send(body)).status).toBe(enabled ? 401 : 403);
expect((await request(app).post(`${ROOT}/preflight`).set('Authorization', 'Basic OnBhc3M=').send(body)).status).toBe(403);
expect((await request(app).post(`${ROOT}/preflight`).set('X-PortOS-Instance-Id', identity.peers[0].instanceId)
.set('X-PortOS-Peer-Auth', 'forged').send(body)).status).toBe(enabled ? 401 : 403);
const peer = identity.peers[0];
const setup = await request(app).post('/api/peer-administration/grants')
.set('X-PortOS-Instance-Id', peer.instanceId)
.set('X-PortOS-Peer-Auth', derivePeerAuthToken(peer.syncSecret, peer.instanceId)).send({});
expect(setup.status).toBe(403);
}
});
it('requires exact operator-confirmed identities and CAS, redacts pair binding', async () => {
expect((await grant(intent.action, { confirmedPeerInstanceId: identity.peers[1].instanceId })).body.code).toBe('PEER_ADMIN_IDENTITY_CHANGED');
const saved = await grant();
expect(saved.body.executionSupported).toBe(false);
expect(saved.body.actions.find(row => row.action === intent.action).grant.authority).toBe('operator-session');
expect(JSON.stringify(saved.body)).not.toContain('pairBinding');
expect((await grant()).body.code).toBe('PEER_ADMIN_GRANT_CHANGED');
});
it('binds preflight to a single action, grant, identity and short lifetime', async () => {
await grant();
const snapshot = await preflight();
const input = { protocolVersion: 1, requestId: randomUUID(), preflightId: snapshot.preflightId, grantId: snapshot.grantId, intent };
const changed = await grant(intent.action, { previousGrantId: snapshot.grantId });
expect(changed.status).toBe(200);
expect((await peerRequest('plans', input)).body.code).toBe('PEER_ADMIN_GRANT_CHANGED');
const next = await preflight();
vi.spyOn(Date, 'now').mockReturnValue(next.expiresAt + 1);
expect((await peerRequest('plans', { ...input, preflightId: next.preflightId, grantId: next.grantId })).body.code).toBe('PEER_ADMIN_PREFLIGHT_STALE');
});
it('suspends disabled peers and invalidates rotated pair credentials and grants', async () => {
await grant();
const old = structuredClone(identity.peers[0]);
identity.peers[0].enabled = false;
persistIdentity();
expect((await peerRequest('preflight', { protocolVersion: 1, challenge: randomUUID(), intent }, old)).status).toBe(401);
identity.peers[0].enabled = true;
identity.peers[0].syncSecret = 'c'.repeat(64);
persistIdentity();
expect((await peerRequest('preflight', { protocolVersion: 1, challenge: randomUUID(), intent })).body.code).toBe('PEER_ADMIN_GRANT_REQUIRED');
});
it('reconciles identical retries, rejects changed replay and challenge reuse, and isolates receipts', async () => {
await grant();
const { input, receipt } = await plan();
expect(receipt).toMatchObject({ state: 'planned', queued: false, inFlight: false, executionSupported: false });
expect((await peerRequest('plans', input)).body.payload).toEqual(receipt);
expect((await peerRequest('plans', { ...input, preflightId: randomUUID() })).body.code).toBe('PEER_ADMIN_REPLAY');
expect((await peerRequest('plans', { ...input, requestId: randomUUID() })).body.code).toBe('PEER_ADMIN_PREFLIGHT_STALE');
expect((await peerRequest('receipt', { requestId: input.requestId }, identity.peers[1])).status).toBe(404);
const snapshot = await preflight();
expect((await peerRequest('preflight', { protocolVersion: 1, challenge: snapshot.challenge, intent })).body.code).toBe('PEER_ADMIN_REPLAY');
await grant(intent.action, { previousGrantId: input.grantId, allowPlanning: false });
expect((await peerRequest('receipt', { requestId: input.requestId })).body.code).toBe('PEER_ADMIN_GRANT_REQUIRED');
});
it('rejects unsupported actions, free-form targets, injected inputs and gated catalog entries', async () => {
for (const target of [ { action: 'shell', command: 'echo injected' }, { ...intent, path: '/tmp/anything' },
{ action: 'portos.update', tag: 'v1; echo injected' },
{ action: 'catalog.install', backend: 'ollama', catalogKey: '../../model' },
{ action: 'catalog.install', backend: 'ollama', catalogKey: 'example', url: 'https://example.com/code' } ]) {
expect((await peerRequest('preflight', { protocolVersion: 1, challenge: randomUUID(), intent: target })).status).toBe(400);
}
await grant('catalog.install');
expect((await peerRequest('preflight', { protocolVersion: 1, challenge: randomUUID(),
intent: { action: 'catalog.install', backend: 'ollama', catalogKey: 'does-not-exist' } })).body.code).toBe('PEER_ADMIN_UNKNOWN_MODEL');
expect((await peerRequest('preflight', { protocolVersion: 1, challenge: randomUUID(),
intent: { action: 'catalog.install', backend: 'ollama', catalogKey: 'gemma3-4b-it' } })).body.code).toBe('PEER_ADMIN_MODEL_UNSUPPORTED');
const model = await preflight({ action: 'catalog.install', backend: 'ollama', catalogKey: 'phi-4-mini' });
expect(model.model).toMatchObject({ modelId: 'phi4-mini', sourceLicenseReview: 'required-locally' });
expect(model.resources).toMatchObject({ destinationDiskChecked: false, runtimeMemoryChecked: false });
expect(model.blockers).toContain('MODEL_SOURCE_LICENSE_REVIEW_REQUIRED');
});
it('cannot dispatch or interrupt active work because all executors remain unavailable', async () => {
for (const action of ['portos.update', 'portos.restart']) {
await grant(action);
const { input } = await plan({ action });
expect((await peerRequest('execute', { requestId: input.requestId })).body.code).toBe('PEER_ADMIN_EXECUTION_UNAVAILABLE');
}
expect(execution.update).not.toHaveBeenCalled();
expect(execution.restart).not.toHaveBeenCalled();
expect(execution.install).not.toHaveBeenCalled();
expect(peerFetch).not.toHaveBeenCalled();
});
it('fails closed on unknown policy schemas instead of resetting grants', async () => {
writeFileSync(join(tempRoot, 'peer-admin-grants.json'), '{"schemaVersion":99,"grants":[]}');
const response = await grant();
expect(response.body.code).toBe('PEER_ADMIN_STORE_UNAVAILABLE');
expect(readFileSync(join(tempRoot, 'peer-admin-grants.json'), 'utf8')).toContain('99');
});
it('permits revocation while disabled and expires receipts without restarting work', async () => {
await grant();
const { input, receipt } = await plan();
identity.peers[0].enabled = false;
persistIdentity();
expect((await grant(intent.action, { previousGrantId: input.grantId, allowPlanning: false })).status).toBe(200);
identity.peers[0].enabled = true;
persistIdentity();
vi.spyOn(Date, 'now').mockReturnValue(receipt.expiresAt + 1);
expect((await peerRequest('receipt', { requestId: input.requestId })).body.code).toBe('PEER_ADMIN_PLAN_NOT_FOUND');
expect(execution.restart).not.toHaveBeenCalled();
});
it('completes only the signed preview exchange and does not retry an uncertain response', async () => {
const preflightId = randomUUID();
const grantId = randomUUID();
peerFetch.mockImplementation(async (url, options, peer) => {
const input = JSON.parse(options.body);
const purpose = url.endsWith('/preflight') ? 'preflight' : 'plan';
const payload = { protocolVersion: 1, scope: 'planning-v1',
targetInstanceId: peer.instanceId, senderInstanceId: identity.self.instanceId,
expiresAt: Date.now() + 60000, executionSupported: false, version: '1.0.0',
preflightId, grantId, intent: input.intent,
...(purpose === 'preflight' ? { challenge: input.challenge, observedAt: Date.now() }
: { requestId: input.requestId, state: 'planned', queued: false, inFlight: false }) };
return { ok: true, json: async () => ({ payload, signature: signPeerAdmin(peer, purpose, payload) }) };
});
const response = await operator('/api/peer-administration/preview', { peerId: identity.peers[0].id, intent });
expect(response.status).toBe(200);
expect(response.body.plan).toMatchObject({ state: 'planned', queued: false, inFlight: false });
expect(peerFetch).toHaveBeenCalledTimes(2);
expect(peerFetch.mock.calls.map(([url]) => url.split('/').at(-1))).toEqual(['preflight', 'plans']);
peerFetch.mockClear().mockRejectedValueOnce(new Error('timeout with a private network path'));
const failed = await operator('/api/peer-administration/preview', { peerId: identity.peers[0].id, intent });
expect(failed.body.code).toBe('PEER_ADMIN_UNAVAILABLE');
expect(JSON.stringify(failed.body)).not.toContain('private network path');
expect(peerFetch).toHaveBeenCalledTimes(1);
});
it('requires signed fresh remote identity and sends only the scoped pair credential', async () => {
peerFetch.mockImplementation(async (_url, options, peer) => {
expect(peer.auth).toBeNull();
expect(peer.peerAuthAccepted).toBe(true);
expect(options.headers).toEqual({ 'Content-Type': 'application/json' });
const input = JSON.parse(options.body);
const payload = { protocolVersion: 1, scope: 'planning-v1', challenge: input.challenge,
targetInstanceId: randomUUID(), senderInstanceId: identity.self.instanceId,
expiresAt: Date.now() + 60000, executionSupported: false };
return { ok: true, json: async () => ({ payload, signature: signPeerAdmin(peer, 'preflight', payload) }) };
});
const result = await operator('/api/peer-administration/preview', { peerId: identity.peers[0].id, intent });
expect(result.body.code).toBe('PEER_ADMIN_UNVERIFIED_RESPONSE');
expect(peerFetch).toHaveBeenCalledTimes(1);
});
});