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 { createHash, timingSafeEqual } from 'node:crypto';
import { isAuthEnabled, verifyPassword, verifyRequestSession } from './auth.js';
// Shared with sidecar processes (lib/sidecarAuthGate.js) so the Autofixer UI
// on :5560 applies byte-identical credential extraction and CSRF rules.
import { browserRequestRefusal, isLocalConnection, extractBasicPassword } from '../../lib/portosAuthCore.js';
import { getSettings, settingsEvents } from './settings.js';
import { getVoiceConfig } from './voice/config.js';
import { isRegistryPublic } from '../lib/apiRegistry.js';
import {
GATED_NON_API_PREFIXES,
isAlwaysPublicApiPath,
isPeerApiRequestAllowed,
isPeerBasicBootstrapRequest,
} from '../lib/apiAccessPolicy.js';
import { sendErrorResponse, ServerError } from '../lib/errorHandler.js';
import { logSecurityEvent } from '../lib/securityAuditLog.js';
import { isRemoteRequest } from '../lib/requestOrigin.js';
import {
changedHostControlSettingsPaths, changedVoiceConfigHostControlPaths, hostControlBodyKeys,
hostControlSettingsPathsIn, isHostControlRoute, voiceConfigHostControlPathsIn,
} from '../lib/hostControlRoutes.js';
import { derivePeerAuthToken, PEER_AUTH_HEADER, PEER_INSTANCE_HEADER } from '../lib/peerHttpClient.js';
import { loadData as loadInstances } from './instanceIdentity.js';
// Paths that bypass the auth gate even when a password is set:
// - /api/auth/status, /api/auth/whoami, /api/auth/login → the login UI
// itself needs to reach these to render and sign in.
// - /api/system/health — Tailscale's reachability check shouldn't need a
// session.
// Anything not on this list returns 401 when auth is on and the request has
// no valid token.
// Short-lived cache for successful Basic-auth scrypt results so probe cycles
// (3 parallel HTTP requests every 30s) don't re-run scrypt each time. Failed
// results are deliberately not cached so a corrected credential is retried
// immediately. Keyed by sha256 so plaintext never lives in the Map. Flushed
// on any settings write (covers password rotation).
const basicAuthCache = new Map();
const BASIC_AUTH_CACHE_TTL_MS = 60_000;
settingsEvents.on('settings:updated', () => basicAuthCache.clear());
const verifyBasicPassword = async (password) => {
if (typeof password !== 'string' || password.length === 0) return false;
const key = createHash('sha256').update(password).digest('hex');
const cached = basicAuthCache.get(key);
if (cached && cached.expiresAt > Date.now()) return cached.ok;
const ok = await verifyPassword(password);
if (ok) {
basicAuthCache.set(key, { ok: true, expiresAt: Date.now() + BASIC_AUTH_CACHE_TTL_MS });
}
return ok;
};
// A paired peer's token (#8356) resolves to its peer record. Only an enabled
// peer holding a pair secret can match; a corrupt/unreadable registry fails
// closed to "not a peer" so the request falls through to the other methods.
const pairedPeerFor = async (instanceId) => {
if (typeof instanceId !== 'string' || !instanceId) return null;
const data = await loadInstances().catch(() => null);
const peers = Array.isArray(data?.peers) ? data.peers : [];
return peers.find((p) => p?.instanceId === instanceId && p.enabled !== false
&& typeof p.syncSecret === 'string' && p.syncSecret.length >= 32) ?? null;
};
const verifyPeerToken = async (headers) => {
const token = headers?.[PEER_AUTH_HEADER.toLowerCase()];
const instanceId = headers?.[PEER_INSTANCE_HEADER.toLowerCase()];
if (typeof token !== 'string' || !token) return null;
const peer = await pairedPeerFor(instanceId);
if (!peer) return null;
const expected = Buffer.from(derivePeerAuthToken(peer.syncSecret, instanceId));
const given = Buffer.from(token);
return expected.length === given.length && timingSafeEqual(expected, given) ? peer : null;
};
// A paired peer that still authenticates with this install's password (an
// older sender, or a pair secret that differs between the two machines) is
// told once per process: the password it holds is operator authority here.
const warnedBasicPeers = new Set();
const warnIfPairedPeerUsedBasic = async (headers) => {
const instanceId = headers?.[PEER_INSTANCE_HEADER.toLowerCase()];
if (typeof instanceId !== 'string' || warnedBasicPeers.has(instanceId)) return;
const peer = await pairedPeerFor(instanceId);
if (!peer) return;
warnedBasicPeers.add(instanceId);
console.warn(`⚠️ Paired peer ${peer.name || peer.id} authenticated with the instance password instead of its pair credential — pair it again, then remove the stored password on that machine`);
};
// Logged once per peer + method + path per process (bounded): an older or
// newer peer calling outside the contract should be diagnosable without
// flooding the log.
const warnedPeerScope = new Set();
const WARNED_PEER_SCOPE_MAX = 256;
const refusePeerScope = (req, res, path, peer) => {
const key = `${peer.id} ${req.method} ${path}`;
if (!warnedPeerScope.has(key)) {
if (warnedPeerScope.size >= WARNED_PEER_SCOPE_MAX) warnedPeerScope.clear();
warnedPeerScope.add(key);
console.warn(`⛔ Peer ${peer.name || peer.id} refused outside the federation surface: ${req.method} ${path}`);
}
if (path.startsWith('/data/')) {
res.status(403).type('text/plain').send('Forbidden');
return;
}
sendErrorResponse(res, new ServerError('A peer credential only reaches the federation API.', {
status: 403, code: 'PEER_SCOPE_FORBIDDEN',
}));
};
const wakePeer = (peer) => {
if (!peer?.id) return;
import('./instances.js').then(({ wakePeerProbe }) => {
wakePeerProbe(peer);
}).catch((err) => {
console.error(`❌ Failed to wake peer probe: ${err?.message || err}`);
});
};
export const __testing = { verifyBasicPassword, wakePeer };
const BROWSER_REFUSAL_MESSAGES = {
CROSS_ORIGIN_BLOCKED: 'Cross-origin request rejected',
HOST_NOT_ALLOWED: 'Browser requests must address PortOS by an IP, a local or tailnet name, or a host listed in PORTOS_ALLOWED_HOSTS',
};
const browserRefusalError = (code) => new ServerError(BROWSER_REFUSAL_MESSAGES[code], { status: 403, code });
const isPublicPath = (path) => {
if (isAlwaysPublicApiPath(path)) return true;
// /api/* and /data/* are always gated. /sdapi/* (and any future non-/api
// API surface listed above) is also gated. Everything else is the static
// client bundle — index.html / hashed JS+CSS / fonts — which is safe to
// serve without a session: a sidecar can't do anything with it without a
// token to hit the JSON API, and the login page itself must be reachable.
if (path.startsWith('/api/') || path.startsWith('/data/')) return false;
for (const prefix of GATED_NON_API_PREFIXES) {
if (path.startsWith(prefix)) return false;
}
return true;
};
// Express middleware. The browser-relay guard (cross-origin + DNS-rebinding
// Host check) runs in both modes. With auth off everything else passes; with
// it on, allows the small public set above and gates the rest behind a valid
// token in the cookie or Authorization: Bearer header.
export const authGate = async (req, res, next) => {
const enabled = await isAuthEnabled();
// Downstream peer-provider routes need to distinguish a verified peer Basic
// credential from an interactive browser session. The global gate is the
// one authoritative verifier, so leave a request-local, non-secret marker
// instead of re-running password verification in each provider route.
req.portosAuthContext = { enabled, authenticated: false, method: null };
// App credentials authorize only this exact local broker namespace, whether
// or not the optional instance password is configured. Never exempt its admin API.
if (/^\/api\/managed-visitors\/v1(?:\/|$)/i.test(req.path)) {
const { authenticateManagedVisitorRequest } = await import('./managedVisitors.js');
req.managedVisitorAuth = await authenticateManagedVisitorRequest(req);
return next();
}
// Runs FIRST, before the auth-off bypass and isPublicPath: without a password
// any web page the user opens could otherwise relay a hidden form POST onto
// loopback (where requireHostControl trusts the socket peer), and public
// endpoints like /api/auth/logout still mutate state.
const refusal = browserRequestRefusal(req);
if (refusal) {
logSecurityEvent('request.refused', { refused: true, code: refusal, ip: req.ip, method: req.method, path: req.path, origin: req.headers?.origin, host: req.headers?.host });
sendErrorResponse(res, browserRefusalError(refusal));
return;
}
if (!enabled) {
// The pair token is independent of the instance password, so a paired peer
// stays identified after the password is removed: peer-provider routes
// (federated media) require a verified peer and never take the auth-off
// bypass. Only the federation surface is annotated; elsewhere the caller is
// as anonymous as any other request to a password-free install.
const peer = isPeerApiRequestAllowed(req.method, req.path.toLowerCase())
? await verifyPeerToken(req.headers) : null;
if (peer) {
req.portosAuthContext = { enabled: false, authenticated: true, method: 'peer', peerId: peer.id };
wakePeer(peer);
}
return next();
}
// Express mounts match case-insensitively. Use the same casing for every
// authorization check, including public exceptions, without rewriting the
// request URL: downstream record IDs and asset filenames may be case-sensitive.
const path = req.path.toLowerCase();
if (isPublicPath(path)) return next();
// Per-API public exemptions. When the user has marked an API exposed +
// passwordless in Settings (`apiAccess.<id>`), re-open ONLY its declared
// public prefix (e.g. /api/voice/public/, /sdapi/). `isRegistryPublic`
// matches only those prefixes, so config-mutation routes outside them
// (/api/voice/config, etc.) stay gated. This sits AFTER the cross-origin
// CSRF guard above (a public API is still not a CSRF bypass) and after the
// static public-path set. `getSettings()` is a cheap file read; no cache is
// introduced here so a Settings toggle takes effect on the very next request.
// A passwordless API exemption must not discard a supplied operator/agent
// session: conditional host-control handlers still need that identity.
if (await verifyRequestSession(req)) {
req.portosAuthContext = { enabled: true, authenticated: true, method: 'session' };
return next();
}
const settings = await getSettings();
if (isRegistryPublic(settings, path)) return next();
// A paired peer's scoped credential. Checked before Basic so a sender that
// presents both during the upgrade handshake is identified as the peer.
// Its authority ends at the federation surface (#8387): operator routes
// refuse it outright rather than falling through to Basic, so a peer that
// sends both never borrows the password's reach.
const peer = await verifyPeerToken(req.headers);
if (peer) {
if (!isPeerApiRequestAllowed(req.method, path)) {
refusePeerScope(req, res, path, peer);
return;
}
req.portosAuthContext = { enabled: true, authenticated: true, method: 'peer', peerId: peer.id };
wakePeer(peer);
return next();
}
// Also accept HTTP Basic auth — the legacy peer credential, kept so unpaired
// and not-yet-upgraded peers keep federating (a paired peer that still uses
// it is warned once per process). It yields `method: 'basic'`, never a session.
// The peer sends `Authorization: Basic <base64(:password)>` (the Instances
// UI stores username + password; only the password is validated here since
// PortOS is single-user). scrypt verification is intentionally slow but runs
// in libuv's thread pool so it doesn't block the event loop.
const basicPassword = extractBasicPassword(req);
if (basicPassword && await verifyBasicPassword(basicPassword)) {
req.portosAuthContext = { enabled: true, authenticated: true, method: 'basic' };
// Pair-secret setup intentionally uses the saved instance password once to
// provision the scoped credential; this is not a fallback federation call.
if (!isPeerBasicBootstrapRequest(req.method, path)) await warnIfPairedPeerUsedBasic(req.headers);
return next();
}
// /data/* is hit directly by <img>/<audio>/<video> tags which don't show a
// structured-JSON error — return a plain 401 there. API callers expect the
// PortOS error envelope.
if (path.startsWith('/data/')) {
res.status(401).type('text/plain').send('Unauthorized');
return;
}
sendErrorResponse(res, new ServerError('Authentication required', {
status: 401, code: 'AUTH_REQUIRED',
}));
};
// Host execution needs operator authority: a peer's credential — the scoped
// peer token or the legacy Basic password — never qualifies. Password-free
// installs require a local connection (see isLocalConnection). Neither req.ip
// nor the machine-local warning acknowledgement can grant authority.
const hasHostControl = (auth, localConnection) =>
(auth?.enabled === true && auth.authenticated === true && auth.method === 'session')
|| (auth?.enabled === false && localConnection === true);
export const HOST_CONTROL_FORBIDDEN_MESSAGE = 'Host control requires an operator session, or a local connection when no password is set. Set an instance password to use it remotely.';
// A request the Tailcat ingress accepted arrives from a loopback socket, so
// the address alone would read as local; the listener's remote mark wins.
const requestIsLocalConnection = (req) => !isRemoteRequest(req)
&& isLocalConnection(req.socket?.remoteAddress, req.headers);
// Server-derived HTTP authority; never read caller-provided body fields.
export const requestHasHostControl = (req) => hasHostControl(req.portosAuthContext, requestIsLocalConnection(req));
// Re-check at tool dispatch, after any STT/LLM wait. A handshake/session that
// was valid when a turn started is not a durable grant to execute later.
export const socketHasCurrentHostControl = async (socket) => {
if (socket.disconnected === true) return false;
if (await isAuthEnabled()) {
return Boolean(await verifyRequestSession({ headers: socket.handshake?.headers || {} }));
}
return socketHasHostControl(socket);
};
const hostControlRefusal = (req) => {
logSecurityEvent('host-control.refused', { refused: true, ip: req.ip, method: req.method, path: req.originalUrl?.split('?')[0] ?? req.path, auth: req.portosAuthContext?.method ?? 'none' });
return new ServerError(HOST_CONTROL_FORBIDDEN_MESSAGE, {
status: 403, code: 'HOST_CONTROL_FORBIDDEN',
});
};
// Mount after authGate: missing context fails closed.
export const requireHostControl = (req, res, next) => {
if (requestHasHostControl(req)) return next();
sendErrorResponse(res, hostControlRefusal(req));
};
// The in-handler twin of requireHostControl, for a route that is open for
// plain records and needs operator authority only when the validated request
// would start host work (e.g. a repository link that auto-clones). Throws the
// same 403 so the route's error middleware answers it.
export const assertHostControl = (req) => {
if (!requestHasHostControl(req)) throw hostControlRefusal(req);
};
// Applies requireHostControl to every route in the audited
// HOST_CONTROL_ROUTES list (lib/hostControlRoutes.js). Mounted once, right
// after authGate, so the list — not each route file — is the one place that
// says which HTTP routes execute on the host.
export const hostControlRouteGate = (req, res, next) => (
isHostControlRoute(req.method, req.path) ? requireHostControl(req, res, next) : next()
);
// The body-slice twin, mounted right after the JSON parser: the two
// polymorphic policy stores (PUT /api/settings, PUT /api/cos/config) are
// gated only when the body names a key that changes execution policy, or
// changes the stored value of a nested settings key that picks an executable
// (HOST_CONTROL_SETTINGS_PATHS). PUT /api/voice/config is gated the same way
// when the body would change the voice agent's instructions or coding-agent
// tool (HOST_CONTROL_VOICE_CONFIG_PATHS). Those stored-value reads are
// skipped when the caller already holds host control, since the answer
// could not change.
export const hostControlBodyGate = async (req, res, next) => {
if (hostControlBodyKeys(req.method, req.path, req.body).length > 0) return requireHostControl(req, res, next);
const settingsNamed = hostControlSettingsPathsIn(req.method, req.path, req.body);
const voiceNamed = voiceConfigHostControlPathsIn(req.method, req.path, req.body);
if ((settingsNamed.length === 0 && voiceNamed.length === 0)
|| hasHostControl(req.portosAuthContext, requestIsLocalConnection(req))) return next();
if (settingsNamed.length > 0
&& changedHostControlSettingsPaths(settingsNamed, req.body, await getSettings(), req.method, req.path).length > 0) {
return requireHostControl(req, res, next);
}
if (voiceNamed.length > 0
&& changedVoiceConfigHostControlPaths(voiceNamed, req.body, await getVoiceConfig()).length > 0) {
return requireHostControl(req, res, next);
}
return next();
};
// The socket twin of requireHostControl on a password-free install, for the
// per-event re-check in socket.js (with a password set, that re-check already
// admits only a verified session to host-control events). Locality is
// recorded at the handshake by socketAuthGate; a socket that never passed the
// gate carries none and fails closed.
export const socketHasHostControl = (socket) => hasHostControl({ enabled: false }, socket.data?.portosLocalConnection);
// Socket.IO middleware. Run after a successful HTTP-side handshake — same
// `req.headers.cookie` is available on `socket.handshake.headers`. When auth
// is off, every connection is allowed; when on, the handshake must carry a
// valid cookie/header. The browser-relay guard applies in both modes.
//
// NOTE: there is intentionally NO `isRegistryPublic` check here. The public
// API surface (apiRegistry) is HTTP-only — external callers hit REST endpoints,
// not the interactive socket. The socket carries the authenticated UI session
// (voice streaming, live updates) and must stay fully gated when auth is on.
// Records which credential passed the handshake so the per-event re-check in
// socket.js (registerAuthHandlers) can tell a real operator session from a
// peer relay connection. `socket.data` always exists on a real Socket.IO
// socket; guarded here only so the plain `{ handshake }` fixtures this
// module's own tests pass in don't throw.
const markAuthMethod = (socket, method) => {
if (!socket.data) socket.data = {};
socket.data.portosAuthMethod = method;
};
// engine.io `allowRequest` for the Socket.IO server: refuses the transport
// handshake itself (polling and websocket) for a foreign or rebindable browser
// request, before socketAuthGate ever runs.
export const allowSocketRequest = (req, callback) => callback(null, browserRequestRefusal(req) === null);
export const socketAuthGate = async (socket, next) => {
if (!socket.data) socket.data = {};
// `socket.request` is the engine.io handshake request; the Tailcat ingress
// marks it remote even though the handshake address is loopback.
socket.data.portosLocalConnection = !isRemoteRequest(socket.request)
&& isLocalConnection(socket.handshake?.address, socket.handshake?.headers);
const fakeReq = { headers: socket.handshake?.headers || {} };
// Before the auth-off bypass: a foreign page must not drive shell:start /
// iterm:input on a password-free install. server/index.js also refuses the
// engine.io handshake itself with the same predicate.
const refusal = browserRequestRefusal(fakeReq);
if (refusal) {
const err = new Error(BROWSER_REFUSAL_MESSAGES[refusal]);
err.data = { code: refusal };
return next(err);
}
const enabled = await isAuthEnabled();
if (!enabled) return next();
if (await verifyRequestSession(fakeReq)) {
markAuthMethod(socket, 'session');
return next();
}
// Peer relay connections: the paired peer token, else legacy Basic. Neither
// grants operator authority — socket.js re-checks every inbound event and
// allows a peer-authenticated socket only the minimal read-only
// subscription events it needs (PEER_RELAY_ALLOWED_EVENTS).
if (await verifyPeerToken(fakeReq.headers)) {
markAuthMethod(socket, 'peer');
return next();
}
const basicPassword = extractBasicPassword(fakeReq);
if (basicPassword && await verifyBasicPassword(basicPassword)) {
markAuthMethod(socket, 'basic');
return next();
}
const err = new Error('Authentication required');
err.data = { code: 'AUTH_REQUIRED' };
next(err);
};