Zum Inhalt springen

Claude Code in deiner eigenen Web-App · Teil 16 von 16 der Serie

Teil 16: Sitesmith auf deinem Handy

Öffne Sitesmith in deinem Heimnetz vom Handy aus: Der Server lauscht im LAN, druckt einen Login-Link mit QR-Code und hält alle anderen mit einem Token, einem Cookie und den Prüfungen von Host und Origin draußen. Danach ein Blick zurück auf die ganze Serie.

Quest-Ziele

  • Den Server in deinem Netz lauschen lassen und wissen, was das öffnet
  • Ein Handy mit einem Token im #Fragment des Links und einem daraus abgeleiteten Cookie anmelden
  • Wissen, welche Prüfung was abhält: DNS-Rebinding, fremde Seiten, Sites in der Vorschau, Raten
  • Die Hooks auf diesem Rechner halten und Vorschau und Terminal hinter den Login stellen
  • Wissen, was einfaches HTTP im LAN nicht kann: Benachrichtigungen, Zwischenablage, Vertraulichkeit unterwegs
  • Die Seite auf einem Bildschirm in Handygröße benutzen

Claude Code baut, du machst Tee, und während die Frage zur Fußzeile auf dem Bildschirm des Laptops wartet, steckt dein Handy in der Tasche. Seit Teil 13 kann der Laptop klingen, aber die Frage zu dir bringen kann er nicht. Dieser letzte Teil bringt Sitesmith auf dein Handy, in deinem eigenen Netz.

Technisch ist das eine Option: den Server im Netz lauschen lassen statt nur auf 127.0.0.1. Die ganze Arbeit steckt in dem, was daraus folgt. Jede Prüfung bisher beruhte auf einer Tatsache: Wer sich verbindet, sitzt an diesem Rechner. Ab jetzt stimmt das nicht mehr, und Sitesmith ist keine harmlose Seite. Es tippt in Claude Code, und es zeigt ein Terminal, in dem eine Shell wartet, sobald Claude Code sich beendet (Teil 3). Wer die Seite benutzen kann, kann jeden Befehl mit deinen Rechten ausführen. In diesem Teil geht es deshalb vor allem darum, wer hineinkommt und welche Prüfung was draußen hält.

Dieselben Sites, dieselben Fragen: Sitesmith in deiner Tasche, in deinem eigenen Netz.
Dieselben Sites, dieselben Fragen: Sitesmith in deiner Tasche, in deinem eigenen Netz.

Im Netz lauschen

Der Server bekommt zwei neue Optionen und druckt einen QR-Code. Installier das Paket, das ihn zeichnet, und seine Typen:

~/sitesmith
$ npm install qrcode$ npm install --save-dev @types/qrcode

Oben in server/main.ts nennt der Kommentar die neuen Optionen, und zwei Importe kommen dazu: der QR-Code und server/access.ts, das du weiter unten schreibst.

server/main.ts
/**
 * Sitesmith's server: the API, live updates over server-sent events, the built page (dist/), and a
 * second server on a port of its own that shows the sites. It listens on this machine only, unless
 * --host opens it to your network.
 *
 *   node server/main.ts [--port 5400] [--sites ./sites] [--data ./.data] [--ollama URL] [--local-context 65536]
 *                       [--host 0.0.0.0] [--name my-pc.local]
 *
 * With --host, the server listens on your network too: your phone opens it with the login link it
 * prints. --name adds a host name the page may be opened by (every one you use, like my-pc.local).
 */
import fs from 'node:fs';
import http from 'node:http';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import QRCode from 'qrcode';
import { WebSocketServer } from 'ws';
import type { AnswerBody, Brain, Config, LocalModels, NewSite, ReplyBody, RequestBody, ServerEvent, Uploaded } from '../shared/types.ts';
import { Access, LOGIN_PAGE, lanAddresses } from './access.ts';
import { Agent, type HookEvent } from './agent.ts';
import { HttpError, fileIn, readJson, send, sendFile } from './http.ts';
import { requestText, runTitle } from './requests.ts';
import { NAME, OWN, Sites } from './sites.ts';
import { Terminals, type Target } from './terminals.ts';

Unter option() kommen options() für eine Option, die mehrmals angegeben werden darf, und die beiden Konstanten dafür, wo der Server lauscht:

server/main.ts
function option(name: string, fallback: string) {
  const i = process.argv.indexOf(name);
  return i > 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
}
/** every value of an option given more than once */
const options = (name: string) => process.argv.flatMap((a, i) => (a === name && process.argv[i + 1] ? [process.argv[i + 1]] : []));
const PORT = Number(option('--port', '5400'));
const PREVIEW_PORT = PORT + 2;
/** Vite's dev server (`npm run dev`), which forwards /api here */
const DEV_PORT = 5401;
const DIST = path.join(APP, 'dist');
/** where to listen: this machine only (127.0.0.1), or 0.0.0.0 for the network too */
const HOST = option('--host', '127.0.0.1');
const ON_NETWORK = HOST === '0.0.0.0';
// one address of the network alone would shut out the hooks, which always come over 127.0.0.1
if (!ON_NETWORK && HOST !== '127.0.0.1') throw new Error('--host takes 127.0.0.1 (this machine) or 0.0.0.0 (the network too)');

