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

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