@pablopunk/webr 0.1.1

package/src/server/auth/auth.ts

@@ -0,0 +1,134 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import type { WebSocket } from 'ws';
+import { z } from 'zod';
+import type { MetadataDatabase } from '../storage/database';
+import { isLocalRequest, sourceAddress } from './access';
+import { AuditLog } from './audit';
+import { ApproverPresence } from './presence';
+import { pairPage } from './pair-page';
+import { PairingService, RateLimiter, formatInviteToken } from './pairing';
+import { SessionStore, clearedSessionCookie, deviceNameFrom, sessionCookie, type DeviceSession } from './sessions';
+
+export type AuthOptions = { publicUrls?: string[] };
+export type Access = { local: boolean; session?: DeviceSession };
+
+const publicRoutes: [method: string, path: RegExp][] = [
+  ['GET', /^\/api\/auth\/state$/],
+  ['POST', /^\/api\/pair\/request$/],
+  ['POST', /^\/api\/pair\/request\/[^/]+\/poll$/],
+  ['POST', /^\/api\/pair\/redeem$/],
+  ['GET', /^\/[a-z0-9-]+\.(?:png|ico|webmanifest)$/],
+];
+const idParams = z.object({ id: z.uuid() });
+const emptyBody = z.object({}).strict();
+const sourceOf = (request: FastifyRequest) => sourceAddress(request.ip);
+const deviceOf = (request: FastifyRequest) => deviceNameFrom(request.headers['user-agent']);
+
+export class Auth {
+  readonly sessions: SessionStore;
+  readonly pairing = new PairingService();
+  readonly audit: AuditLog;
+  private readonly presence = new ApproverPresence();
+  private readonly accessByRequest = new WeakMap<object, Access>();
+  private readonly deviceBySocket = new WeakMap<object, string>();
+
+  constructor(database: MetadataDatabase, private readonly origin: URL, private readonly options: AuthOptions = {}) {
+    this.audit = new AuditLog(database);
+    this.sessions = new SessionStore(database, Date.now, this.audit);
+  }
+
+  access(request: FastifyRequest): Access { return this.accessByRequest.get(request.raw) ?? { local: false }; }
+
+  guard(request: FastifyRequest, reply: FastifyReply) {
+    const access: Access = { local: isLocalRequest(request.raw), session: this.sessions.authenticate(request.headers.cookie, sourceOf(request)) };
+    this.accessByRequest.set(request.raw, access);
+    if (access.local || access.session || this.isPublic(request)) return undefined;
+    if (request.method === 'GET' && request.headers.accept?.includes('text/html')) return reply.code(401).type('text/html').send(pairPage());
+    return reply.code(401).send({ error: 'unauthorized' });
+  }
+
+  expectedOrigin(request: FastifyRequest) {
+    return `${request.headers.host === this.origin.host ? this.origin.protocol : `${request.protocol}:`}//${request.headers.host}`;
+  }
+
+  routes(app: FastifyInstance) {
+    const requestLimiter = new RateLimiter(6, 60_000);
+    const redeemLimiter = new RateLimiter(10, 60_000);
+    app.websocketServer.on('connection', (socket: WebSocket, request) => { const id = this.accessByRequest.get(request)?.session?.id; if (id) this.deviceBySocket.set(socket, id); });
+
+    app.get('/api/auth/state', async (request) => { const { local, session } = this.access(request); return { local, authenticated: !!session }; });
+    app.post('/api/pair/request', async (request, reply) => {
+      if (!requestLimiter.allow(request.ip)) return reply.code(429).send({ error: 'rate_limited' });
+      try {
+        const created = this.pairing.request(deviceOf(request), sourceOf(request));
+        this.audit.record('pair_requested', { source: sourceOf(request), deviceName: deviceOf(request) });
+        return created;
+      } catch (error) { return reply.code(429).send({ error: error instanceof Error && error.message === 'cooling_down' ? 'cooling_down' : 'too_many_requests' }); }
+    });
+    app.post('/api/pair/request/:id/poll', async (request, reply) => {
+      const { id } = idParams.parse(request.params);
+      const { secret } = z.object({ secret: z.string().min(1).max(100) }).strict().parse(request.body);
+      const result = this.pairing.claim(id, secret);
+      if (result.status === 'approved') this.grant(request, reply, result.deviceName!);
+      return result.status === 'pending' ? { status: result.status, approverOnline: this.presence.attentive() } : { status: result.status };
+    });
+    app.post('/api/pair/redeem', async (request, reply) => {
+      if (!redeemLimiter.allow(request.ip)) return reply.code(429).send({ error: 'rate_limited' });
+      const { token } = z.object({ token: z.string().min(1).max(64) }).strict().parse(request.body);
+      if (!this.pairing.redeemInvite(token)) return reply.code(403).send({ error: 'invalid_token' });
+      this.audit.record('invite_redeemed', { source: sourceOf(request), deviceName: deviceOf(request) });
+      this.grant(request, reply, deviceOf(request));
+      return { ok: true };
+    });
+
+    app.get('/api/pair/pending', async () => { this.presence.seen(); return this.pairing.pending(); });
+    for (const [action, state] of [['approve', 'approved'], ['deny', 'denied']] as const) {
+      app.post(`/api/pair/:id/${action}`, async (request, reply) => {
+        const { id } = idParams.parse(request.params);
+        emptyBody.parse(request.body);
+        const decided = this.pairing.decide(id, state);
+        if (!decided) return reply.code(404).send({ error: 'request_not_found' });
+        this.audit.record(state === 'approved' ? 'pair_approved' : 'pair_denied', decided);
+        return { [state]: true };
+      });
+    }
+    app.post('/api/pair/invites', async (request) => {
+      const invite = this.pairing.createInvite();
+      this.audit.record('invite_created', { source: sourceOf(request) });
+      return { token: formatInviteToken(invite.token), expiresAt: invite.expiresAt, urls: (this.options.publicUrls ?? []).map((base) => `${base}/#token=${invite.token}`) };
+    });
+    app.get('/api/audit', async () => this.audit.recent());
+    app.get('/api/devices', async (request) => this.sessions.list().map((device) => ({ ...device, current: device.id === this.access(request).session?.id })));
+    app.post('/api/devices/:id/revoke', async (request, reply) => {
+      const { id } = idParams.parse(request.params);
+      emptyBody.parse(request.body);
+      const device = this.sessions.list().find((candidate) => candidate.id === id);
+      if (!device || !this.revoke(app, id)) return reply.code(404).send({ error: 'device_not_found' });
+      this.audit.record('device_revoked', { source: sourceOf(request), deviceName: device.name });
+      return { revoked: true };
+    });
+    app.post('/api/auth/logout', async (request, reply) => {
+      const session = this.access(request).session;
+      if (session && this.revoke(app, session.id)) this.audit.record('device_revoked', { source: sourceOf(request), deviceName: session.name });
+      reply.header('Set-Cookie', clearedSessionCookie(this.isSecure(request)));
+      return { ok: true };
+    });
+  }
+
+  private isPublic(request: FastifyRequest) {
+    const path = request.url.split('?')[0];
+    return publicRoutes.some(([method, pattern]) => method === request.method && pattern.test(path));
+  }
+
+  private isSecure(request: FastifyRequest) { return this.origin.protocol === 'https:' && request.headers.host === this.origin.host; }
+
+  private grant(request: FastifyRequest, reply: FastifyReply, deviceName: string) {
+    reply.header('Set-Cookie', sessionCookie(this.sessions.create(deviceName).token, this.isSecure(request)));
+  }
+
+  private revoke(app: FastifyInstance, id: string) {
+    const revoked = this.sessions.revoke(id);
+    for (const socket of app.websocketServer.clients) if (this.deviceBySocket.get(socket) === id) socket.close(1008);
+    return revoked;
+  }
+}