--host 0.0.0.0 lässt den Server auf jeder IPv4-Adresse des Rechners lauschen, Loopback eingeschlossen, also funktioniert localhost weiter. Ohne die Option lauscht er wie bisher auf 127.0.0.1, und nichts aus diesem Teil ist von außen erreichbar. Jeder andere Wert hält den Server gleich beim Start an. Auf nur einer Netzadresse zu lauschen, etwa 192.168.0.202, ließe 127.0.0.1 aus, und genau dort rufen die Hooks den Server immer auf (Teil 6): Jede Sitzung verlöre ihren Weg zurück zur Seite. --name fügt einen Hostnamen hinzu, unter dem die Seite geöffnet werden darf, etwa my-pc.local, falls dein Netz den Rechner unter einem kennt; die Option darf mehrmals vorkommen.

Dann ersetzt du den ganzen Abschnitt „who may ask“ mit ORIGINS, HOSTS, allowed() und allowedSocket() durch dies:

server/main.ts
/* ------------------------------------------------------------------ */
/* who may ask                                                          */
/* ------------------------------------------------------------------ */

/**
 * The names the page may be opened by: localhost, and on the network this machine's addresses
 * and the names you gave. Host and Origin must be one of them (no DNS rebinding, no foreign pages,
 * no previewed sites); anyone but your own browser here must have logged in (server/access.ts).
 */
const NAMES = ['localhost', '127.0.0.1', ...(ON_NETWORK ? lanAddresses() : []), ...options('--name')];
const access = new Access(DATA, { port: PORT, previewPort: PREVIEW_PORT, devPort: DEV_PORT, names: NAMES });

Die Namen sind das, womit die Host-Prüfung aus Teil 2 vergleicht: localhost und 127.0.0.1 immer, die Netzadressen des Rechners, wenn er im Netz lauscht, und die Namen, die du angegeben hast. Die Prüfungen selbst ziehen in eine eigene Klasse um.

Ein Token, auf der Platte aufbewahrt

Leg server/access.ts an. Sie beginnt mit drei Helfern:

server/access.ts
import crypto from 'node:crypto';
import fs from 'node:fs';
import type http from 'node:http';
import os from 'node:os';
import path from 'node:path';

const COOKIE = 'sitesmith';
const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);

/** This machine's addresses in its networks (IPv4, not loopback): where a phone finds it. */
export function lanAddresses() {
  return Object.entries(os.networkInterfaces())
    // the bridges of Docker and virtual machines lead nowhere a phone could be
    .filter(([name]) => !/^(docker|br-|veth|virbr)/.test(name))
    .flatMap(([, list]) => list ?? [])
    .filter((a) => a.family === 'IPv4' && !a.internal)
    .map((a) => a.address);
}

/** The request's cookies. Whatever a client sends, nothing here may throw: a bad value is no value. */
function cookies(req: http.IncomingMessage) {
  const out: Record<string, string> = {};
  for (const part of String(req.headers.cookie ?? '').split(';')) {
    const at = part.indexOf('=');
    if (at < 0) continue;
    try { out[part.slice(0, at).trim()] = decodeURIComponent(part.slice(at + 1).trim()); } catch { /* not ours */ }
  }
  return out;
}

/** Equal, compared in constant time: how long it takes says nothing about the secret. */
function same(a: string, b: string) {
  const [x, y] = [Buffer.from(a), Buffer.from(b)];
  return x.length === y.length && crypto.timingSafeEqual(x, y);
}

lanAddresses sammelt die IPv4-Adressen des Rechners, die nicht Loopback sind. Die virtuellen Netzwerkkarten von Docker und von virtuellen Maschinen (docker0, br-…, veth…, virbr…) überspringt sie: Die führen zu Containern und virtuellen Maschinen, nicht zu deinem Handy. Ein Rechner kann trotzdem mehr als eine echte Adresse haben, eine fürs Kabel und eine fürs WLAN, wie der, auf dem der Test lief.

cookies liest den Cookie-Header in ein Objekt. Was ein Client auch schickt, es darf nicht werfen: decodeURIComponent wirft bei einer kaputten Maskierung wie %zz, also bleibt ein Wert, den es nicht dekodieren kann, einfach weg. Diese Sorgfalt zählt, weil der Vorschau-Server diese Prüfungen außerhalb jedes try aufruft, wo eine Ausnahme den ganzen Server beenden würde, und einen Header kann jeder im Netz schicken.

same vergleicht zwei Geheimnisse in konstanter Zeit. Ein gewöhnlicher Vergleich hört beim ersten abweichenden Zeichen auf, er antwortet also etwas früher, je falscher ein Rateversuch ist, und mit genug Messungen verrät diese Zeit einem Angreifer, wie viele Zeichen gestimmt haben. timingSafeEqual vergleicht immer jedes Byte. Es braucht zwei Eingaben gleicher Länge in Bytes und wirft sonst, daher die Prüfung davor, an den beiden Buffern und nicht an den Strings: Ein Zeichen wie é zählt in einem String einmal, belegt aber zwei Bytes. Die Länge des Tokens ist kein Geheimnis.

Dann die Klasse, mit dem Token und den Namen:

server/access.ts
/**
 * Who may use Sitesmith. Your own browser on this machine may, as before. Anything else must have
 * logged in with the token: once, with the link the server prints, which sets a cookie. Host and
 * Origin are checked for every request, now against the LAN addresses too.
 */
