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

feat: measure authenticated live UI load and idle traffic in performance audits (#13101)

Adam Eivy25ce3e3cd597
diff --git a/scripts/perf/README.md b/scripts/perf/README.md
index 3ff22186db..42b471404d 100644
--- a/scripts/perf/README.md
+++ b/scripts/perf/README.md
@@ -181,6 +181,90 @@ Numeric and long-hex path segments collapse to `:id`; query strings, hosts, toke
and bodies are never retained. Fixture-unavailable APIs (503) are counted under
`unavailable`; this is shell/dashboard traffic shape, not production endpoint timing.
+Every traffic row also carries `duplicates` (same exact request repeated within a
+phase), `overlapping` (repeated while an identical request was still in flight)
+and `httpErrors` (status 400 or above); the exact URLs used to count them stay in
+memory only.
+
+## Live install audit (`liveBrowserAudit.mjs`)
+
+The synthetic fixture cannot show production fan-out: unavailable APIs return
+503 there, and its useful-content marker is only a visible shell. The live audit
+is a separate, explicitly selected workflow against this machine's running
+install. Its report says `"live": true, "synthetic": false`; never merge it with
+fixture evidence.
+
+~~~sh
+node scripts/perf/liveBrowserAudit.mjs /tmp/live-audit.json
+node scripts/perf/liveBrowserAudit.mjs --route=/messages/inbox --sibling=/messages/contacts --idle-ms=90000
+~~~
+
+Defaults: `--route=/media/history` (collection `/api/image-gen/gallery`),
+`--sibling=/media/collections`, `--idle-ms=60000` (60,000–600,000).
+`/messages/inbox` is also registered; any other static route needs
+`--collection-endpoint=/api/...`. `LIVE_AUDIT_BROWSER` optionally selects a
+Chromium executable. Phases:
+
+- `cold` — fresh browser context, cache disabled, full load of `--route`.
+ `usefulContentMs` ends when the route's collection response has finished, no
+ loading skeleton (`role=status aria-busy=true`) remains, and no HTTP request
+ is in flight; then a two-second tail catches eager follow-ups.
+- `sibling` — in-app navigation (a visible link, else the data router via
+ history) to `--sibling`, with the same completed-data rule. Refetching the
+ route's collection here is a finding.
+- `idle` — no interaction for the full window; `idleBytesPerMinute` reports
+ HTTP encoded/decoded and Socket.IO payload bytes separately.
+
+Per phase and endpoint pattern the report holds requests, completion, failure,
+cancellation, HTTP errors, duplicates, overlapping duplicates, encoded/decoded
+bytes and WebSocket frames/payload bytes, plus phase `totals`, `inFlight`
+requests at the end and `blocked` requests. Findings: `http-error`,
+`request-failed`, `overlapping-duplicate-request`, `sibling-collection-refetch`,
+`blocked-foreign-origin`, `blocked-mutation`, `in-flight-at-end` and
+`browser-stage-<phase>`. Exit 0 = measured with no findings, 1 = findings or a
+failed stage, 2 = UNVERIFIED.
+
+### Transport and authority
+
+- Origin: `PORTOS_URL`, else the agent key file's URL, else the local listener
+ (the same resolution as `scripts/portos-api.js`). Only plain-HTTP loopback
+ with no path or userinfo is accepted; with HTTPS on, use the `:5553` mirror.
+- Credential: the delegated agent session (`PORTOS_API_TOKEN`, else the Agent
+ API key file). The instance password is never used. A Node preflight sends it
+ as a bearer to that exact origin's `/api/auth/whoami` without following
+ redirects. A password-free install needs no credential and none is attached.
+- Browser: a fresh headless context with no profile and service workers
+ blocked. Before the credential enters it, a guard aborts every request and
+ WebSocket to any other origin (another loopback port included — cookies are
+ not port-scoped) and every same-origin non-GET/HEAD/OPTIONS request except
+ Socket.IO polling. The session is then installed as the install's
+ port-scoped, host-only, HttpOnly, SameSite=Strict session cookie, so the UI
+ and its Socket.IO handshake pass the normal auth gate; host-control and other
+ gates are unchanged. The audit starts no provider, sync, send or host action:
+ such writes are blocked and reported, not performed.
+- Missing or rejected credential, a non-loopback origin, an unreachable
+ install, no Chrome, or a redirect to `/login` produce `status: "unverified"`
+ with a fixed `unverified.reason` and `nextStep`; no browser is launched for
+ the preflight failures.
+
+### Redaction
+
+Labels come only from literals in server/routes: an API URL becomes its source
+route pattern (`/api/messages/:accountId/:messageId`); an unmatched API path
+keeps only its mount (`/api/image-gen/:unmatched`); `/assets/` and `/data/`
+collapse; pages other than `/`, `--route` and `--sibling` become `/:page` or
+`/:static`; other origins become `:foreign-origin`. Hosts, ports, queries,
+headers, cookies, bodies and frames are never stored. Playwright errors become
+fixed stage codes. Tests, from `server/`:
+
+~~~sh
+npm test -- ../scripts/perf/liveTraffic.test.js
+~~~
+
+They cover redaction of identifiers/credentials, the exact-origin bearer
+preflight (no redirect following, decoy origin never contacted), guard order and
+request/WebSocket decisions, and UNVERIFIED reports that launch no browser.
+
### Findings
The initial synthetic run identified media contract failures tracked in #8292:
diff --git a/scripts/perf/collectionTraffic.js b/scripts/perf/collectionTraffic.js
index 692050f231..e09f65996d 100644
--- a/scripts/perf/collectionTraffic.js
+++ b/scripts/perf/collectionTraffic.js
@@ -13,13 +13,22 @@ export function endpointFor(rawUrl) {
}
const empty = () => ({ requests: 0, completed: 0, failed: 0, canceled: 0,
+ duplicates: 0, overlapping: 0, httpErrors: 0,
encodedBytes: 0, decodedBytes: 0, unavailable: 0, socketSentFrames: 0,
socketReceivedFrames: 0, socketSentBytes: 0, socketReceivedBytes: 0 });
-export function createTrafficAccumulator() {
+/**
+ * `label` maps a raw URL (and method) to the endpoint pattern a report may
+ * hold; the live audit passes a source-route redactor. Exact URLs are kept in
+ * memory only, to count repeats within a phase (`duplicates`) and repeats
+ * started while an identical request was still in flight (`overlapping`).
+ */
+export function createTrafficAccumulator({ label = endpointFor } = {}) {
const phases = new Map();
const requests = new Map();
const sockets = new Map();
+ const seen = new Map();
+ const inFlight = new Map();
let phase = 'cold';
const bucket = (endpoint, target = phase) => {
if (!phases.has(target)) phases.set(target, new Map());
@@ -36,6 +45,9 @@ export function createTrafficAccumulator() {
row.encodedBytes += Math.max(0, (encoded || 0) - request.encoded);
row[failed ? 'failed' : 'completed']++;
if (canceled) row.canceled++;
+ const open = (inFlight.get(request.key) || 1) - 1;
+ if (open) inFlight.set(request.key, open);
+ else inFlight.delete(request.key);
requests.delete(id);
};
return {
@@ -44,14 +56,23 @@ export function createTrafficAccumulator() {
const id = event.requestId;
if (name === 'requestWillBeSent') {
if (event.redirectResponse) finish(id, event.redirectResponse.encodedDataLength, false, false);
- const endpoint = endpointFor(event.request.url);
- requests.set(id, { endpoint, encoded: 0 });
- bucket(endpoint).requests++;
+ const method = event.request.method || 'GET';
+ const endpoint = label(event.request.url, method);
+ const key = method + ' ' + event.request.url;
+ const row = bucket(endpoint);
+ row.requests++;
+ if (!seen.has(phase)) seen.set(phase, new Set());
+ if (seen.get(phase).has(key)) row.duplicates++;
+ else seen.get(phase).add(key);
+ if (inFlight.has(key)) row.overlapping++;
+ inFlight.set(key, (inFlight.get(key) || 0) + 1);
+ requests.set(id, { endpoint, encoded: 0, key });
} else if (name === 'responseReceived') {
const request = requests.get(id);
if (request) {
const row = bucket(request.endpoint);
if (event.response.status === 503) row.unavailable++;
+ if (event.response.status >= 400) row.httpErrors++;
const headers = Math.max(0, event.response.encodedDataLength || 0);
row.encodedBytes += headers;
request.encoded += headers;
@@ -66,7 +87,7 @@ export function createTrafficAccumulator() {
request.encoded += encoded;
} else if (name === 'loadingFinished') finish(id, event.encodedDataLength, false, false);
else if (name === 'loadingFailed') finish(id, 0, true, event.canceled);
- else if (name === 'webSocketCreated') sockets.set(id, endpointFor(event.url));
+ else if (name === 'webSocketCreated') sockets.set(id, label(event.url, 'GET'));
else if (name === 'webSocketClosed') sockets.delete(id);
else if (name === 'webSocketFrameSent' || name === 'webSocketFrameReceived') {
const row = bucket(sockets.get(id) || '/socket.io/');
@@ -82,6 +103,11 @@ export function createTrafficAccumulator() {
Object.fromEntries([...endpoints].sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, { ...value }]))]));
},
pending() { return requests.size; },
+ pendingByEndpoint() {
+ const counts = new Map();
+ for (const { endpoint } of requests.values()) counts.set(endpoint, (counts.get(endpoint) || 0) + 1);
+ return Object.fromEntries([...counts].sort(([a], [b]) => a.localeCompare(b)));
+ },
};
}
diff --git a/scripts/perf/liveBrowserAudit.mjs b/scripts/perf/liveBrowserAudit.mjs
new file mode 100644
index 0000000000..2ae6bace1e
--- /dev/null
+++ b/scripts/perf/liveBrowserAudit.mjs
@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * Live-install browser traffic audit (#13101). Separate from the synthetic
+ * fixture audit: it measures the running install through a disposable browser
+ * context authorized only by the delegated agent session. See README.md
+ * "Live install audit" for the transport, redaction and exit-code contract.
+ */
+import { createRequire } from 'node:module';
+import { writeFile } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { performance } from 'node:perf_hooks';
+import { createTrafficAccumulator, idleBytesPerMinute } from './collectionTraffic.js';
+import {
+ NEXT_STEPS, createEndpointRedactor, installLiveTransport, liveFindings, parseLiveAuditArgs,
+ phaseTotals, preflightLiveTransport, resolveLiveOrigin, sameOrigin,
+} from './liveTraffic.js';
+import { requestApi, resolveCredentials } from '../portos-api.js';
+import { isDirectlyInvoked } from '../lib/directInvocation.js';
+
+const EVENTS = ['requestWillBeSent', 'responseReceived', 'dataReceived', 'loadingFinished', 'loadingFailed',
+ 'webSocketCreated', 'webSocketClosed', 'webSocketFrameSent', 'webSocketFrameReceived'];
+const STAGE_TIMEOUT_MS = 30000;
+const OBSERVATION_TAIL_MS = 2000;
+// Completed-data state: the shell is mounted and no loading skeleton
+// (PageSkeleton / Skeleton render role=status aria-busy=true) remains.
+const settled = () => document.getElementById('main-content') !== null
+ && document.querySelector('[role="status"][aria-busy="true"]') === null;
+
+// Useful content also requires no HTTP request still in flight (route chunks,
+// API reads, media): right after an in-app navigation the previous page's
+// settled DOM is still mounted, so the DOM check alone would pass early.
+async function waitForUsefulContent(page, traffic, signal) {
+ const deadline = performance.now() + STAGE_TIMEOUT_MS;
+ await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+ for (;;) {
+ if (traffic.pending() === 0 && await page.evaluate(settled)) return;
+ if (performance.now() > deadline) throw new Error('useful content not reached');
+ await delay(50, undefined, { signal });
+ }
+}
+
+// Prefer a real in-app link (what a user clicks); otherwise drive the data
+// router through history so the shell is not reloaded.
+async function navigateInApp(page, path) {
+ const link = page.locator(`a[href="${path}"]`).filter({ visible: true }).first();
+ if (await link.count()) {
+ await link.click();
+ return 'link';
+ }
+ await page.evaluate(target => {
+ history.pushState({ usr: null, key: 'live-audit', idx: (history.state?.idx ?? 0) + 1 }, '', target);
+ dispatchEvent(new PopStateEvent('popstate', { state: history.state }));
+ }, path);
+ return 'history';
+}
+
+async function measure({ browser, origin, token, args, catalog, report, signal }) {
+ const redact = createEndpointRedactor({ origin, pages: [args.route, args.sibling], catalog });
+ const collectionPattern = redact(origin + args.collectionEndpoint);
+ const traffic = createTrafficAccumulator({ label: redact });
+ const blocked = new Map();
+ let phase = 'cold';
+ const advance = name => { phase = name; traffic.setPhase(name); };
+ const scenario = report.scenario = { usefulContentMs: null, siblingUsefulContentMs: null, siblingNavigation: null, idleMs: null };
+ const findings = [];
+ const context = await browser.newContext({ viewport: { width: 1280, height: 800 }, serviceWorkers: 'block' });
+ try {
+ await installLiveTransport(context, {
+ origin, token,
+ onBlocked: (reason, url, method) => {
+ const key = [phase, reason, redact(url, method)].join('\0');
+ blocked.set(key, (blocked.get(key) || 0) + 1);
+ },
+ });
+ const page = await context.newPage();
+ page.setDefaultTimeout(STAGE_TIMEOUT_MS);
+ const cdp = await context.newCDPSession(page);
+ for (const name of EVENTS) cdp.on('Network.' + name, event => traffic.event(name, event));
+ await cdp.send('Network.enable');
+ await cdp.send('Network.setCacheDisabled', { cacheDisabled: true });
+ try {
+ const started = performance.now();
+ const collection = page.waitForResponse(response => response.request().method() === 'GET'
+ && sameOrigin(response.url(), origin) && new URL(response.url()).pathname === args.collectionEndpoint,
+ { timeout: STAGE_TIMEOUT_MS }).catch(() => null);
+ await page.goto(origin + args.route, { waitUntil: 'domcontentloaded' });
+ const response = await collection;
+ if (new URL(page.url()).pathname === '/login') {
+ report.status = 'unverified';
+ report.unverified = { reason: 'login-redirect', nextStep: NEXT_STEPS['login-redirect'] };
+ return;
+ }
+ if (!response) throw new Error('collection response not observed');
+ if (!response.ok()) findings.push({ phase, endpoint: collectionPattern, reason: 'collection-http-status', count: response.status() });
+ await response.finished();
+ await waitForUsefulContent(page, traffic, signal);
+ scenario.usefulContentMs = Math.round(performance.now() - started);
+ // A fixed tail catches eager follow-up fetches; networkidle would hide
+ // recurring requests behind its own timeout.
+ await delay(OBSERVATION_TAIL_MS, undefined, { signal });
+
+ advance('sibling');
+ const siblingStarted = performance.now();
+ scenario.siblingNavigation = await navigateInApp(page, args.sibling);
+ await page.waitForFunction(target => location.pathname === target, args.sibling);
+ await waitForUsefulContent(page, traffic, signal);
+ scenario.siblingUsefulContentMs = Math.round(performance.now() - siblingStarted);
+ await delay(OBSERVATION_TAIL_MS, undefined, { signal });
+
+ advance('idle');
+ const idleStarted = performance.now();
+ await delay(args.idleMs, undefined, { signal });
+ scenario.idleMs = Math.round(performance.now() - idleStarted);
+ report.status = 'verified';
+ } catch {
+ // Playwright errors carry URLs, DOM text and paths: only the stage crosses.
+ report.status = 'failed';
+ findings.push({ phase, endpoint: 'browser', reason: 'browser-stage-' + phase, count: 1 });
+ }
+ } finally {
+ scenario.phases = traffic.snapshot();
+ scenario.totals = phaseTotals(scenario.phases);
+ scenario.inFlight = traffic.pendingByEndpoint();
+ scenario.blocked = [...blocked].map(([key, count]) => {
+ const [blockedPhase, reason, endpoint] = key.split('\0');
+ return { phase: blockedPhase, reason, endpoint, count };
+ });
+ if (scenario.idleMs) scenario.idleBytesPerMinute = idleBytesPerMinute(scenario.phases.idle, scenario.idleMs);
+ report.findings.push(...findings, ...liveFindings({ phases: scenario.phases, inFlight: scenario.inFlight,
+ blocked: scenario.blocked, collectionEndpoint: collectionPattern }));
+ await context.close().catch(() => report.findings.push({ phase: 'end', endpoint: 'browser', reason: 'context-cleanup', count: 1 }));
+ }
+}
+
+/**
+ * Returns an aggregate report; never throws for an expected environment gap.
+ * status: 'verified' (measured), 'failed' (a stage broke), 'unverified'
+ * (no authorized transport; `unverified.nextStep` says what to do).
+ */
+export async function runLiveAudit({ args, env = process.env, chromium, catalog, request = requestApi, signal } = {}) {
+ const report = {
+ version: 1, kind: 'live-browser-audit', live: true, synthetic: false, status: 'unverified',
+ route: args.route, sibling: args.sibling, collectionEndpoint: args.collectionEndpoint, idleTargetMs: args.idleMs,
+ transport: null, scenario: null, findings: [],
+ };
+ const unverified = reason => {
+ report.unverified = { reason, nextStep: NEXT_STEPS[reason] };
+ return report;
+ };
+ const { url, token } = await resolveCredentials(env);
+ let origin;
+ try { origin = resolveLiveOrigin(url); } catch (error) { return unverified(error.reason || 'invalid-origin'); }
+ const preflight = await preflightLiveTransport({ origin, token, request });
+ if (!preflight.ok) return unverified(preflight.reason);
+ const delegated = preflight.mode === 'delegated-session';
+ report.transport = {
+ mode: preflight.mode, origin: 'loopback-http',
+ credentialSource: !delegated ? 'none' : env.PORTOS_API_TOKEN ? 'PORTOS_API_TOKEN' : 'agent-key-file',
+ };
+ let browser;
+ try {
+ browser = await chromium.launch({ headless: true, ...(env.LIVE_AUDIT_BROWSER
+ ? { executablePath: env.LIVE_AUDIT_BROWSER } : { channel: 'chrome' }) });
+ } catch { return unverified('browser-unavailable'); }
+ try {
+ await measure({ browser, origin, token: delegated ? token : null, args, catalog, report, signal });
+ } catch {
+ report.status = 'failed';
+ report.findings.push({ phase: 'setup', endpoint: 'browser', reason: 'browser-setup', count: 1 });
+ } finally {
+ await browser.close().catch(() => report.findings.push({ phase: 'end', endpoint: 'browser', reason: 'cleanup', count: 1 }));
+ }
+ return report;
+}
+
+/** 0 measured with no findings, 1 findings or a failed stage, 2 UNVERIFIED. */
+export const exitCodeFor = report => report.status === 'unverified' ? 2
+ : report.status === 'verified' && report.findings.length === 0 ? 0 : 1;
+
+if (isDirectlyInvoked(import.meta.url)) {
+ let args;
+ try { args = parseLiveAuditArgs(process.argv.slice(2)); } catch (error) {
+ console.error(`❌ ${error.message}`);
+ process.exit(1);
+ }
+ const { chromium } = createRequire(new URL('../../server/package.json', import.meta.url))('playwright-core');
+ const abort = new AbortController();
+ const stop = () => abort.abort();
+ process.once('SIGINT', stop);
+ process.once('SIGTERM', stop);
+ const report = await runLiveAudit({ args, chromium, signal: abort.signal });
+ process.removeListener('SIGINT', stop);
+ process.removeListener('SIGTERM', stop);
+ report.passed = exitCodeFor(report) === 0;
+ process.exitCode = exitCodeFor(report);
+ const serialized = JSON.stringify(report, null, 2) + '\n';
+ try {
+ if (args.output) await writeFile(args.output, serialized, { flag: 'wx' });
+ else process.stdout.write(serialized);
+ } catch {
+ console.error('❌ Could not write aggregate report; choose a new writable output file.');
+ process.exitCode = 1;
+ }
+}
diff --git a/scripts/perf/liveTraffic.js b/scripts/perf/liveTraffic.js
new file mode 100644
index 0000000000..549292ed5b
--- /dev/null
+++ b/scripts/perf/liveTraffic.js
@@ -0,0 +1,205 @@
+/**
+ * Live-install browser audit policy (#13101). The synthetic fixture audit
+ * (collectionTraffic.js) proves traffic shape against a disposable origin; this
+ * module scopes a delegated session to exactly one loopback PortOS origin and
+ * labels every URL by a source-declared pattern, so no record identifier,
+ * query, host, header or credential can reach a report.
+ */
+import { getApiRouteCatalog } from '../../server/lib/apiRouteGraph.js';
+import { sessionCookieNameFor } from '../../lib/portosAuthCore.js';
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const PAGE_PATH = /^(?:\/[a-z0-9][a-z0-9-]*)+$/;
+const API_PATH = /^\/api(?:\/[a-z0-9][a-z0-9-]*)+$/;
+
+/** Large-collection routes and the list endpoint whose completion marks useful content. */
+export const COLLECTION_ROUTES = Object.freeze({
+ '/media/history': '/api/image-gen/gallery',
+ '/messages/inbox': '/api/messages/inbox',
+});
+
+/** Fixed operator guidance per UNVERIFIED reason; never interpolates environment values. */
+export const NEXT_STEPS = Object.freeze({
+ 'invalid-origin': 'Set PORTOS_URL to this machine\'s loopback HTTP origin (for example http://127.0.0.1:5553), then rerun.',
+ 'non-loopback-origin': 'Live audits target only this machine\'s loopback HTTP origin; set PORTOS_URL to it (the :5553 mirror when HTTPS is on), then rerun.',
+ 'origin-unreachable': 'Start PortOS or point PORTOS_URL at its loopback HTTP origin (the :5553 mirror when HTTPS is on), then rerun.',
+ 'whoami-unreadable': 'The origin did not answer /api/auth/whoami as PortOS; check PORTOS_URL names this install, then rerun.',
+ 'credential-missing': 'Run from a PortOS-spawned agent (PORTOS_API_TOKEN) or enable Settings > Security > Agent API key, then rerun.',
+ 'credential-rejected': 'The delegated session was rejected (expired or revoked); respawn the agent or re-enable the Agent API key, then rerun.',
+ 'browser-unavailable': 'Install Google Chrome or set LIVE_AUDIT_BROWSER to a Chromium executable, then rerun.',
+ 'login-redirect': 'The audit browser was sent to /login, so the delegated session cookie was not accepted; verify the credential with `node scripts/portos-api.js whoami`, then rerun.',
+});
+
+export const refusal = reason => Object.assign(new Error(reason), { reason });
+
+/** The exact origin a live audit may contact: plain-HTTP loopback with no path or userinfo. */
+export function resolveLiveOrigin(raw) {
+ let url;
+ try { url = new URL(raw); } catch { throw refusal('invalid-origin'); }
+ if (url.username || url.password || !['', '/'].includes(url.pathname) || url.search || url.hash) throw refusal('invalid-origin');
+ if (url.protocol !== 'http:' || !LOOPBACK_HOSTS.has(url.hostname)) throw refusal('non-loopback-origin');
+ return url.origin;
+}
+
+/** Exact scheme/host/port equality, treating ws: as http: (the Socket.IO upgrade). */
+export function sameOrigin(raw, origin) {
+ let url;
+ try { url = new URL(raw); } catch { return false; }
+ const scheme = { 'ws:': 'http:', 'wss:': 'https:' }[url.protocol] || url.protocol;
+ return `${scheme}//${url.host}` === origin;
+}
+
+/**
+ * 'allow' only for same-origin safe reads (and Socket.IO polling writes, the
+ * transport itself). Anything else is refused before it leaves the browser:
+ * a foreign origin could receive the cookie or observe the audit, and a
+ * mutation could start a provider, sync, send or host action.
+ */
+export function classifyBrowserRequest({ url, method, origin }) {
+ if (!sameOrigin(url, origin)) return 'foreign-origin';
+ if (SAFE_METHODS.has(String(method).toUpperCase())) return 'allow';
+ return new URL(url).pathname.startsWith('/socket.io/') ? 'allow' : 'mutation';
+}
+
+const compileRoute = path => new RegExp('^' + path.split('/').map(segment =>
+ segment.startsWith(':') ? '[^/]+' : segment.startsWith('*') ? '.+'
+ : segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('/') + '/?$');
+
+/**
+ * URL -> report label. API paths become the matching source route pattern
+ * (`/api/messages/:accountId/:messageId`), so a label only ever contains
+ * literals declared in server/routes; unmatched API paths keep only their
+ * mount. Pages keep only the operator-chosen static paths. Hosts, queries and
+ * every other segment value are dropped.
+ */
+export function createEndpointRedactor({ origin, pages = [], catalog = getApiRouteCatalog() }) {
+ const routes = catalog.routes.map(({ method, path }) => ({
+ method, path, re: compileRoute(path),
+ statics: path.split('/').filter(segment => segment && !/^[:*]/.test(segment)).length,
+ }));
+ const mounts = [...new Set(catalog.mounts)].sort((a, b) => b.length - a.length);
+ const knownPages = new Set(['/', ...pages]);
+ return (raw, method = 'GET') => {
+ let url;
+ try { url = new URL(raw); } catch { return '/invalid-url'; }
+ if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) return '/non-http';
+ if (!sameOrigin(raw, origin)) return ':foreign-origin';
+ const path = url.pathname;
+ if (path === '/socket.io' || path.startsWith('/socket.io/')) return '/socket.io/';
+ if (path.startsWith('/assets/')) return '/assets/:asset';
+ if (path.startsWith('/data/')) return '/data/:asset';
+ if (/^\/(?:api|sdapi)(?:\/|$)/.test(path)) {
+ const verb = String(method).toUpperCase() === 'HEAD' ? 'GET' : String(method).toUpperCase();
+ let best = null;
+ for (const route of routes) {
+ if (!route.re.test(path)) continue;
+ const rank = [route.method === verb ? 1 : 0, route.statics];
+ if (!best || rank[0] > best.rank[0] || (rank[0] === best.rank[0] && rank[1] > best.rank[1])) best = { route, rank };
+ }
+ if (best) return best.route.path;
+ const mount = mounts.find(prefix => path === prefix || path.startsWith(prefix + '/'));
+ return (mount || (path.startsWith('/sdapi') ? '/sdapi' : '/api')) + '/:unmatched';
+ }
+ if (knownPages.has(path)) return path;
+ return /^\/[^/]+\.[a-z0-9]+$/i.test(path) ? '/:static' : '/:page';
+ };
+}
+
+/**
+ * Install the transport on a fresh, disposable browser context. The guard is
+ * registered before the credential exists in the context. The session cookie is
+ * host-only and HttpOnly; cookies are not port-scoped, so the guard (not the
+ * cookie jar) is what keeps it from another loopback port: every request and
+ * WebSocket to a different origin is aborted before it is sent.
+ */
+export async function installLiveTransport(context, { origin, token, onBlocked }) {
+ await context.route(() => true, async route => {
+ const request = route.request();
+ const decision = classifyBrowserRequest({ url: request.url(), method: request.method(), origin });
+ if (decision === 'allow') return route.continue();
+ onBlocked(decision, request.url(), request.method());
+ return route.abort('blockedbyclient');
+ });
+ await context.routeWebSocket(url => !sameOrigin(url.href, origin), ws => {
+ onBlocked('foreign-origin', ws.url(), 'GET');
+ return ws.close({ code: 1008, reason: 'live audit origin guard' });
+ });
+ if (token) {
+ await context.addCookies([{ name: sessionCookieNameFor(new URL(origin).host), value: token,
+ url: origin, httpOnly: true, sameSite: 'Strict' }]);
+ }
+}
+
+/**
+ * Confirm the credential against the exact origin before any browser starts.
+ * `request` is portos-api's requestApi: no redirect following, so the bearer
+ * cannot be forwarded to another location.
+ */
+export async function preflightLiveTransport({ origin, token, request }) {
+ const headers = { Accept: 'application/json' };
+ if (token) headers.Authorization = `Bearer ${token}`;
+ let response;
+ try {
+ response = await request(`${origin}/api/auth/whoami`, { method: 'GET', headers, body: null, timeoutMs: 10000 });
+ } catch { return { ok: false, reason: 'origin-unreachable' }; }
+ let body = null;
+ try { body = JSON.parse(response.text); } catch { /* handled below */ }
+ if (response.status !== 200 || typeof body?.required !== 'boolean') return { ok: false, reason: 'whoami-unreadable' };
+ if (!body.required) return { ok: true, mode: 'password-free' };
+ if (body.authenticated === true && token) return { ok: true, mode: 'delegated-session' };
+ return { ok: false, reason: token ? 'credential-rejected' : 'credential-missing' };
+}
+
+/** Findings from aggregate live traffic; inputs and outputs carry only patterns and counts. */
+export function liveFindings({ phases, inFlight, blocked, collectionEndpoint }) {
+ const findings = [];
+ const blockedAt = new Map(blocked.map(({ phase, endpoint, count }) => [phase + '\0' + endpoint, count]));
+ for (const [phase, endpoints] of Object.entries(phases)) {
+ for (const [endpoint, row] of Object.entries(endpoints)) {
+ if (row.httpErrors) findings.push({ phase, endpoint, reason: 'http-error', count: row.httpErrors });
+ const failed = row.failed - row.canceled - (blockedAt.get(phase + '\0' + endpoint) || 0);
+ if (failed > 0) findings.push({ phase, endpoint, reason: 'request-failed', count: failed });
+ if (row.overlapping) findings.push({ phase, endpoint, reason: 'overlapping-duplicate-request', count: row.overlapping });
+ if (phase !== 'cold' && endpoint === collectionEndpoint && row.requests) {
+ findings.push({ phase, endpoint, reason: 'sibling-collection-refetch', count: row.requests });
+ }
+ }
+ }
+ for (const { phase, endpoint, reason, count } of blocked) findings.push({ phase, endpoint, reason: 'blocked-' + reason, count });
+ for (const [endpoint, count] of Object.entries(inFlight)) findings.push({ phase: 'end', endpoint, reason: 'in-flight-at-end', count });
+ return findings;
+}
+
+/** Per-phase sums so a reader need not add endpoint rows. */
+export function phaseTotals(phases) {
+ return Object.fromEntries(Object.entries(phases).map(([phase, endpoints]) => [phase,
+ Object.values(endpoints).reduce((sum, row) => {
+ for (const [key, value] of Object.entries(row)) sum[key] = (sum[key] || 0) + value;
+ return sum;
+ }, {})]));
+}
+
+/** CLI: [output] [--route=/path] [--sibling=/path] [--collection-endpoint=/api/...] [--idle-ms=N]. */
+export function parseLiveAuditArgs(argv) {
+ const out = { output: undefined, route: '/media/history', sibling: '/media/collections', collectionEndpoint: null, idleMs: 60000 };
+ for (const arg of argv) {
+ const [flag, ...rest] = arg.split('=');
+ const value = rest.join('=');
+ if (flag === '--route' || flag === '--sibling') {
+ if (!PAGE_PATH.test(value)) throw new Error(flag + ' must be a static lowercase path such as /media/history');
+ out[flag.slice(2)] = value;
+ } else if (flag === '--collection-endpoint') {
+ if (!API_PATH.test(value)) throw new Error('--collection-endpoint must be a static /api path');
+ out.collectionEndpoint = value;
+ } else if (flag === '--idle-ms') {
+ out.idleMs = Number(value);
+ if (!Number.isInteger(out.idleMs) || out.idleMs < 60000 || out.idleMs > 600000) throw new Error('--idle-ms must be 60000-600000');
+ } else if (!arg.startsWith('--') && out.output === undefined) out.output = arg;
+ else throw new Error('Unknown argument: ' + flag);
+ }
+ out.collectionEndpoint ??= COLLECTION_ROUTES[out.route] ?? null;
+ if (!out.collectionEndpoint) throw new Error('--collection-endpoint is required for a route without a registered collection');
+ if (out.sibling === out.route) throw new Error('--sibling must differ from --route');
+ return out;
+}
diff --git a/scripts/perf/liveTraffic.test.js b/scripts/perf/liveTraffic.test.js
new file mode 100644
index 0000000000..f00828e116
--- /dev/null
+++ b/scripts/perf/liveTraffic.test.js
@@ -0,0 +1,171 @@
+import { createServer } from 'node:http';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createTrafficAccumulator } from './collectionTraffic.js';
+import {
+ createEndpointRedactor, installLiveTransport, liveFindings, parseLiveAuditArgs,
+ preflightLiveTransport, resolveLiveOrigin,
+} from './liveTraffic.js';
+import { exitCodeFor, runLiveAudit } from './liveBrowserAudit.mjs';
+import { requestApi } from '../portos-api.js';
+
+const ORIGIN = 'http://127.0.0.1:5553';
+const TOKEN = 'tok-example-0123456789abcdef';
+const CATALOG = {
+ mounts: ['/api/image-gen', '/api/messages'],
+ routes: [
+ { method: 'GET', path: '/api/image-gen/gallery' },
+ { method: 'GET', path: '/api/image-gen/:filename/variants' },
+ { method: 'GET', path: '/api/messages/inbox' },
+ { method: 'GET', path: '/api/messages/:accountId/:messageId' },
+ ],
+};
+
+describe('live audit redaction', () => {
+ it('reduces live URLs to source route patterns with no identifiers, queries, hosts or credentials', () => {
+ const redact = createEndpointRedactor({ origin: ORIGIN, pages: ['/media/history'], catalog: CATALOG });
+ const traffic = createTrafficAccumulator({ label: redact });
+ const urls = [
+ `${ORIGIN}/api/image-gen/gallery?limit=60&search=alice%40example.com`,
+ `${ORIGIN}/api/image-gen/portrait-of-alice.png/variants`,
+ `${ORIGIN}/api/messages/[email protected]/msg-4711`,
+ `${ORIGIN}/api/messages/inbox?token=${TOKEN}`,
+ `${ORIGIN}/api/image-gen/private-project/unknown/route`,
+ `${ORIGIN}/api/unmounted-secret/alice`,
+ `${ORIGIN}/data/images/alice-at-home.png`,
+ `${ORIGIN}/media/history?q=alice`,
+ `${ORIGIN}/brain/people/alice-example`,
+ 'http://127.0.0.1:5560/api/messages/inbox',
+ 'https://tracker.example.net/collect?u=alice',
+ ];
+ urls.forEach((url, i) => {
+ traffic.event('requestWillBeSent', { requestId: 'r' + i, request: { url, method: 'GET' } });
+ traffic.event('loadingFinished', { requestId: 'r' + i, encodedDataLength: 10 });
+ });
+ traffic.event('webSocketCreated', { requestId: 's', url: `ws://127.0.0.1:5553/socket.io/?EIO=4&sid=${TOKEN}` });
+ const phases = traffic.snapshot();
+ expect(Object.keys(phases.cold)).toEqual([':foreign-origin', '/:page', '/api/:unmatched', '/api/image-gen/:filename/variants',
+ '/api/image-gen/:unmatched', '/api/image-gen/gallery', '/api/messages/:accountId/:messageId', '/api/messages/inbox',
+ '/data/:asset', '/media/history']);
+ expect(phases.cold[':foreign-origin'].requests).toBe(2);
+ expect(JSON.stringify(phases)).not.toMatch(/alice|msg-4711|private-project|unmounted|tok-example|127\.0\.0\.1|5553|5560|example\.(com|net)/);
+ });
+
+ it('counts sequential repeats and concurrent duplicates without keeping the URL', () => {
+ const traffic = createTrafficAccumulator({ label: createEndpointRedactor({ origin: ORIGIN, catalog: CATALOG }) });
+ const send = id => traffic.event('requestWillBeSent', { requestId: id, request: { url: `${ORIGIN}/api/messages/inbox?cursor=alice`, method: 'GET' } });
+ send('a'); send('b');
+ traffic.event('loadingFinished', { requestId: 'a', encodedDataLength: 1 });
+ traffic.event('loadingFinished', { requestId: 'b', encodedDataLength: 1 });
+ send('c');
+ expect(traffic.snapshot().cold['/api/messages/inbox']).toMatchObject({ requests: 3, duplicates: 2, overlapping: 1 });
+ expect(traffic.pendingByEndpoint()).toEqual({ '/api/messages/inbox': 1 });
+ });
+
+ it('reports blocked requests once, sibling collection refetches and in-flight work as findings', () => {
+ const row = (overrides) => ({ requests: 0, failed: 0, canceled: 0, overlapping: 0, httpErrors: 0, ...overrides });
+ const findings = liveFindings({
+ phases: {
+ cold: { '/api/image-gen/gallery': row({ requests: 1 }), ':foreign-origin': row({ requests: 1, failed: 1 }) },
+ sibling: { '/api/image-gen/gallery': row({ requests: 1, httpErrors: 1 }) },
+ },
+ blocked: [{ phase: 'cold', reason: 'foreign-origin', endpoint: ':foreign-origin', count: 1 }],
+ inFlight: { '/api/settings': 1 },
+ collectionEndpoint: '/api/image-gen/gallery',
+ });
+ expect(findings.map(f => `${f.phase} ${f.reason}`)).toEqual(['sibling http-error', 'sibling sibling-collection-refetch',
+ 'cold blocked-foreign-origin', 'end in-flight-at-end']);
+ });
+});
+
+describe('live audit transport', () => {
+ const servers = [];
+ const listen = handler => new Promise(resolve => {
+ const seen = [];
+ const server = createServer((req, res) => { seen.push({ path: req.url, authorization: req.headers.authorization }); handler(req, res); });
+ servers.push(server);
+ server.listen(0, '127.0.0.1', () => resolve({ origin: `http://127.0.0.1:${server.address().port}`, seen }));
+ });
+ afterEach(async () => { await Promise.all(servers.splice(0).map(server => new Promise(resolve => server.close(resolve)))); });
+
+ it('accepts only an exact plain-HTTP loopback origin', () => {
+ expect(resolveLiveOrigin('http://127.0.0.1:5553/')).toBe(ORIGIN);
+ expect(resolveLiveOrigin('http://[::1]:5553')).toBe('http://[::1]:5553');
+ const reasons = ['https://127.0.0.1:5555', 'http://portos.example.ts.net:5555', 'http://192.0.2.10:5555',
+ 'http://user:[email protected]:5553', 'http://127.0.0.1:5553/api', 'not a url'].map(raw => {
+ try { resolveLiveOrigin(raw); return 'accepted'; } catch (error) { return error.reason; }
+ });
+ expect(reasons).toEqual(['non-loopback-origin', 'non-loopback-origin', 'non-loopback-origin', 'invalid-origin', 'invalid-origin', 'invalid-origin']);
+ });
+
+ it('presents the bearer only to the exact origin and never follows a redirect elsewhere', async () => {
+ const decoy = await listen((req, res) => res.end('{}'));
+ const auth = await listen((req, res) => res.end(JSON.stringify({ required: true, authenticated: req.headers.authorization === `Bearer ${TOKEN}` })));
+ const redirecting = await listen((req, res) => { res.writeHead(302, { location: decoy.origin + '/api/auth/whoami' }); res.end(); });
+ const open = await listen((req, res) => res.end(JSON.stringify({ required: false, authenticated: true })));
+
+ await expect(preflightLiveTransport({ origin: auth.origin, token: TOKEN, request: requestApi })).resolves.toEqual({ ok: true, mode: 'delegated-session' });
+ await expect(preflightLiveTransport({ origin: auth.origin, token: 'revoked', request: requestApi })).resolves.toEqual({ ok: false, reason: 'credential-rejected' });
+ await expect(preflightLiveTransport({ origin: auth.origin, token: null, request: requestApi })).resolves.toEqual({ ok: false, reason: 'credential-missing' });
+ await expect(preflightLiveTransport({ origin: redirecting.origin, token: TOKEN, request: requestApi })).resolves.toEqual({ ok: false, reason: 'whoami-unreadable' });
+ await expect(preflightLiveTransport({ origin: open.origin, token: TOKEN, request: requestApi })).resolves.toEqual({ ok: true, mode: 'password-free' });
+ expect(auth.seen.map(r => r.path)).toEqual(['/api/auth/whoami', '/api/auth/whoami', '/api/auth/whoami']);
+ expect(decoy.seen).toEqual([]);
+ const [authServer] = servers.splice(1, 1);
+ await new Promise(resolve => authServer.close(resolve));
+ await expect(preflightLiveTransport({ origin: auth.origin, token: TOKEN, request: requestApi })).resolves.toEqual({ ok: false, reason: 'origin-unreachable' });
+ });
+
+ it('guards every request and WebSocket before the session cookie enters the browser context', async () => {
+ const calls = [];
+ let routeHandler, socketMatcher;
+ const context = {
+ route: async (_match, handler) => { calls.push('route'); routeHandler = handler; },
+ routeWebSocket: async (match) => { calls.push('routeWebSocket'); socketMatcher = match; },
+ addCookies: async cookies => calls.push(['addCookies', cookies]),
+ };
+ const blocked = [];
+ await installLiveTransport(context, { origin: ORIGIN, token: TOKEN, onBlocked: (reason, url) => blocked.push([reason, url]) });
+ expect(calls).toEqual(['route', 'routeWebSocket', ['addCookies', [{ name: 'portos_auth_5553', value: TOKEN, url: ORIGIN, httpOnly: true, sameSite: 'Strict' }]]]);
+
+ const decide = async (url, method = 'GET') => {
+ let outcome;
+ await routeHandler({ request: () => ({ url: () => url, method: () => method }),
+ continue: async () => { outcome = 'continue'; }, abort: async () => { outcome = 'abort'; } });
+ return outcome;
+ };
+ expect(await decide(`${ORIGIN}/api/messages/inbox`)).toBe('continue');
+ expect(await decide(`${ORIGIN}/socket.io/?EIO=4&transport=polling`, 'POST')).toBe('continue');
+ expect(await decide(`${ORIGIN}/api/messages/sync`, 'POST')).toBe('abort');
+ expect(await decide('http://127.0.0.1:5560/api/auth/whoami')).toBe('abort');
+ expect(await decide('http://localhost:5553/api/auth/whoami')).toBe('abort');
+ expect(await decide('https://cdn.example.net/x.js')).toBe('abort');
+ expect(blocked.map(([reason]) => reason)).toEqual(['mutation', 'foreign-origin', 'foreign-origin', 'foreign-origin']);
+ expect(socketMatcher(new URL('ws://127.0.0.1:5553/socket.io/'))).toBe(false);
+ expect(socketMatcher(new URL('ws://127.0.0.1:5560/socket.io/'))).toBe(true);
+ });
+
+ it('stays UNVERIFIED with a next step, without launching a browser, when no authorized transport exists', async () => {
+ const chromium = { launch: vi.fn() };
+ const args = parseLiveAuditArgs([]);
+ const env = { PORTOS_URL: 'http://192.0.2.10:5555', PORTOS_AGENT_KEY_FILE: '/nonexistent/agent-key.json', PORTOS_API_TOKEN: TOKEN };
+ const request = vi.fn();
+ const remote = await runLiveAudit({ args, env, chromium, request });
+ expect(request).not.toHaveBeenCalled();
+ expect(remote).toMatchObject({ live: true, synthetic: false, status: 'unverified', unverified: { reason: 'non-loopback-origin' } });
+
+ const auth = await listen((req, res) => res.end(JSON.stringify({ required: true, authenticated: false })));
+ const missing = await runLiveAudit({ args, env: { PORTOS_URL: auth.origin, PORTOS_AGENT_KEY_FILE: '/nonexistent/agent-key.json' }, chromium });
+ expect(missing.unverified).toMatchObject({ reason: 'credential-missing', nextStep: expect.stringContaining('Agent API key') });
+ expect(chromium.launch).not.toHaveBeenCalled();
+ expect(exitCodeFor(missing)).toBe(2);
+ expect(JSON.stringify([remote, missing])).not.toMatch(/tok-example|192\.0\.2\.10|127\.0\.0\.1/);
+ });
+
+ it('parses a bounded live window and requires a collection marker', () => {
+ expect(parseLiveAuditArgs(['out.json', '--route=/messages/inbox', '--sibling=/messages/contacts', '--idle-ms=90000']))
+ .toEqual({ output: 'out.json', route: '/messages/inbox', sibling: '/messages/contacts', collectionEndpoint: '/api/messages/inbox', idleMs: 90000 });
+ for (const bad of [['--idle-ms=5000'], ['--route=/brain/people'], ['--route=//evil.example'], ['--route=/Media'], ['--sibling=/media/history']]) {
+ expect(() => parseLiveAuditArgs(bad)).toThrow();
+ }
+ });
+});