package/src/server/auth/pair-page.ts

@@ -0,0 +1,85 @@
+const styles = `
+:root { color-scheme: light dark; --page: #f8f8f7; --surface: #fff; --ink: #1b1c1d; --soft: #5b5d61; --line: #dedfdd; --blue: #345fba; --danger: #c9534d; }
+@media (prefers-color-scheme: dark) { :root { --page: #121313; --surface: #1a1b1c; --ink: #ececea; --soft: #a2a4a7; --line: #2d2f31; --blue: #5b86e0; --danger: #e0716b; } }
+* { box-sizing: border-box; }
+body { margin: 0; min-height: 100dvh; display: grid; place-items: center; padding: max(16px, env(safe-area-inset-top)) max(16px, env(safe-area-inset-right)) max(16px, env(safe-area-inset-bottom)) max(16px, env(safe-area-inset-left)); background: var(--page); color: var(--ink); font: 15px/1.5 'DM Sans', system-ui, sans-serif; }
+main { width: min(380px, 100%); padding: 28px 24px; border: 1px solid var(--line); border-radius: 14px; background: var(--surface); text-align: center; }
+h1 { margin: 0 0 4px; font-size: 20px; }
+p { margin: 0 0 20px; color: var(--soft); }
+button { width: 100%; min-height: 44px; border: 0; border-radius: 10px; background: var(--blue); color: #fff; font: inherit; font-weight: 600; cursor: pointer; }
+button.link { width: auto; min-height: 0; margin-top: 16px; padding: 4px; background: none; color: var(--soft); font-weight: 400; text-decoration: underline; }
+input { width: 100%; min-height: 44px; margin-bottom: 10px; padding: 0 12px; border: 1px solid var(--line); border-radius: 10px; background: transparent; color: var(--ink); font: 600 16px ui-monospace, Menlo, monospace; letter-spacing: .12em; text-align: center; text-transform: uppercase; }
+.code { margin: 8px 0 16px; font: 700 44px/1 ui-monospace, Menlo, monospace; letter-spacing: .18em; text-indent: .18em; }
+.hint { margin: 0 0 8px; padding: 10px 12px; border: 1px solid var(--line); border-radius: 10px; font-size: 13px; text-align: left; }
+.hint code { font-family: ui-monospace, Menlo, monospace; color: var(--ink); }
+.error { margin-top: 12px; color: var(--danger); }
+[hidden] { display: none !important; }
+`;
+
+const script = `
+const $ = (id) => document.getElementById(id);
+const views = ['start', 'waiting', 'token-view'];
+const show = (name) => views.forEach((view) => { $(view).hidden = view !== name; });
+const say = (text) => { $('error').textContent = text || ''; };
+const post = (path, body) => fetch(path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body || {}) });
+const enter = () => location.replace('/');
+let timer;
+const stop = () => clearTimeout(timer);
+const reset = (message) => { stop(); sessionStorage.removeItem('webr-pairing'); show('start'); say(message); };
+
+async function poll(request) {
+  const response = await post('/api/pair/request/' + request.id + '/poll', { secret: request.secret });
+  const { status, approverOnline } = await response.json().catch(() => ({ status: 'expired' }));
+  if (status === 'approved') return enter();
+  if (status === 'denied') return reset('The request was declined.');
+  if (status === 'expired') return reset('The request expired. Try again.');
+  $('hint').hidden = approverOnline !== false;
+  timer = setTimeout(() => poll(request).catch(() => { timer = setTimeout(() => poll(request), 3000); }), 1500);
+}
+function wait(request) { $('code').textContent = request.code; $('hint').hidden = true; show('waiting'); say(''); stop(); poll(request).catch(() => reset('Could not reach the server.')); }
+
+async function tooManyRequestsMessage(response) {
+  const { error } = await response.json().catch(() => ({}));
+  return error === 'cooling_down' ? 'That request was declined. Wait a minute before asking again.' : 'Too many requests. Wait a minute and try again.';
+}
+
+async function requestAccess() {
+  say('');
+  const response = await post('/api/pair/request');
+  if (response.status === 429) return say(await tooManyRequestsMessage(response));
+  if (!response.ok) return say('Could not send the request.');
+  const request = await response.json();
+  sessionStorage.setItem('webr-pairing', JSON.stringify(request));
+  wait(request);
+}
+
+async function redeem(token) {
+  const response = await post('/api/pair/redeem', { token });
+  if (response.ok) return enter();
+  history.replaceState(null, '', location.pathname);
+  show('token-view'); say(response.status === 429 ? 'Too many attempts. Wait a minute.' : 'That code is not valid or has expired.');
+}
+
+$('request').onclick = () => requestAccess().catch(() => say('Could not reach the server.'));
+$('cancel').onclick = () => reset('');
+$('use-token').onclick = () => { say(''); show('token-view'); $('token').focus(); };
+$('back').onclick = () => { say(''); show('start'); };
+$('token-form').onsubmit = (event) => { event.preventDefault(); redeem($('token').value).catch(() => say('Could not reach the server.')); };
+
+const hashToken = new URLSearchParams(location.hash.slice(1)).get('token');
+const saved = (() => { try { return JSON.parse(sessionStorage.getItem('webr-pairing') || 'null'); } catch { return null; } })();
+if (hashToken) redeem(hashToken).catch(() => say('Could not reach the server.'));
+else if (saved) wait(saved);
+`;
+
+const installableAppHead = `<link rel="manifest" href="/manifest.webmanifest"><link rel="icon" href="/favicon.ico" sizes="48x48"><link rel="apple-touch-icon" href="/apple-touch-icon.png"><meta name="apple-mobile-web-app-capable" content="yes"><meta name="mobile-web-app-capable" content="yes"><meta name="apple-mobile-web-app-title" content="Webr"><meta name="apple-mobile-web-app-status-bar-style" content="default"><meta name="theme-color" media="(prefers-color-scheme: light)" content="#f8f8f7"><meta name="theme-color" media="(prefers-color-scheme: dark)" content="#121313">`;
+
+export const pairPage = () => `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"><meta name="robots" content="noindex">${installableAppHead}<title>Connect · Webr</title><style>${styles}</style></head>
+<body><main>
+<h1>Webr</h1>
+<div id="start"><p>This device isn’t connected yet.</p><button id="request" type="button">Request access</button><button id="use-token" class="link" type="button">I have a code</button></div>
+<div id="waiting" hidden><p>Approve this request in Webr on your computer. Make sure the code matches.</p><div class="code" id="code" aria-live="polite"></div><p class="hint" id="hint" hidden>Nobody has Webr open on your computer right now. Open Webr there to approve, or run <code>webr invite</code> in a terminal there and enter the code instead.</p><button id="cancel" class="link" type="button">Cancel</button></div>
+<div id="token-view" hidden><p>Enter the code shown in Webr’s settings.</p><form id="token-form"><input id="token" name="token" autocomplete="one-time-code" autocapitalize="characters" spellcheck="false" placeholder="XXXX-XXXX-XXXX-XXXX" required><button type="submit">Connect</button></form><button id="back" class="link" type="button">Back</button></div>
+<p class="error" id="error" role="alert"></p>
+</main><script>${script}</script></body></html>`;