export class Access {
  /** the secret in the login link; delete .data/token and restart to log every phone out */
  readonly token: string;
  /** the cookie's value: derived from the token, so the link itself is never stored in a browser */
  private session: string;
  private hosts = new Set<string>();
  private origins = new Set<string>();
  private previewHosts = new Set<string>();
  /** failed logins per address, for the last minute */
  private failures = new Map<string, number[]>();

  /** `names`: every host name the page may be opened by (localhost, LAN addresses, names you add) */
  constructor(data: string, opts: { port: number; previewPort: number; devPort: number; names: string[] }) {
    const file = path.join(data, 'token');
    try { this.token = fs.readFileSync(file, 'utf8').trim(); } catch { this.token = ''; }
    if (!this.token) {
      this.token = crypto.randomBytes(24).toString('base64url');
      fs.mkdirSync(data, { recursive: true });
      fs.writeFileSync(file, `${this.token}\n`, { mode: 0o600 });
    }
    this.session = crypto.createHmac('sha256', this.token).update('sitesmith session').digest('base64url');
    for (const name of opts.names) {
      for (const port of [opts.port, opts.devPort]) {
        this.hosts.add(`${name}:${port}`);
        this.origins.add(`http://${name}:${port}`);
      }
      this.previewHosts.add(`${name}:${opts.previewPort}`);
    }
  }

Das Token sind 24 zufällige Bytes aus der Zufallsquelle des Betriebssystems, 192 Bit, geschrieben als 32 Zeichen base64url, die ohne Maskierung in einen Link passen. Das errät niemand. Es kommt mit dem Modus 600 in .data/token, also kann nur dein Benutzer die Datei lesen, und es bleibt über Neustarts hinweg dort, damit ein Handy angemeldet bleibt, wenn du den Server neu startest. Lösch die Datei und starte neu, dann gibt es ein neues Token, und jedes Handy ist abgemeldet.

Der Wert des Cookies ist nicht das Token, sondern ein HMAC davon: ein Hash, den nur berechnen kann, wer das Token kennt. So führt der Server keine Liste von Sitzungen; er berechnet den einen gültigen Wert beim Start und vergleicht damit. Und das Token selbst landet nie im Cookie-Speicher eines Browsers. Halt das aber nicht für mehr, als es ist: Das Cookie ist so gut wie ein Login, 30 Tage lang. Wer es hat, ist drin, genau wie wer den Link hat.

Die Namen werden zu drei Mengen: den Hosts, unter denen Seite und API angefragt werden dürfen, auf dem Port des Servers und dem des Dev-Servers; den Origins unserer eigenen Seite; und den Hosts des Vorschau-Servers.

Wer was darf

Als Nächstes die Prüfungen, eine Methode für jede:

server/access.ts
/** Your own browser on this machine: a loopback address, and the page asked for by localhost. */
local(req: http.IncomingMessage) {
  const host = String(req.headers.host ?? '').replace(/:\d+$/, '');
  return LOOPBACK.has(req.socket.remoteAddress ?? '') && (host === 'localhost' || host === '127.0.0.1');
}

loggedIn(req: http.IncomingMessage) {
  const value = cookies(req)[COOKIE];
  return Boolean(value) && same(value, this.session);
}

/** The API and the page: a known host, you (here or logged in), and our own page's origin. */
allowed(req: http.IncomingMessage) {
  if (!this.hosts.has(req.headers.host ?? '')) return false;
  if (!this.local(req) && !this.loggedIn(req)) return false;
  const origin = req.headers.origin;
  return req.method === 'GET' || req.method === 'HEAD' || origin === undefined || this.origins.has(origin);
}

/** A terminal socket: the same, and the origin must be there and ours. */
allowedSocket(req: http.IncomingMessage) {
  return this.hosts.has(req.headers.host ?? '') && (this.local(req) || this.loggedIn(req)) && this.origins.has(req.headers.origin ?? '');
}

/** The preview server: a known host, and you. */
allowedPreview(req: http.IncomingMessage) {
  if (!this.previewHosts.has(req.headers.host ?? '')) return false;
  return LOOPBACK.has(req.socket.remoteAddress ?? '') || this.loggedIn(req);
}

/** The hooks run on this machine, and only there: never from the network, logged in or not. */
fromThisMachine(req: http.IncomingMessage) {
  return LOOPBACK.has(req.socket.remoteAddress ?? '');
}

/** No other page's script: a POST from a browser carries the origin of its page. */
ownOrigin(req: http.IncomingMessage) {
  const origin = req.headers.origin;
  return req.method === 'GET' || origin === undefined || this.origins.has(origin);
}

/** Whether the login page may be shown (a known host is enough: it has nothing to hide). */
knownHost(req: http.IncomingMessage) {
  return this.hosts.has(req.headers.host ?? '');
}
  • local ist dein eigener Browser auf diesem Rechner, und dafür braucht es zweierlei: Die Verbindung kommt von einer Loopback-Adresse, und die Seite wurde als localhost oder 127.0.0.1 angefragt. Die Adresse ist kein Header, den ein Client schreiben könnte; sie ist der Ursprung der TCP-Verbindung. Öffnest du die Seite auf diesem Rechner über seine Netzadresse, http://192.168.0.202:5400, zählst du als Netz und musst dich anmelden. Genau damit hat der Test unten das Handy gespielt.

