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
/**
* portosAuthCore — zero-dependency primitives shared by the main PortOS server
* (`server/services/auth.js`, `server/services/authGate.js`) and by sidecar
* processes that must honour the same password gate (`autofixer/ui.js` via
* `lib/sidecarAuthGate.js`).
*
* Sidecars run as separate PM2 processes with their own `package.json`, so they
* cannot import the server's service layer (settings.js, zod, the error
* middleware…). Everything here is Node builtins only, no side effects at
* import time — same contract as `lib/tailscale-https.js`.
*
* The constants below are the WIRE/AT-REST format of the auth system. Changing
* SCRYPT_PARAMS, COOKIE_NAME, or the token hashing invalidates stored
* credentials/sessions across every install, so treat them as a migration.
*/
import { createHash, timingSafeEqual, scrypt } from 'node:crypto';
import { isIP } from 'node:net';
import { hostname as osHostname } from 'node:os';
import { promisify } from 'node:util';
import { PORTS } from '../server/lib/ports.js';
const scryptAsync = promisify(scrypt);
// The bundled dev proxy overwrites this with its socket peer on every API hop.
// Consumers may use it only to RESTRICT loopback access, never to grant it.
export const DEV_PROXY_CLIENT_ADDRESS_HEADER = 'x-portos-dev-proxy-client-address';
export const COOKIE_NAME = 'portos_auth';
export const SALT_BYTES = 16;
export const HASH_BYTES = 64;
export const TOKEN_BYTES = 32;
export const SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
// scrypt cost parameters per OWASP 2023 password-storage guidance for
// interactive logins. Node's default `maxmem` of 32 MiB rejects this N;
// OpenSSL needs headroom over the canonical 128·N·r working set (~128 MiB
// here), so 256 MiB is allocated.
export const SCRYPT_PARAMS = { N: 131072, r: 8, p: 1, maxmem: 256 * 1024 * 1024 };
const derivePasswordHash = async (password, salt, scryptParams) => {
const buf = await scryptAsync(password, salt, HASH_BYTES, scryptParams);
return buf.toString('hex');
};
export const hashPassword = (password, salt) =>
derivePasswordHash(password, salt, SCRYPT_PARAMS);
// Test-only: high-level auth suites verify service/middleware behavior with a
// cheap real-scrypt profile. The production hashPassword contract above stays
// pinned to SCRYPT_PARAMS so callers cannot accidentally create an incompatible
// stored credential.
export const __hashPasswordWithParamsForTests = (password, salt, scryptParams) =>
derivePasswordHash(password, salt, scryptParams);
export const constantEqual = (aHex, bHex) => {
const a = Buffer.from(aHex, 'hex');
const b = Buffer.from(bHex, 'hex');
if (a.length !== b.length) return false;
return timingSafeEqual(a, b);
};
export const hashToken = (token) => createHash('sha256').update(token).digest('hex');
// Verify a plaintext password against a stored `secrets.auth` record
// ({ enabled, passwordHash, salt }). Returns false for any incomplete record
// so callers never have to re-derive the "is this configured" checks.
export const verifyPasswordAgainst = async (auth, password) => {
if (!auth?.enabled || !auth.passwordHash || !auth.salt) return false;
if (typeof password !== 'string' || password.length === 0) return false;
return constantEqual(await hashPassword(password, auth.salt), auth.passwordHash);
};
// Parse a single cookie out of a `Cookie` header. Express doesn't ship a
// cookie parser and we only need one name — a manual parse keeps the sidecar
// dependency-free.
export const parseCookie = (cookieHeader, name) => {
if (typeof cookieHeader !== 'string') return null;
for (const part of cookieHeader.split(';')) {
const eq = part.indexOf('=');
if (eq === -1) continue;
if (part.slice(0, eq).trim() !== name) continue;
const raw = part.slice(eq + 1).trim();
// decodeURIComponent throws on malformed %XX sequences. An attacker
// sending `portos_auth=%E0` would otherwise turn every gated request into
// a 500 instead of a clean 401. Treat a malformed cookie as "no token".
try { return decodeURIComponent(raw); }
catch { return null; }
}
return null;
};
export const parseCookieToken = (cookieHeader) => parseCookie(cookieHeader, COOKIE_NAME);
// Cookies are scoped by host, NOT port (RFC 6265 §8.5). Two PortOS installs a
// browser reaches on the same host — e.g. a Mac's own PortOS on
// https://127.0.0.1:5555 and a remote box tunnelled to http://127.0.0.1:15555
// by `tailcat forward` — used to share one `portos_auth` cookie slot, so each
// login clobbered the other's session. Worse: once the HTTPS install stored a
// `Secure` `portos_auth`, browsers that treat http://127.0.0.1 as insecure
// (Safari/WebKit, Firefox) refuse to let the plain-HTTP install set a cookie
// of the same name at all ("leave secure cookies alone", RFC 6265bis §5.7),
// so its login succeeded server-side and the SPA bounced straight back to
// /login with no cookie stored. The session cookie name therefore carries the
// port the browser used (from `Host`), falling back to the legacy bare name
// when the origin uses the scheme's default port. Readers accept every
// PortOS session cookie (legacy + any port-scoped one) and verify each, so
// a sidecar on another port (Autofixer UI on :5560) still inherits the main
// UI's session, and a foreign install's cookie is simply not a valid token.
const SCOPED_COOKIE_RE = /^portos_auth_(\d{1,5})$/;
// Bound the per-request work a hostile Cookie header can cause.
const MAX_SESSION_COOKIES = 8;
export const sessionCookieNameFor = (hostHeader) => {
if (typeof hostHeader !== 'string') return COOKIE_NAME;
const match = /:(\d{1,5})$/.exec(hostHeader.trim());
if (!match) return COOKIE_NAME;
const port = Number(match[1]);
if (!Number.isInteger(port) || port < 1 || port > 65535) return COOKIE_NAME;
return `${COOKIE_NAME}_${port}`;
};
export const isSessionCookieName = (name) => name === COOKIE_NAME || SCOPED_COOKIE_RE.test(name);
// Every PortOS session cookie value in a `Cookie` header, in header order,
// de-duplicated. `{ name, value }` so callers can tell legacy from scoped.
export const parseSessionCookies = (cookieHeader) => {
const found = [];
if (typeof cookieHeader !== 'string') return found;
const seen = new Set();
for (const part of cookieHeader.split(';')) {
if (found.length >= MAX_SESSION_COOKIES) break;
const eq = part.indexOf('=');
if (eq === -1) continue;
const name = part.slice(0, eq).trim();
if (!isSessionCookieName(name)) continue;
let value;
try { value = decodeURIComponent(part.slice(eq + 1).trim()); }
catch { continue; }
if (!value || seen.has(`${name}=${value}`)) continue;
seen.add(`${name}=${value}`);
found.push({ name, value });
}
return found;
};
const bearerToken = (req) => {
const authHeader = req.headers?.authorization;
// RFC 6750: the Bearer scheme name is case-insensitive.
if (typeof authHeader === 'string' && authHeader.length > 7
&& authHeader.slice(0, 7).toLowerCase() === 'bearer ') {
return authHeader.slice(7).trim() || null;
}
return null;
};
// Every candidate session token on a request: all PortOS session cookies
// (the one for this request's own port first), then `Authorization: Bearer`.
// Callers must accept the request if ANY candidate verifies — a stale or
// foreign cookie must not mask a valid one.
export const extractTokens = (req) => {
const own = sessionCookieNameFor(req.headers?.host);
const cookies = parseSessionCookies(req.headers?.cookie);
const ordered = [
...cookies.filter((c) => c.name === own),
...cookies.filter((c) => c.name !== own),
].map((c) => c.value);
const bearer = bearerToken(req);
if (bearer) ordered.push(bearer);
return [...new Set(ordered)];
};
// Pull the first candidate session token from a request — cookie first, then
// `Authorization: Bearer`. Bearer support lets curl/scripts authenticate
// without juggling cookies. Header names are lowercased by both Node's HTTP
// parser and Socket.IO's handshake, so no uppercase fallback is needed.
// Prefer `extractTokens` + verify-any for authorization decisions.
export const extractToken = (req) => extractTokens(req)[0] ?? null;
// Extract the password from an `Authorization: Basic <base64>` header. PortOS
// is single-user so the username is ignored; only the password is validated.
// Used by peer-to-peer federation probes and by scripts hitting a sidecar.
export const extractBasicPassword = (req) => {
const authHeader = req.headers?.authorization;
if (typeof authHeader !== 'string') return null;
if (authHeader.slice(0, 6).toLowerCase() !== 'basic ') return null;
const decoded = Buffer.from(authHeader.slice(6), 'base64').toString('utf8');
const colonIdx = decoded.indexOf(':');
return colonIdx === -1 ? decoded : decoded.slice(colonIdx + 1);
};
// Reject cross-origin browser requests in both auth modes (see
// browserRequestRefusal below). PortOS reflects `Origin` with
// `Access-Control-Allow-Credentials: true` so the UI works from any tailnet
// hostname / IP — but combined with the session cookie that becomes a CSRF
// surface: a malicious page on another tailnet host can fetch PortOS APIs with
// `credentials: 'include'` after the user has logged in (Tailscale's `ts.net`
// is on the Public Suffix List, so SameSite=Lax doesn't help — same-tailnet
// hosts are same-site). Compare the `Origin` header's host:port against the
// request's own `Host`; any mismatch is cross-origin. Requests with no
// `Origin` (server-to-server, curl, the loopback mirror) pass through.
// Hostnames are case-insensitive (RFC 3986 §3.2.2).
const stripPort = (hostHeader) => {
// Bracketed IPv6 host: `[::1]:port` → `[::1]`.
if (hostHeader.startsWith('[')) {
const close = hostHeader.indexOf(']');
return close === -1 ? hostHeader : hostHeader.slice(0, close + 1);
}
const colon = hostHeader.indexOf(':');
return colon === -1 ? hostHeader : hostHeader.slice(0, colon);
};
const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
const isLoopback = (hostname) => LOOPBACK_HOSTS.has(hostname.toLowerCase());
// The port in a `host[:port]` authority, or '' when absent (the scheme default).
const portOf = (authority) => /:(\d+)$/.exec(authority)?.[1] ?? '';
// Ports a PortOS-served page can originate from: the API (HTTPS/HTTP), its
// loopback HTTP mirror, the Vite dev server and the Autofixer UI — plus the
// ecosystem overrides for each.
const isPortosLoopbackPort = (originPort, hostPort) => {
if (originPort === hostPort) return true;
const env = process.env;
const own = [PORTS.API, PORTS.API_LOCAL, PORTS.UI, PORTS.AUTOFIXER_UI, env.PORT, env.PORTOS_HTTP_PORT, env.VITE_PORT];
return own.some((port) => port !== undefined && port !== '' && String(port) === originPort);
};
export const isCrossOrigin = (req) => {
const origin = req.headers?.origin;
if (!origin) return false;
// An opaque origin (sandboxed iframe, data: URL, cross-origin redirect) is
// never this install's own UI — a hidden sandboxed form would otherwise slip
// through as "no Origin".
if (origin === 'null') return true;
const host = req.headers?.host;
if (!host) return false;
// URL parses scheme://authority — we only compare the authority. A malformed
// Origin (URL constructor throws) is treated as cross-origin.
let parsed;
try { parsed = new URL(origin); }
catch { return true; }
if (parsed.host.toLowerCase() === host.toLowerCase()) return false;
// Dev/sidecar workflow exemption: Vite proxies :5554 → :5555 with
// changeOrigin, and the autofixer UI on :5560 is opened from the main UI —
// so a real same-machine browser request can arrive as
// `Origin: http://localhost:5554` / `Host: localhost:5555`. Treat a
// loopback-to-loopback pairing as same-origin only when the page is served by
// PortOS itself (one of its own ports, or the very port being addressed under
// another loopback name). Any other loopback port is a DIFFERENT principal — a
// managed app, a dev server, a hostile local page — and must not borrow the
// session cookie or the loopback trust that password-free host control rests on.
if (isLoopback(stripPort(parsed.host)) && isLoopback(stripPort(host))
&& isPortosLoopbackPort(portOf(parsed.host), portOf(host))) return false;
return true;
};
// DNS rebinding defeats the Origin-vs-Host comparison above: a hostname the
// attacker controls resolves to this machine, so the page's Origin and the
// request's Host match. A browser request therefore must also address PortOS
// by a name no public site can rebind — an IP literal, a single-label name
// (`localhost`, a MagicDNS short name), a private-use suffix, the machine's
// own hostname, its configured PORTOS_HOST, or an operator-listed name in
// PORTOS_ALLOWED_HOSTS (comma-separated; a leading dot allows every subdomain).
const PRIVATE_HOST_SUFFIXES = ['.localhost', '.ts.net', '.local', '.home.arpa', '.internal', '.lan'];
const normalizeHostname = (value) => stripPort(String(value).trim().toLowerCase()).replace(/\.$/, '');
const configuredHosts = (env) => [env?.PORTOS_HOST, env?.PORTOS_ALLOWED_HOSTS].filter(Boolean).join(',')
.split(',').map((entry) => entry.trim())
.map((entry) => (entry.startsWith('.') ? `.${normalizeHostname(entry.slice(1))}` : normalizeHostname(entry)))
.filter((entry) => entry && entry !== '.');
const MACHINE_HOSTNAME = osHostname();
export const isAllowedHost = (hostHeader, { env = process.env, machineHostname = MACHINE_HOSTNAME } = {}) => {
if (typeof hostHeader !== 'string' || !hostHeader.trim()) return false;
const host = normalizeHostname(hostHeader);
if (!host) return false;
if (isIP(host) || (host.startsWith('[') && isIP(host.slice(1, -1)) === 6)) return true;
if (!host.includes('.')) return true;
if (PRIVATE_HOST_SUFFIXES.some((suffix) => host.endsWith(suffix))) return true;
if (typeof machineHostname === 'string' && host === machineHostname.toLowerCase().replace(/\.$/, '')) return true;
return configuredHosts(env).some((entry) => (entry.startsWith('.')
? host.endsWith(entry) || host === entry.slice(1)
: host === entry));
};
// Browsers stamp every request with `Sec-Fetch-Site` and every cross-origin or
// state-changing one with `Origin`; curl, agents, peers, and native companion
// apps send neither, so they never reach the checks below.
export const isBrowserRequest = (req) => Boolean(req.headers?.origin || req.headers?.['sec-fetch-site']);
// The browser-relay guard. Applies whether or not the optional password is
// set: without it, any page the user opens could drive loopback APIs (a
// hidden form POST needs no preflight). Returns the refusal code, or null
// when the request may proceed.
export const browserRequestRefusal = (req, options) => {
if (!isBrowserRequest(req)) return null;
if (isCrossOrigin(req)) return 'CROSS_ORIGIN_BLOCKED';
if (!isAllowedHost(req.headers?.host, options)) return 'HOST_NOT_ALLOWED';
return null;
};
// The Vite dev proxy (:5554 → :5555, changeOrigin) rewrites Host to the API
// target but forwards the browser's Origin, so a tailnet browser on
// `https://<name>.ts.net:5554` would look cross-origin to the API. The proxy
// vouches for a request that is same-origin to ITSELF by re-stamping Origin as
// the target's; a foreign Origin is forwarded untouched and the API refuses it.
// Returns the Origin to forward, or null to leave the header alone.
export const devProxyForwardedOrigin = (req, target) => {
if (!req.headers?.origin || isCrossOrigin(req)) return null;
return new URL(target).origin;
};
// Sliding-window login throttle. Auth is normally tailnet-only so this is
// defense in depth against a sidecar burning CPU on scrypt verifications.
// In-memory only (a restart resets the counters — acceptable for a
// defense-in-depth control on a single-user install).
export const createLoginThrottle = ({ maxAttempts = 10, windowMs = 60 * 1000 } = {}) => {
const attempts = new Map();
const trim = (timestamps, cutoff) => {
let i = 0;
while (i < timestamps.length && timestamps[i] < cutoff) i++;
return i === 0 ? timestamps : timestamps.slice(i);
};
const recentFor = (ip) => {
const cutoff = Date.now() - windowMs;
const recent = trim(attempts.get(ip) || [], cutoff);
if (recent.length === 0) attempts.delete(ip);
else attempts.set(ip, recent);
return recent;
};
return {
isLimited: (ip) => (typeof ip === 'string' && ip.length > 0
? recentFor(ip).length >= maxAttempts
: false),
recordFailure: (ip) => {
if (typeof ip !== 'string' || ip.length === 0) return;
const recent = recentFor(ip);
recent.push(Date.now());
attempts.set(ip, recent);
},
clear: (ip) => { if (typeof ip === 'string') attempts.delete(ip); },
};
};
const isLoopbackAddress = (value) => {
if (typeof value !== 'string') return false;
const address = value.replace(/^::ffff:/i, '');
return address === '::1' || (isIP(address) === 4 && address.startsWith('127.'));
};
// A loopback connection, restricted further when it carries the dev proxy's
// client-address marker: Vite proxies every browser from its own loopback
// socket, so the marker's address is the real caller. A direct remote caller
// cannot gain authority by forging a loopback marker — its connection address
// is not loopback to begin with.
export const isLocalConnection = (remoteAddress, headers) => {
const proxyClient = headers?.[DEV_PROXY_CLIENT_ADDRESS_HEADER];
return isLoopbackAddress(remoteAddress)
&& (proxyClient === undefined || isLoopbackAddress(proxyClient));
};