package/src/server/auth/pairing.ts

@@ -0,0 +1,91 @@
+import { createHash, randomBytes, randomInt, randomUUID, timingSafeEqual } from 'node:crypto';
+
+const REQUEST_TTL_MS = 5 * 60_000;
+const INVITE_TTL_MS = 5 * 60_000;
+const MAX_PENDING_REQUESTS = 8;
+const MAX_PENDING_PER_SOURCE = 2;
+const DENY_COOLDOWN_MS = 60_000;
+const TOKEN_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+const TOKEN_LENGTH = 16;
+
+type PairRequest = { id: string; code: string; deviceName: string; source: string; secretHash: Buffer; expiresAt: number; state: 'pending' | 'approved' | 'denied' };
+export type PendingPairRequest = Pick<PairRequest, 'id' | 'code' | 'deviceName' | 'source' | 'expiresAt'>;
+export type ClaimResult = { status: 'pending' | 'denied' | 'expired' | 'approved' };
+
+const sha256 = (value: string) => createHash('sha256').update(value).digest();
+export const normalizeInviteToken = (input: string) => input.toUpperCase().replace(/[^A-Z0-9]/g, '');
+export const formatInviteToken = (token: string) => token.match(/.{1,4}/g)!.join('-');
+const newInviteToken = () => Array.from({ length: TOKEN_LENGTH }, () => TOKEN_ALPHABET[randomInt(TOKEN_ALPHABET.length)]).join('');
+
+export class RateLimiter {
+  private readonly hits = new Map<string, number[]>();
+  constructor(private readonly limit: number, private readonly windowMs: number, private readonly now = Date.now) {}
+  allow(key: string) {
+    const at = this.now();
+    const recent = (this.hits.get(key) ?? []).filter((time) => at - time < this.windowMs);
+    if (recent.length >= this.limit) { this.hits.set(key, recent); return false; }
+    this.hits.set(key, [...recent, at]);
+    return true;
+  }
+}
+
+export class PairingService {
+  private readonly requests = new Map<string, PairRequest>();
+  private readonly invites = new Map<string, number>();
+  private readonly cooldowns = new Map<string, number>();
+  constructor(private readonly now = Date.now) {}
+
+  request(deviceName: string, source: string) {
+    this.sweep();
+    if (this.cooldowns.has(source)) throw new Error('cooling_down');
+    const pending = this.pending();
+    if (pending.length >= MAX_PENDING_REQUESTS || pending.filter((request) => request.source === source).length >= MAX_PENDING_PER_SOURCE) throw new Error('too_many_requests');
+    const secret = randomBytes(24).toString('base64url');
+    const request: PairRequest = { id: randomUUID(), code: String(randomInt(10_000)).padStart(4, '0'), deviceName, source, secretHash: sha256(secret), expiresAt: this.now() + REQUEST_TTL_MS, state: 'pending' };
+    this.requests.set(request.id, request);
+    return { id: request.id, code: request.code, secret, expiresAt: request.expiresAt };
+  }
+
+  pending(): PendingPairRequest[] {
+    this.sweep();
+    return [...this.requests.values()].filter((request) => request.state === 'pending').map(({ id, code, deviceName, source, expiresAt }) => ({ id, code, deviceName, source, expiresAt }));
+  }
+
+  decide(id: string, state: 'approved' | 'denied') {
+    this.sweep();
+    const request = this.requests.get(id);
+    if (!request || request.state !== 'pending') return undefined;
+    request.state = state;
+    if (state === 'denied') this.cooldowns.set(request.source, this.now() + DENY_COOLDOWN_MS);
+    return { deviceName: request.deviceName, source: request.source };
+  }
+
+  claim(id: string, secret: string): ClaimResult & { deviceName?: string } {
+    this.sweep();
+    const request = this.requests.get(id);
+    if (!request || !timingSafeEqual(request.secretHash, sha256(secret))) return { status: 'expired' };
+    if (request.state === 'pending') return { status: 'pending' };
+    this.requests.delete(id);
+    return request.state === 'approved' ? { status: 'approved', deviceName: request.deviceName } : { status: 'denied' };
+  }
+
+  createInvite() {
+    this.sweep();
+    const token = newInviteToken();
+    const expiresAt = this.now() + INVITE_TTL_MS;
+    this.invites.set(token, expiresAt);
+    return { token, expiresAt };
+  }
+
+  redeemInvite(input: string) {
+    this.sweep();
+    return this.invites.delete(normalizeInviteToken(input));
+  }
+
+  private sweep() {
+    const at = this.now();
+    for (const [id, request] of this.requests) if (request.expiresAt <= at) this.requests.delete(id);
+    for (const [token, expiresAt] of this.invites) if (expiresAt <= at) this.invites.delete(token);
+    for (const [source, until] of this.cooldowns) if (until <= at) this.cooldowns.delete(source);
+  }
+}