  • allowed bewacht die API und die Seite. Zuerst der Host, wie in Teil 2: Eine fremde Website, deren Name plötzlich auf deinen Rechner zeigt (DNS-Rebinding), schickt im Host-Header immer noch ihren eigenen Namen und wird abgewiesen. Dann du: hier oder angemeldet. Dann der Origin, für alles außer GET und HEAD: Eine Seite von woanders oder eine Site in der Vorschau kann höchstens ein GET schicken, das nichts ändert, und der Browser lässt sie die Antwort nicht lesen.

  • allowedSocket bewacht den WebSocket des Terminals. Dieselben Regeln, aber der Origin muss da sein und unserer sein: Browser lassen seit Langem jede Seite ohne Rückfrage einen WebSocket zu jeder Adresse öffnen (neuere fangen an zu fragen, bevor eine öffentliche Seite dein Netz erreicht, aber darauf darf sich der Server nicht verlassen), wie Teil 4 erklärt hat, und dieser Socket tippt in eine Shell.

  • allowedPreview bewacht den Vorschau-Server: ein bekannter Host und du, auf diesem Rechner oder angemeldet. Ohne das könnte jeder im Netz deine Sites ansehen.

  • fromThisMachine ist für die Hooks, weiter unten.

  • knownHost genügt für die Login-Seite, die nichts zu verbergen hat.

Anmelden

Die letzte Methode der Klasse:

server/access.ts
  /**
   * A login with the token. Five wrong tries a minute per address, then a pause: the token is long
   * enough that guessing is hopeless, but there is no reason to let anyone try.
   */
  login(req: http.IncomingMessage, token: string): { ok: true; cookie: string } | { ok: false; status: number } {
    const who = req.socket.remoteAddress ?? '';
    const now = Date.now();
    const recent = (this.failures.get(who) ?? []).filter((t) => t > now - 60000);
    if (recent.length >= 5) return { ok: false, status: 429 };
    if (!same(token, this.token)) {
      this.failures.set(who, [...recent, now]);
      return { ok: false, status: 401 };
    }
    this.failures.delete(who);
    // HttpOnly: no script reads it; SameSite=Strict: no other site's page sends it along
    const cookie = `${COOKIE}=${this.session}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${60 * 60 * 24 * 30}`;
    return { ok: true, cookie };
  }
}

Fünf falsche Versuche pro Adresse und Minute; ein sechster in dieser Minute bekommt 429 und wird gar nicht erst geprüft, auch das richtige Token nicht. Bei 192 Bit ist Raten ohnehin aussichtslos, aber es gibt keinen Grund, jemanden in einer Schleife probieren zu lassen. Ein richtiges Token löscht die Einträge der Adresse.

Jedes Attribut des Cookies erledigt eine Sache:

  • HttpOnly: Kein Skript auf der Seite kann es lesen. Ein Skript, das durch irgendeinen Fehler in die Seite gerät, kann zwar Anfragen schicken, solange es läuft, aber das Cookie nicht davontragen.

  • SameSite=Strict: Der Browser lässt es bei jeder Anfrage weg, die eine Seite einer anderen Site auslöst. Eine fremde Seite, die ein Formular an dein Sitesmith schickt oder einen Link darauf setzt, kommt ohne Cookie an, also als nicht angemeldet.

  • Path=/ für den ganzen Server, Max-Age 30 Tage.

  • Kein Secure: Das würde dem Browser sagen, es nur über HTTPS zu schicken, und das hier ist HTTP.

Am Ende der Datei kommt die Login-Seite, als ein einziger String:

server/access.ts
/** The login page: it takes the token from the link's #fragment (never sent over the network by itself). */
export const LOGIN_PAGE = `<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="dark"><title>Sitesmith: log in</title>
<style>
body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #15130f; color: #f1ece4; font: 15px/1.5 system-ui, sans-serif; }
form { box-sizing: border-box; display: grid; gap: 12px; width: min(380px, calc(100vw - 32px)); padding: 24px; border: 1px solid #352f27; border-radius: 12px; background: #1d1a16; }
input { padding: 10px; border: 1px solid #4a4237; border-radius: 8px; background: #110f0c; color: inherit; font: 14px ui-monospace, monospace; }
button { padding: 10px; border: 0; border-radius: 8px; background: #ff8a3d; color: #1b120a; font-weight: 700; font-size: 15px; }
p { margin: 0; color: #9a9083; } .bad { color: #ff6f61; }
</style></head><body>
<form><h1 style="margin:0;font-size:20px">Sitesmith</h1>
<p>Open the link the server printed, or paste its token.</p>
<input name="token" autocomplete="off" aria-label="Token" placeholder="Token">
<button>Log in</button><p class="bad" aria-live="polite"></p></form>
<script>
const form = document.querySelector('form');
async function login(token) {
  const res = await fetch('/api/login', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token }) });
  if (res.ok) location.replace('/');
  else form.querySelector('.bad').textContent = res.status === 429 ? 'Too many tries: wait a minute.' : 'That token is not right.';
}
form.onsubmit = (e) => { e.preventDefault(); login(form.token.value.trim()); };
// the link's token, also when the link is opened on this page (only the #fragment changes then)
function fromLink() { if (location.hash.length > 1) { const t = location.hash.slice(1); history.replaceState(null, '', '/login'); login(t); } }
window.addEventListener('hashchange', fromLink);
fromLink();
</script></body></html>
`;