package/src/server/auth/presence.ts

@@ -0,0 +1,8 @@
+const ATTENTIVE_WINDOW_MS = 10_000;
+
+export class ApproverPresence {
+  private lastSeenAt = Number.NEGATIVE_INFINITY;
+  constructor(private readonly now = Date.now) {}
+  seen() { this.lastSeenAt = this.now(); }
+  attentive() { return this.now() - this.lastSeenAt < ATTENTIVE_WINDOW_MS; }
+}

package/src/server/auth/sessions.ts

@@ -0,0 +1,48 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import type { MetadataDatabase } from '../storage/database';
+import type { AuditLog } from './audit';
+
+export type DeviceSession = { id: string; name: string; createdAt: number; lastSeenAt: number };
+
+export const SESSION_COOKIE = 'webr_session';
+export const IDLE_EXPIRY_MS = 90 * 24 * 60 * 60 * 1000;
+const COOKIE_MAX_AGE_SECONDS = 400 * 24 * 60 * 60;
+const TOUCH_INTERVAL_MS = 60_000;
+
+const hashToken = (token: string) => createHash('sha256').update(token).digest('hex');
+const readCookie = (header: string | undefined, name: string) => header?.split(';').map((part) => part.trim().split('=')).find(([key]) => key === name)?.[1];
+
+export const sessionCookie = (token: string, secure: boolean) => `${SESSION_COOKIE}=${token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${COOKIE_MAX_AGE_SECONDS}${secure ? '; Secure' : ''}`;
+export const clearedSessionCookie = (secure: boolean) => `${SESSION_COOKIE}=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0${secure ? '; Secure' : ''}`;
+
+export class SessionStore {
+  constructor(private readonly database: MetadataDatabase, private readonly now = Date.now, private readonly audit?: AuditLog) {}
+
+  create(name: string) {
+    const token = randomBytes(32).toString('base64url');
+    const at = this.now();
+    const session: DeviceSession = { id: randomUUID(), name, createdAt: at, lastSeenAt: at };
+    this.database.addDeviceSession({ ...session, tokenHash: hashToken(token) });
+    return { session, token };
+  }
+
+  authenticate(cookieHeader: string | undefined, source?: string): DeviceSession | undefined {
+    const token = readCookie(cookieHeader, SESSION_COOKIE);
+    if (!token) return undefined;
+    const row = this.database.deviceSessionByTokenHash(hashToken(token));
+    if (!row) return undefined;
+    const at = this.now();
+    if (at - row.lastSeenAt > IDLE_EXPIRY_MS) { this.database.deleteDeviceSession(row.id); this.audit?.record('session_expired', { source, deviceName: row.name }); return undefined; }
+    if (at - row.lastSeenAt > TOUCH_INTERVAL_MS) this.database.touchDeviceSession(row.id, at);
+    return { id: row.id, name: row.name, createdAt: row.createdAt, lastSeenAt: at };
+  }
+
+  list() { return this.database.deviceSessions().sort((a, b) => b.lastSeenAt - a.lastSeenAt).map((device) => ({ ...device, expiresAt: device.lastSeenAt + IDLE_EXPIRY_MS })); }
+  revoke(id: string) { return this.database.deleteDeviceSession(id); }
+}
+
+export function deviceNameFrom(userAgent = '') {
+  const system = /iPhone/.test(userAgent) ? 'iPhone' : /iPad/.test(userAgent) ? 'iPad' : /Android/.test(userAgent) ? 'Android' : /Macintosh|Mac OS X/.test(userAgent) ? 'Mac' : /Windows/.test(userAgent) ? 'Windows' : /Linux/.test(userAgent) ? 'Linux' : 'Device';
+  const browser = /Edg\//.test(userAgent) ? 'Edge' : /Firefox\/|FxiOS/.test(userAgent) ? 'Firefox' : /Chrome\/|CriOS/.test(userAgent) ? 'Chrome' : /Safari\//.test(userAgent) ? 'Safari' : undefined;
+  return browser ? `${system} · ${browser}` : system;
+}

package/src/server/directories.ts

@@ -0,0 +1,21 @@
+import { readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const MAX_SUGGESTIONS = 12;
+
+export const expandHome = (path: string) => path === '~' ? homedir() : path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
+
+const splitAtLastSlash = (prefix: string) => ({ parent: prefix.slice(0, prefix.lastIndexOf('/') + 1), partial: prefix.slice(prefix.lastIndexOf('/') + 1) });
+const startsWithPartial = (partial: string) => (name: string) => name.toLowerCase().startsWith(partial.toLowerCase()) && (partial.startsWith('.') || !name.startsWith('.'));
+
+export async function suggestDirectories(prefix: string): Promise<string[]> {
+  if (!prefix.startsWith('/') && !prefix.startsWith('~')) return [];
+  const { parent, partial } = splitAtLastSlash(prefix.includes('/') ? prefix : `${prefix}/`);
+  const entries = await readdir(expandHome(parent), { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => entry.isDirectory() && startsWithPartial(partial)(entry.name))
+    .map((entry) => `${parent}${entry.name}/`)
+    .sort((a, b) => a.localeCompare(b))
+    .slice(0, MAX_SUGGESTIONS);
+}

package/src/server/dist.ts

@@ -0,0 +1,3 @@
+import { fileURLToPath } from 'node:url';
+
+export const distRoot = () => process.env.WEBR_DIST ?? fileURLToPath(new URL('../../dist', import.meta.url));

package/src/server/host.ts

@@ -0,0 +1,166 @@
+import Fastify, { type FastifyRequest } from 'fastify';
+import websocket from '@fastify/websocket';
+import staticFiles from '@fastify/static';
+import { resolve } from 'node:path';
+import { distRoot } from './dist';
+import { z } from 'zod';
+import type { RuntimeManager } from './runtime/manager';
+import { launchInput, opaqueId } from '../shared/runtime';
+import { registerWebsockets } from './websockets';
+import { createWorkspace } from './runtime/workspace';
+import { expandHome, suggestDirectories } from './directories';
+import { perfLog, perfLogEnabled } from './perf-log';
+import { Auth, type AuthOptions } from './auth/auth';
+import { isTrustedHost } from './auth/access';
+import { MAX_IMAGE_BYTES, UploadStore, uploadContentTypes } from './uploads';
+
+const localOwner = 'local';
+type SsrHandler = (request: FastifyRequest['raw'], response: import('node:http').ServerResponse, next: (error?: unknown) => void, locals: Record<string, unknown>) => void;
+
+export async function createHost(manager: RuntimeManager, origin: string, ssr?: SsrHandler, tls?: { key: Buffer; cert: Buffer }, uploads = new UploadStore(), authOptions: AuthOptions = {}) {
+  const app = Fastify({ logger: false, bodyLimit: 16 * 1024, ...(tls ? { https: tls } : {}), requestTimeout: 10_000 });
+  const configuredOrigin = new URL(origin);
+  const auth = new Auth(manager.database, configuredOrigin, authOptions);
+  app.addHook('onRequest', async (request, reply) => {
+    reply.header('X-Content-Type-Options', 'nosniff');
+    reply.header('Cache-Control', 'no-store');
+    reply.header('Referrer-Policy', 'no-referrer');
+    if (!isTrustedHost(request.headers.host, configuredOrigin.host)) return reply.code(403).send({ error: 'invalid_host' });
+    const upgrade = request.headers.upgrade === 'websocket';
+    if ((request.method !== 'GET' && request.method !== 'HEAD' || upgrade) && request.headers.origin !== auth.expectedOrigin(request)) return reply.code(403).send({ error: 'invalid_origin' });
+    return auth.guard(request, reply);
+  });
+  app.setErrorHandler((error, _request, reply) => {
+    const message = error instanceof Error ? error.message : '';
+    if (error instanceof z.ZodError) return reply.code(400).send({ error: 'invalid_request' });
+    const status = (error as { statusCode?: number }).statusCode;
+    if (status === 413) return reply.code(413).send({ error: 'image_too_large' });
+    if (status === 415 || message === 'unsupported_image') return reply.code(415).send({ error: 'unsupported_image' });
+    if (status && status >= 400 && status < 500) return reply.code(status).send({ error: 'invalid_request' });
+    if (message === 'thread_not_found') return reply.code(404).send({ error: message });
+    if (message === 'launch_in_progress') return reply.code(409).send({ error: message });
+    return reply.code(['idempotency_conflict', 'binding_conflict', 'invalid_adoption'].includes(message) ? 409 : 503).send({ error: ['idempotency_conflict', 'binding_conflict', 'invalid_adoption', 'machine_disconnected'].includes(message) ? message : 'request_failed' });
+  });
+  await app.register(websocket, { options: { maxPayload: 32 * 1024, perMessageDeflate: false } });
+  const hub = registerWebsockets(app, manager);
+  auth.routes(app);
+  app.get('/api/catalog/machines', async () => manager.bootstrap().machines);
+  app.get('/api/catalog/:machineId', async (request) => {
+    const { machineId } = z.object({ machineId: opaqueId }).parse(request.params);
+    const { projectId } = z.object({ projectId: opaqueId.optional() }).strict().parse(request.query);
+    return manager.catalog(machineId, projectId);
+  });
+  app.get('/api/runtime', async () => manager.bootstrap());
+  app.addContentTypeParser(uploadContentTypes, { parseAs: 'buffer', bodyLimit: MAX_IMAGE_BYTES }, (_request, body, done) => done(null, body));
+  app.post('/api/uploads', { bodyLimit: MAX_IMAGE_BYTES }, async (request, reply) => {
+    const { machineId } = z.object({ machineId: opaqueId }).strict().parse(request.query);
+    const supervisor = manager.supervisors.get(machineId);
+    if (!supervisor?.connected) return reply.code(409).send({ error: 'machine_disconnected' });
+    if (!supervisor.target.acceptsLocalFiles) return reply.code(409).send({ error: 'uploads_unsupported_target' });
+    if (!Buffer.isBuffer(request.body)) return reply.code(415).send({ error: 'unsupported_image' });
+    return { path: await uploads.save(request.headers['content-type'], request.body) };
+  });
+  app.get('/api/directories', async (request, reply) => {
+    const { machineId, prefix } = z.object({ machineId: opaqueId, prefix: z.string().max(1000).refine((path) => !/[\x00-\x1f]/.test(path)) }).strict().parse(request.query);
+    const supervisor = manager.supervisors.get(machineId);
+    if (!supervisor?.target.acceptsLocalFiles) return reply.code(409).send({ error: 'directories_unsupported_target' });
+    return suggestDirectories(prefix);
+  });
+  app.get('/api/worktrees', async (request) => {
+    const { machineId, projectId } = z.object({ machineId: opaqueId, projectId: opaqueId }).strict().parse(request.query);
+    return manager.worktrees(machineId, projectId);
+  });
+  app.post('/api/worktrees/open', async (request) => {
+    const input = z.object({ machineId: opaqueId, projectId: opaqueId, path: z.string().min(1).max(1000) }).strict().parse(request.body);
+    return manager.openWorktree(input.machineId, input.projectId, input.path);
+  });
+  app.post('/api/workspaces', async (request, reply) => {
+    const input = z.object({ machineId: opaqueId, path: z.string().regex(/^(\/|~\/)/).max(1000).refine((path) => !/[\x00-\x1f]/.test(path)), label: z.string().trim().min(1).max(80) }).strict().parse(request.body);
+    const key = z.uuid().parse(request.headers['idempotency-key']);
+    const supervisor = manager.supervisors.get(input.machineId);
+    if (!supervisor?.connected) return reply.code(409).send({ error: 'machine_disconnected' });
+    const result = await createWorkspace(manager.database, supervisor.target, key, expandHome(input.path), input.label);
+    supervisor.invalidate();
+    return reply.code(result.state === 'unknown' ? 202 : 201).send(result);
+  });
+  app.get('/api/projects/:machineId/:projectId/icon', async (request, reply) => {
+    const { machineId, projectId } = z.object({ machineId: opaqueId, projectId: opaqueId }).parse(request.params);
+    const target = manager.supervisors.get(machineId)?.target;
+    const icon = await target?.icon?.(projectId);
+    if (!icon) return reply.code(404).send();
+    if (icon.contentType === 'image/svg+xml') reply.header('Content-Security-Policy', "sandbox; default-src 'none'; style-src 'unsafe-inline'");
+    return reply.type(icon.contentType).send(icon.bytes);
+  });
+  app.post('/api/threads', async (request, reply) => {
+    const input = launchInput.parse(request.body);
+    const key = z.uuid().parse(request.headers['idempotency-key']);
+    const supervisor = manager.supervisors.get(input.machineId);
+    if (!supervisor?.connected) return reply.code(409).send({ error: 'machine_disconnected' });
+    const catalog = await manager.catalog(input.machineId, input.projectId);
+    if (!catalog.harnesses.find((harness) => harness.id === input.agent)?.launchEnabled || supervisor.target.canLaunch && !supervisor.target.canLaunch(input)) return reply.code(409).send({ error: 'launch_unavailable' });
+    const result = manager.journal.submit(localOwner, key, input, supervisor.target);
+    return reply.code(202).send(result);
+  });
+  app.post('/api/threads/:id/adopt', async (request) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const input = z.object({ machineId: opaqueId, terminalIds: z.array(opaqueId).min(1).max(256) }).strict().parse(request.body);
+    await manager.adopt(input.machineId, id, input.terminalIds); return { adopted: true };
+  });
+  app.post('/api/threads/:id/focus', async (request) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const input = z.object({ machineId: opaqueId, paneId: opaqueId }).strict().parse(request.body);
+    await manager.focusPane(input.machineId, id, input.paneId); return { focused: true };
+  });
+  app.post('/api/threads/:id/archive', async (request) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const input = z.object({ machineId: opaqueId, archived: z.boolean() }).strict().parse(request.body);
+    manager.archive(input.machineId, id, input.archived); return { archived: input.archived };
+  });
+  app.post('/api/threads/:id/rename', async (request) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const input = z.object({ machineId: opaqueId, title: z.string().trim().min(1).max(90).refine((title) => !/[\x00-\x1f\x7f]/.test(title)) }).strict().parse(request.body);
+    await manager.renameThread(input.machineId, id, input.title); return { title: input.title };
+  });
+  app.post('/api/threads/:id/terminal', async (request) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const input = z.object({ machineId: opaqueId, direction: z.enum(['right', 'down']) }).strict().parse(request.body);
+    return manager.toggleTerminal(input.machineId, id, input.direction);
+  });
+  app.post('/api/threads/:id/terminal/close', async (request) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const input = z.object({ machineId: opaqueId }).strict().parse(request.body);
+    await manager.closeTerminal(input.machineId, id); return { closed: true };
+  });
+  app.post('/api/threads/:id/delete', async (request) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const input = z.object({ machineId: opaqueId }).strict().parse(request.body);
+    await manager.deleteThread(input.machineId, id); return { deleted: true };
+  });
+  app.post('/api/archive/delete', async () => manager.deleteArchived());
+  app.get('/api/operations/:id', async (request, reply) => {
+    const { id } = z.object({ id: z.uuid() }).parse(request.params);
+    const operation = manager.database.operation(id);
+    if (!operation || ![localOwner, manager.database.getSetting('allowed_account')].includes(operation.accountId)) return reply.code(404).send({ error: 'operation_not_found' });
+    return { id: operation.id, state: operation.state, step: operation.step, threadId: operation.threadId };
+  });
+  app.get('/api/stats', async () => hub.stats());
+  if (perfLogEnabled) app.post('/api/dev/perf', { bodyLimit: 256 * 1024 }, async (request) => { for (const record of z.object({ records: z.array(z.record(z.string(), z.unknown())).max(100) }).parse(request.body).records) perfLog('client', record); return { ok: true }; });
+  if (ssr) {
+    const clientRoot = resolve(distRoot(), 'client');
+    await app.register(staticFiles, { root: clientRoot, serve: false });
+    app.get('/_astro/*', async (request, reply) => {
+      const path = z.string().regex(/^[A-Za-z0-9_./-]+$/).parse((request.params as { '*': string })['*']);
+      const full = resolve(clientRoot, '_astro', path);
+      if (!full.startsWith(resolve(clientRoot, '_astro') + '/')) return reply.code(404).send();
+      return reply.sendFile(path, resolve(clientRoot, '_astro'));
+    });
+    app.get('/:file(^[a-z0-9-]+\\.(?:png|ico|webmanifest)$)', async (request, reply) => reply.sendFile((request.params as { file: string }).file, clientRoot));
+    app.get('/*', async (request, reply) => {
+      reply.hijack();
+      if (perfLogEnabled) reply.raw.setHeader('Document-Policy', 'js-profiling');
+      ssr(request.raw, reply.raw, () => { if (!reply.raw.headersSent) { reply.raw.statusCode = 404; reply.raw.end('Not found'); } }, { runtime: manager, accountId: localOwner });
+    });
+  }
+  app.addHook('onClose', async () => manager.close());
+  return app;
+}