Sie bringt ihren Stil und ihr Skript selbst mit, weil der Browser, der sie sieht, noch nicht angemeldet ist und keine der Dateien der gebauten Seite bekäme. Ihr wichtigster Kniff ist, woher das Token kommt: Der Link setzt es hinter ein #. Dieses Fragment schicken Browser nie an den Server; es bleibt im Browser. Das Token steht also nicht in der Anfragezeile, in keinem Log und nicht im Referer-Header einer späteren Anfrage. Das Skript liest es, entfernt es mit history.replaceState aus der Adressleiste und schickt es an /api/login. Hat das geklappt, geht es weiter zur Seite.

Der Listener für hashchange kam aus dem Testen: Öffnet man den Link, während die Login-Seite schon offen ist, ändert sich nur das Fragment, und die Seite lädt nicht neu. Du kannst das Token auch in das Feld einfügen.

Das Fragment hält das Token aus Logs und Adressen heraus, nicht aus dem Netz. Über einfaches HTTP trägt die Login-Anfrage es lesbar für jeden, der den Verkehr sehen kann, und jede spätere Anfrage trägt das Cookie genauso. Mehr dazu weiter unten.

Die Haustür

Zurück in server/main.ts kommt die Login-Route in die Liste der Routen (im Download steht sie direkt über den Routen der Hooks):

server/main.ts
['POST', /^\/api\/login$/, async (req, res) => {
  const { token } = await readJson<{ token: string }>(req);
  const result = access.login(req, String(token ?? ''));
  if (!result.ok) throw new HttpError(result.status, result.status === 429 ? 'too many tries' : 'wrong token');
  res.setHeader('set-cookie', result.cookie);
  send(res, 200, {});
}],

Und du ersetzt den Request-Handler des Servers:

server/main.ts
const server = http.createServer(async (req, res) => {
  const url = new URL(req.url ?? '/', 'http://localhost');
  try {
    // the login page and the login itself need no login, only a known host
    if (url.pathname === '/login' || url.pathname === '/api/login') {
      if (!access.knownHost(req) || !access.ownOrigin(req)) throw new HttpError(403, 'forbidden');
      if (url.pathname === '/login') { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }); res.end(LOGIN_PAGE); return; }
    } else if (!access.allowed(req)) {
      // a phone that is not logged in yet: to the login page
      if (req.method === 'GET' && !url.pathname.startsWith('/api/') && access.knownHost(req)) { res.writeHead(302, { location: '/login' }); res.end(); return; }
      throw new HttpError(403, 'forbidden');
    }
    // the hooks run on this machine: never from the network, logged in or not
    if (url.pathname.startsWith('/api/hooks/') && !access.fromThisMachine(req)) throw new HttpError(403, 'forbidden');
    if (url.pathname.startsWith('/api/')) {
      const route = routes.find(([method, re]) => method === req.method && re.test(url.pathname));
      if (!route) throw new HttpError(404, 'not found');
      await route[2](req, res, url.pathname.match(route[1])!);
      return;
    }
    // the page: its built files, and index.html for every other address
    if (!fs.existsSync(path.join(DIST, 'index.html'))) {
      throw new HttpError(503, `The page is not built: run npm run build, or use the dev server on port ${DEV_PORT}.`);
    }
    sendFile(res, fileIn(DIST, url.pathname) ?? path.join(DIST, 'index.html'), { 'cache-control': 'no-cache' });
  } catch (err) {
    const status = err instanceof HttpError ? err.status : 500;
    if (status === 500) console.error(err);
    if (!res.headersSent) send(res, status, { error: err instanceof Error ? err.message : String(err) });
    else res.end();
  }
});

Die Login-Seite und der Login selbst brauchen keinen Login, nur einen bekannten Host, der weiterhin DNS-Rebinding draußen hält, und für den Login unsere eigene Herkunft (access.ownOrigin), damit ein Skript auf einer anderen Seite im Browser des Handys deine fünf Versuche nicht aufbrauchen kann. Das Token selbst schützen seine Länge und diese fünf Versuche pro Minute. Alles andere geht durch access.allowed. Ein Browser, der nicht angemeldet ist und eine Seite anfragt, nicht die API, wird nach /login geschickt, so landet ein Handy auf der Login-Seite, wenn du die bloße Adresse eintippst. Die API antwortet mit 403.

Dann die Hooks. Ihre Routen nehmen die Ereignisse von Claude Code entgegen und reichen die Antworten der Seite an die wartenden Hooks weiter, und nur ein Programm ruft sie je auf: server/hook.ts, das in den Sitzungen auf diesem Rechner läuft. Nichts auf deinem Handy hat dort etwas zu suchen, also kommt nichts aus dem Netz hinein, egal welches Cookie es mitbringt.

Der Upgrade-Handler für das Terminal ändert sich an einer Stelle: Er fragt access.allowedSocket.