package/src/server/perf-log.ts

@@ -0,0 +1,23 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export const perfLogEnabled = process.env.WEBR_DEV === '1';
+const file = process.env.WEBR_PERF_LOG ?? '.data/perf.jsonl';
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+let bytesWritten = 0;
+let ready: Promise<unknown> | undefined;
+
+function startWithAnEmptyLog() {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, '');
+}
+if (perfLogEnabled) startWithAnEmptyLog();
+
+export function perfLog(source: 'client' | 'server', record: Record<string, unknown>) {
+  if (!perfLogEnabled || bytesWritten >= MAX_LOG_BYTES) return;
+  ready ??= mkdir(dirname(file), { recursive: true });
+  const line = JSON.stringify({ ...record, at: new Date().toISOString(), source }) + '\n';
+  bytesWritten += line.length;
+  void ready.then(() => appendFile(file, line)).catch(() => undefined);
+}

package/src/server/protocol/deadlines.ts

@@ -0,0 +1,24 @@
+export const AGENT_READY_TIMEOUT_MS = 30_000;
+export const SHELL_READY_TIMEOUT_MS = 15_000;
+export const SCREEN_SETTLE_TIMEOUT_MS = 10_000;
+export const TRANSPORT_MARGIN_MS = 5000;
+export const WORKTREE_TIMEOUT_MS = 120_000;
+export const WORKTREE_REMOVE_TIMEOUT_MS = 60_000;
+export const MAX_RPC_TIMEOUT_MS = 305_000;
+export type RpcOptions = { timeoutMs: number; requestId?: string };
+
+export function requestDeadline(method: string, params: Record<string, unknown>, readDeadline = 5000, options?: RpcOptions) {
+  let timeout = readDeadline;
+  if (method === 'agent.start') {
+    const ready = params.timeout_ms ?? AGENT_READY_TIMEOUT_MS;
+    if (typeof ready !== 'number' || !Number.isInteger(ready) || ready <= 3000 || ready > 300_000) throw new Error('invalid_ready_timeout');
+    timeout = ready + TRANSPORT_MARGIN_MS;
+  }
+  if (method === 'worktree.create') timeout = WORKTREE_TIMEOUT_MS;
+  if (method === 'worktree.remove') timeout = WORKTREE_REMOVE_TIMEOUT_MS;
+  if (['tab.create', 'workspace.create', 'worktree.open'].includes(method)) timeout = 30_000;
+  timeout = options?.timeoutMs ?? timeout;
+  const maximum = ['agent.start', 'worktree.create', 'worktree.open', 'worktree.remove', 'tab.create', 'workspace.create'].includes(method) ? MAX_RPC_TIMEOUT_MS : 5000;
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > maximum) throw new Error('invalid_rpc_timeout');
+  return timeout;
+}