server/main.ts
// /api/sites/<name>/session/socket?cols=..&rows=..: the session on a page's screen
server.on('upgrade', (req, socket, head) => {
  const url = new URL(req.url ?? '/', 'http://localhost');
  const m = url.pathname.match(/^\/api\/sites\/([^/]+)\/session\/socket$/);
  let t: Target | null = null;
  try { if (m && access.allowedSocket(req)) t = target(m[1]); } catch { /* no such site */ }
  if (!t) { socket.destroy(); return; }
  const size = (key: string, fallback: number) => Math.min(500, Math.max(10, Number(url.searchParams.get(key)) || fallback));
  sockets.handleUpgrade(req, socket, head, (ws) => terminals.attach(ws, t, size('cols', 120), size('rows', 36)));
});

Der Vorschau-Server fragt access.allowedPreview:

server/main.ts
/**
 * The sites, at /<name>/ on a port of their own. A site is code Claude Code wrote: served from the
 * page's own address, its scripts could call the API just like the page does. From another port
 * it is another origin, and access.allowed() turns it away. Hidden files (.sitesmith/ with the requests)
 * are not shown.
 */
const preview = http.createServer((req, res) => {
  const url = new URL(req.url ?? '/', 'http://localhost');
  const [, name = '', ...rest] = url.pathname.split('/');
  const site = access.allowedPreview(req) ? sites.read(name) : null;
  // /<name> without the slash: the site's relative links need it
  if (site && !rest.length) { res.writeHead(302, { location: `/${name}/` }); res.end(); return; }
  const file = site && !hiddenPath(rest.join('/')) ? fileIn(sites.dir(name), rest.join('/')) : null;
  if (!file) { res.writeHead(404, { 'content-type': 'text/html; charset=utf-8' }); res.end(MISSING); return; }
  sendFile(res, file, { 'cache-control': 'no-store' });
});

Das funktioniert, weil Cookies Ports ignorieren. Ein Cookie, das 192.168.0.202:5400 gesetzt hat, wird auch an 192.168.0.202:5402 geschickt, also trägt der Vorschau-Rahmen auf dem Handy es mit, und der Vorschau-Server kann es prüfen. Das gilt in beide Richtungen. Die Sites in der Vorschau sind Code, den Claude Code geschrieben hat, und ihre Anfragen an die API tragen das Cookie ebenfalls: Für SameSite sind sie dieselbe Site, nur der Port ist ein anderer. Deshalb bleibt die Origin-Prüfung: Ein POST vom Origin der Vorschau wird abgelehnt, mit Cookie oder ohne.

Zuletzt lauscht der Server, wo man es ihm gesagt hat, und druckt die Links:

server/main.ts
const SERVER_FILE = path.join(DATA, 'server.json');
server.listen(PORT, HOST, async () => {
  // the hooks of the sessions find the server through this file
  fs.writeFileSync(SERVER_FILE, `${JSON.stringify({ port: PORT, pid: process.pid })}\n`);
  console.log(`Sitesmith: http://localhost:${PORT}/`);
  if (!ON_NETWORK) return;
  // the login links, the first one as a QR code for the phone's camera
  const links = NAMES.filter((n) => n !== 'localhost' && n !== '127.0.0.1').map((n) => `http://${n}:${PORT}/login#${access.token}`);
  console.log('\nOn your phone (same network), open:');
  for (const link of links) console.log(`  ${link}`);
  if (links[0]) console.log(await QRCode.toString(links[0], { type: 'terminal', small: true }));
});
preview.listen(PREVIEW_PORT, HOST);

Ein Link pro Netzadresse und pro --name, und der erste noch einmal als QR-Code für die Kamera deines Handys. Der erste ist nicht unbedingt einer, den dein Handy erreicht: Auf einem Rechner in zwei Netzen nimm den Link, dessen Adresse im Netz deines Handys liegt. Der Vorschau-Server lauscht auf demselben Host wie der Server.

Auf einem Bildschirm in Handygröße

Das meiste am Handy-Layout steht seit Teil 2 in style.css, in einem Block für Bildschirme bis 900 Pixel Breite: Die Seitenleiste wird zur Leiste oben, die Sites zu einer Reihe, die seitwärts scrollt, und Auftragsfeld und Verlauf kommen vor der Vorschau, die den Großteil der Bildschirmhöhe bekommt. Eine Sache braucht Code. Mit den Sites in einer Reihe kann die offene aus dem Blick gescrollt sein. In src/sidebar.ts bekommt die Klasse unter list ein Feld, das sich merkt, welche Site sie zuletzt gezeigt hat:

src/sidebar.ts
export class Sidebar {
  readonly el: HTMLElement;
  private list = h('nav', { class: 'site-list', 'aria-label': 'Sites' });
  /** the site last scrolled into view */
  private shown = '';

und render zwei Zeilen an seinem Ende:

src/sidebar.ts
render(sites: Site[], current: string, agents: Map<string, AgentState>, terminals: TerminalState[]) {
  this.list.replaceChildren(...sites.map((s) => {
    const status = siteStatus(agents.get(s.name), terminals.find((t) => t.site === s.name));
    return h('a', {
      class: 'site-link',
      href: `#site/${s.name}`,
      'aria-current': s.name === current ? 'page' : null,
    },
    h('span', { class: 'site-title' }, s.title),
    h('span', { class: 'site-name' }, s.name),
    status ? h('span', { class: 'site-state' },
      status.dot === 'ask' ? h('span', { class: 'badge' }, '?') : h('span', { class: `dot ${status.dot}`, 'aria-hidden': 'true' }),
      status.text ? h('span', { class: 'site-state-text' }, status.text) : null) : null);
  }));
  if (!sites.length) this.list.append(h('p', { class: 'hint' }, 'No sites yet.'));
  // on a phone the list scrolls sideways: the open site in view, when another one opens
  if (current !== this.shown) this.list.querySelector('[aria-current]')?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
  this.shown = current;
}

Die Liste scrollt nur, wenn eine andere Site aufgegangen ist. render läuft bei jedem Ereignis vom Server, viele Male in der Minute, während Claude Code arbeitet, und jedes Mal zurückzuscrollen würde zunichtemachen, was dein Daumen gerade getan hat. Mit 'nearest' scrollt scrollIntoView nur so weit wie nötig, und gar nicht, wenn der Link schon zu sehen ist.

Probier es aus

Das Handy erreicht den Server, nicht den Dev-Server von Vite, der nur auf diesem Rechner lauscht. Bau die Seite also zuerst mit npm run build und starte dann den Server im Netz (npm start -- --host 0.0.0.0 erledigt beides in einem Zug):

~/sitesmith
$ npm run server -- --host 0.0.0.0Sitesmith: http://localhost:5400/On your phone (same network), open:  http://192.168.0.202:5400/login#TOKEN  http://192.168.1.137:5400/login#TOKEN# TOKEN stands for the 32 characters of the token. A QR code of the first link follows,# drawn with block characters.

Scann den QR-Code mit deinem Handy oder tipp einen der Links ein. Die Login-Seite nimmt das Token aus dem Link und reicht dich an Sitesmith weiter. Öffnest du stattdessen die bloße Adresse, bekommst du die Login-Seite ohne Token:

Die Login-Seite auf einem Bildschirm in Handygröße. Mit dem Link geöffnet, meldet sie sich selbst an; ohne ihn lässt sich das Token aus der Ausgabe des Servers in das Feld einfügen.

Angemeldet ist es die Seite, die du kennst, eingerichtet für den schmalen Bildschirm:

Sitesmith in einem Browser in Handygröße über die Netzadresse des Rechners: die Sites in einer Reihe, die seitwärts scrollt, das Auftragsfeld und darunter die Vorschau. Der Schalter oben sagt Sound on, weil Benachrichtigungen über einfaches HTTP von einem anderen Gerät nicht verfügbar sind. Die Auswahl des Gehirns stammt aus Teil 15.Den Screenshot in voller Größe öffnen
Sitesmith in einem Browser in Handygröße über die Netzadresse des Rechners: die Sites in einer Reihe, die seitwärts scrollt, das Auftragsfeld und darunter die Vorschau. Der Schalter oben sagt Sound on, weil Benachrichtigungen über einfaches HTTP von einem anderen Gerät nicht verfügbar sind. Die Auswahl des Gehirns stammt aus Teil 15.

Kommt das Handy gar nicht durch, ist meist eine Firewall auf dem Rechner der Grund: Sie muss die Ports 5400 und 5402 hereinlassen.

Für diese Serie liefen die Prüfungen von den eigenen Netzadressen des Testrechners aus, die genau wie ein Handy als „nicht dieser Rechner“ zählen. Dieser Server lauschte auf Port 5410, seine Vorschau auf 5412:

Terminal
# From this machine's own LAN addresses, so they count as "not this machine".# This test server listened on port 5410, its preview on 5412.1 page without login:        302 → http://192.168.0.202:5410/login2 API without login:         4033 wrong token, tries 1–5:    401 401 401 401 4013 wrong token, try 6:        429      (that address is locked out for a minute)4 right token (other address): 200, cookie set: sitesmith=…; HttpOnly; SameSite=Strict; Path=/; Max-Age=25920005 API with the cookie:       2005 POST, own origin:          400      (got through; the empty body was refused)5 POST, origin evil.example: 4036 hooks route from the LAN, with the cookie: 4037 preview without cookie:    404      (preview server on 5412)7 preview with cookie:       2009 localhost, no login:       2009 hooks from localhost:      200x foreign Host header:       403# The terminal's socket, from the LAN:no cookie:                         refused: socket hang upcookie, foreign origin:            refused: socket hang upcookie, own origin (no session):   closed 4404

Zeile für Zeile: Eine Seite ohne Login wird zur Login-Seite geschickt, und die API lehnt ab. Fünf falsche Tokens bekommen 401, das sechste 429, und weil diese Adresse nun für eine Minute gesperrt war, kam das richtige Token von der zweiten Adresse: 200, und das Cookie mit den Attributen von oben. Mit dem Cookie antwortet die API. Ein POST von unserem eigenen Origin kam bis zu seiner Route durch, die den leeren Body ablehnte; derselbe POST mit fremdem Origin kam nicht so weit. Die Routen der Hooks weisen das Netz ab, mit Cookie oder ohne. Die Vorschau zeigt ohne Cookie nichts und mit Cookie die Site. Auf localhost funktioniert alles ohne Login, wie bisher, und ein fremder Host-Header wird abgelehnt. Der Socket des Terminals wurde ohne Cookie und mit fremdem Origin geschlossen. Mit Cookie und eigenem Origin kam er durch jede Prüfung, und der Server schloss ihn nur, weil die Site keine Sitzung hatte (4404).

Dann ein Browser in Handygröße (390 × 844 Pixel, mit Touch) über die Netzadresse: Ohne Login landete er auf /login, nach dem Link auf der Seite, mit dem Schalter auf Sound on, und der Vorschau-Rahmen lud. Auch er war zuerst für eine Minute gesperrt, durch die falschen Versuche der Prüfungen davor: Das Limit tut, was es soll.

Was einfaches HTTP nicht kann

http://192.168.0.202:5400 ist kein sicherer Kontext: Der Browser kann nicht wissen, ob etwas zwischen ihm und dem Server den Verkehr liest oder verändert, und er tut recht daran, es nicht anzunehmen. Daraus folgen drei Dinge.

  • Keine Benachrichtigungen. Der Schalter aus Teil 13 bietet dort nur den Klang an.

  • Keine Zwischenablage. Das Kopieren aus dem Terminal (Teil 4) benutzt die Zwischenablage-API des Browsers, und die bekommen nur sichere Seiten. Auf dem Handy wird nichts kopiert.

  • Nichts Vertrauliches unterwegs. Das Token beim Login, das Cookie bei jeder Anfrage, alles, was du ins Terminal tippst, und alles, was Claude Code zeigt, reisen unverschlüsselt. In deinem Heimnetz nehmen viele das für ein Werkzeug wie dieses in Kauf; in einem Netz, das du mit Fremden teilst, tu es nicht.

HTTPS würde alle drei beheben. Es ist die erste Idee in der Liste am Ende.

Was du gebaut hast

Vor sechzehn Teilen war Claude Code ein Programm in einem Terminal. Schau, was jetzt drumherum steht:

  • tmux-Sitzungen, eine pro Site, die den Server überleben und an die du dich jederzeit aus deinem eigenen Terminal hängen kannst;

  • ein Server, der Aufträge eintippt und den Bildschirm nur dort liest, wo nichts anderes sagt, was los ist: der Prompt, der Vertrauensdialog, der Modus;

  • Hooks, die jeden Schritt melden und die Fragen, Berechtigungsabfragen und Pläne von Claude Code festhalten, bis die Seite geantwortet hat;

  • eine Seite mit dem Terminal selbst, einem Verlauf dessen, was Claude Code tut, seiner Zusammenfassung und Dialogen mit Vorschauen für seine Fragen;

  • einen Ausweg für alles, was die Seite nicht beantworten kann: den Terminal-Tab, das Zurückgeben einer Frage, Hooks, die auf einen neu startenden Server warten;

  • mehrere Sites gleichzeitig, einen Klang, wenn eine dich braucht, Dateien und Bilder für Claude Code;

  • ein lokales Modell als Gehirn für jede Site, die auf deinem Rechner bleiben soll;

  • und einen Login, damit all das in deine Tasche passt.

Und nirgends ein API-Key: Alles läuft über Claude Code, wie du es jeden Tag benutzt, mit deinen Einstellungen und deinen Skills, über dein Abo oder mit einem eigenen Modell.

Wie es weitergehen kann

  • HTTPS in deinem Netz. Mit einem Zertifikat davor funktionieren Benachrichtigungen und Zwischenablage auf dem Handy, und der Verkehr ist verschlüsselt. Ein Reverse Proxy wie Caddy kann das, oder ein VPN, das für seine Geräte Zertifikate ausstellt. Eine Sache muss sich vorher ändern: Sitesmith vertraut der Loopback-Adresse, und ein Proxy auf demselben Rechner lässt jede Anfrage von dort kommen. Die Prüfung der Hooks, die der Vorschau und die Versuche pro Adresse richten sich alle nach dieser Adresse, also müsste access.ts von dem Proxy wissen. Für die Serie wurde das nicht ausprobiert.

  • Eine Geschichte pro Site. Mach den Ordner jeder Site zu einem Git-Repository und lass Claude Code nach jedem Auftrag committen. Die Seite könnte die Commits auflisten und eine Site zu jedem davon zurückbringen.

  • Veröffentlichen. Eine Site ist ein Ordner statischer Dateien. Ein Knopf, der ihn zu einem Webhoster kopiert oder Claude Code bittet, ihn zu veröffentlichen, ist ein kleiner Schritt.

  • Claude Code prüft seine eigene Arbeit. Gib den Sitzungen einen Weg, das Ergebnis in einem Browser anzusehen, und schreib in den Auftrag, dass es die Seite auf einem schmalen Bildschirm ansehen soll, bevor es sagt, dass es fertig ist.

  • Andere Arten von Ordnern. Nichts an den tmux-Sitzungen, den Hooks oder den Dialogen hat mit Websites zu tun; nur die Anleitung in CLAUDE.md, der Text des Auftrags und die Vorschau. Tausch die aus, und dieselbe Maschinerie steuert Claude Code für einen Ordner mit Dokumentation, eine kleine App, alles, was du gern vom Sofa aus beschreiben würdest.

Was sich zu behalten lohnt, ist die Form des Ganzen. Das Programm bleibt das echte, mit allem, was es kann, und dein Code sitzt drumherum: Er tippt, er hört den Hooks zu, er liest den Bildschirm nur dort, wo nichts anderes ihm sagt, was los ist, und jedes Warten hat einen Ausweg. Und weil dieses Programm auf deinem Rechner alles kann, prüft jeder Weg hinein, wer da fragt, jedes Mal.

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.