package/src/server/protocol/native.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+const id = z.string().min(1).max(160);
+const rect = z.object({ x: z.number().int().nonnegative(), y: z.number().int().nonnegative(), width: z.number().int().nonnegative(), height: z.number().int().nonnegative() });
+export const nativePane = z.object({ pane_id: id, terminal_id: id, workspace_id: id, tab_id: id, focused: z.boolean(), revision: z.number().int().nonnegative(), agent_status: z.enum(['idle', 'working', 'blocked', 'done', 'unknown']), agent: z.string().nullable().optional(), title: z.string().nullable().optional(), cwd: z.string().nullable().optional(), terminal_title_stripped: z.string().nullable().optional(), scroll: z.object({ max_offset_from_bottom: z.number().int().nonnegative() }).optional() });
+export const nativeTab = z.object({ tab_id: id, workspace_id: id, label: z.string().nullable().optional() });
+export const nativeWorkspace = z.object({ workspace_id: id, label: z.string(), worktree: z.object({ repo_key: id, repo_name: z.string(), repo_root: z.string(), checkout_path: z.string(), is_linked_worktree: z.boolean() }).nullable().optional() });
+export const nativeSnapshot = z.object({ version: z.string(), protocol: z.literal(22), workspaces: z.array(nativeWorkspace).max(1000), tabs: z.array(nativeTab).max(2000), panes: z.array(nativePane).max(4000), layouts: z.array(z.object({ workspace_id: id, tab_id: id, area: rect, panes: z.array(z.object({ pane_id: id, rect })).max(256) })).max(2000), agents: z.array(z.object({ terminal_id: id, state_change_seq: z.number().int().nonnegative().optional() })).max(4000) });
+export type NativeSnapshot = z.infer<typeof nativeSnapshot>;
+export const lifecycleSubscriptions = ['workspace.created', 'workspace.updated', 'workspace.metadata_updated', 'workspace.closed', 'workspace.renamed', 'workspace.moved', 'workspace.reordered', 'worktree.created', 'worktree.opened', 'worktree.removed', 'tab.created', 'tab.closed', 'tab.renamed', 'tab.moved', 'pane.created', 'pane.closed', 'pane.updated', 'pane.moved', 'pane.exited', 'pane.agent_detected', 'layout.updated'].map((type) => ({ type }));