@tequila99/githuman 0.9.1 → 0.11.0

package/README.md

@@ -61,14 +61,56 @@ node dist/cli/index.js serve
 `git rev-parse --show-toplevel` от текущей директории).
 
 ```bash
-node dist/cli/index.js serve --port 4000 --host 0.0.0.0   # LAN-доступ, см. предупреждение ниже
+node dist/cli/index.js serve --port 4000 --host 0.0.0.0   # LAN-доступ, см. ниже
 node dist/cli/index.js list --status in_progress            # список ревью без веб-интерфейса
 node dist/cli/index.js export last --format markdown -o review.md
 ```
 
-> **Осторожно с `--host 0.0.0.0`**: сервер по умолчанию не требует
-> аутентификации. Открывая его в локальной сети, любой в этой сети сможет
-> просматривать содержимое репозитория.
+### Браузерная совместимость
+
+Production JS и CSS собираются с целью Chrome 103 и новее; для остальных
+браузеров цели — Edge 111, Firefox 114, Safari/iOS 16.4. Мобильная компоновка,
+Notes и терминал проверены в Chrome 103 на Android 13 в эмуляторе.
+Цель сборки не добавляет полифилы всех браузерных API: отдельные возможности
+(например, fullscreen) зависят от поддержки браузером. CSS Quasar и редактора
+заметок (Milkdown) использует `:has()` и `dvh`; в Chrome до 105/108 эти правила
+пропускаются, и меняется только оформление отдельных элементов.
+
+### Доступ из локальной сети
+
+`--host` принимает `localhost` (по умолчанию), `127.0.0.1`, `::1`, а для
+доступа из сети — `0.0.0.0` (IPv4) или `::` (IPv4 и IPv6). Конкретный
+LAN-адрес не принимается: без loopback-слушателя некому подтвердить
+устройство. При запуске на всех интерфейсах консоль печатает
+`http://localhost:<порт>` и LAN-адреса машины.
+
+Устройство из сети получает доступ только после сопряжения:
+
+1. Откройте LAN-адрес на телефоне или другой машине (адрес и QR-код —
+   в пункте меню **Devices** вкладки на `localhost`).
+2. Нажмите **Request access**: устройство покажет шестизначный код.
+3. Во вкладке на `localhost` появится запрос. Введите в нём код с экрана
+   устройства и нажмите **Approve**. Без открытой localhost-вкладки запрос
+   истекает через 2 минуты; консоль сервера печатает только факт запроса,
+   без кода.
+
+Доверенное устройство работает со всем приложением, включая терминал и
+агентов. Доступ хранится в cookie браузера и в
+`.githuman/ght-reviews.db` (по базе на репозиторий) и истекает через 30 дней
+без активности. Отзыв — в **Devices**: открытые терминал и чаты устройства
+закрываются сразу (если тот же репозиторий открыт вторым сервером на другом порту — в течение 2 секунд). Управлять устройствами можно только с `localhost`.
+
+Сервер принимает из сети только адреса своих интерфейсов в заголовке
+`Host` — это защищает от DNS rebinding. Другое имя (например, имя машины в
+Tailscale) разрешается флагом `--allowed-host <имя>`, его можно повторять.
+Прокси на той же машине должен передавать `X-Forwarded-For`, иначе его
+запросы выглядят локальными; `ssh -L` — локальный доступ самого пользователя.
+
+> **Осторожно:** соединение идёт по обычному HTTP. Тот, кто слушает ту же
+> сеть Wi-Fi, может перехватить cookie доверенного устройства и получить
+> доступ к терминалу. Используйте LAN-доступ только в сети, которой доверяете.
+> Cookie не разделяются по портам: другой веб-сервер на этой же машине тоже
+> получит cookie устройства.
 
 ### Агенты
 
@@ -94,10 +136,9 @@ node dist/cli/index.js export last --format markdown -o review.md
   `{ "cursor": { "args": ["--model", "<модель>", "acp"] } }`. Допустимы поля
   `command`, `args`, `env`; любое другое (в том числе опечатка) — ошибка
   при запуске сервера.
-- **Только локально.** Агентские маршруты работают лишь при `--host`
-  localhost/127.0.0.1/::1 (иначе это удалённое выполнение команд для всей
-  сети) и отклоняют чужие `Origin`/`Host`. Открывайте приложение по
-  `http://localhost:<порт>`.
+- **Кто может запускать.** Агентские маршруты принимают запросы с этой
+  машины и с доверенных устройств (см. «Доступ из локальной сети») и
+  отклоняют чужие `Origin`/`Host`.
 
 ### Данные и совместимость с оригинальным mcollina/githuman
 
@@ -200,7 +241,7 @@ MIT, см. [LICENSE](LICENSE).
 
 Повтор команды текущей половины возвращает обычный размер и позицию. Перетаскивание заголовка из половины тоже возвращает обычный размер; ручной resize снимает режим половины. Сочетания работают при вводе в терминале и формах, но отключены в модальных диалогах. Win означает Super/Meta (на macOS — Command вместе с Ctrl). Системные сочетания ОС могут перехватываться до браузера.
 
-Если платформенный бинарник PTY недоступен, терминал работает в ограниченном режиме с баннером: команды вводятся в поле под выводом, Ctrl+C прерывает команду, Ctrl+D закрывает shell. `vim`, `less` и другие интерактивные программы требуют PTY. В LAN терминал отключён. Переключатель исходных цветов отключает минимальный контраст для программ со своей палитрой.
+Если платформенный бинарник PTY недоступен, терминал работает в ограниченном режиме с баннером: команды вводятся в поле под выводом, Ctrl+C прерывает команду, Ctrl+D закрывает shell. `vim`, `less` и другие интерактивные программы требуют PTY. Из сети терминал доступен только доверенному устройству. Переключатель исходных цветов отключает минимальный контраст для программ со своей палитрой.
 
 Для разработки на другом порту backend можно передать `GITHUMAN_DEV_API=http://localhost:3848` при запуске Quasar dev-сервера.
 

package/dist/cli/config.js

@@ -1,6 +1,11 @@
+import { isIP } from 'node:net';
 import { parseArgs } from 'node:util';
+import { isLoopbackHost } from "../shared/network/loopback.js";
+import { WILDCARD_HOSTS } from "../server/utils/lan-addresses.js";
 const DEFAULT_PORT = 3847;
 const DEFAULT_HOST = 'localhost';
+// One DNS name: dot-separated labels of letters, digits and inner hyphens.
+const HOST_NAME_PATTERN = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
 /**
  * Default prefix for filenames written under `.githuman/` (e.g.
  * `ght-reviews.db`). The original mcollina/githuman CLI reads and writes
@@ -42,8 +47,33 @@ function resolvePort(explicit) {
     }
     return parsed;
 }
+/**
+ * Only loopback or every interface (ADR 0079). With one LAN address there
+ * is no loopback listener, so no local tab can approve a device.
+ */
 function resolveHost(explicit) {
-    return explicit !== undefined && explicit.length > 0 ? explicit : DEFAULT_HOST;
+    if (explicit === undefined || explicit.length === 0) {
+        return DEFAULT_HOST;
+    }
+    if (WILDCARD_HOSTS.has(explicit) ||
+        (isLoopbackHost(explicit) && !explicit.startsWith('['))) {
+        return explicit;
+    }
+    throw new Error(`Invalid --host value "${explicit}": use localhost (default), or 0.0.0.0 or :: for access from the local network`);
+}
+/** Exact host names only: no scheme, port, path, userinfo or wildcard. */
+function resolveAllowedHosts(values) {
+    return values.map(value => {
+        const name = String(value).toLowerCase();
+        // A loopback name allows nothing: local requests are found by the socket.
+        const loopback = name === 'localhost' ||
+            name.endsWith('.localhost') ||
+            name.startsWith('127.');
+        if (loopback || (!HOST_NAME_PATTERN.test(name) && isIP(name) !== 4)) {
+            throw new Error(`Invalid --allowed-host value "${String(value)}": give an exact non-loopback host name or IPv4 address, for example machine.tailnet.ts.net. IPv6 literals are not accepted.`);
+        }
+        return name;
+    });
 }
 export function parseServeArgs(argv) {
     const { values } = parseArgs({
@@ -55,7 +85,8 @@ export function parseServeArgs(argv) {
             'no-open': { type: 'boolean', default: false },
             'notes-dir': { type: 'string' },
             'db-prefix': { type: 'string' },
-            'api-docs': { type: 'boolean', default: false }
+            'api-docs': { type: 'boolean', default: false },
+            'allowed-host': { type: 'string', multiple: true }
         },
         strict: false
     });
@@ -64,12 +95,14 @@ export function parseServeArgs(argv) {
     const open = values['no-open'] === true ? false : values.open !== false;
     const dbPrefix = resolveDbPrefix(typeof values['db-prefix'] === 'string' ? values['db-prefix'] : undefined);
     const apiDocs = values['api-docs'] === true;
+    const allowedHosts = resolveAllowedHosts(Array.isArray(values['allowed-host']) ? values['allowed-host'] : []);
     return {
         port,
         host,
         open,
         dbPrefix,
         apiDocs,
+        allowedHosts,
         ...(typeof values['notes-dir'] === 'string'
             ? { notesDir: values['notes-dir'] }
             : process.env.GITHUMAN_NOTES_DIR

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import { writeFileSync } from 'node:fs';
 import { parseServeArgs } from "./config.js";
 import { startServer, resolveRepositoryPath, resolveReviewsDbPath } from "./server-runtime.js";
 import { formatStartupMessage } from "./startup-message.js";
+import { lanAddresses } from "../server/utils/lan-addresses.js";
 import { parseListArgs, runList } from "./commands/list.js";
 import { parseExportArgs, runExport } from "./commands/export.js";
 import { createFileDatabase } from "../server/db/index.js";
@@ -47,7 +48,7 @@ async function main(argv) {
             };
             process.once('SIGINT', shutdown);
             process.once('SIGTERM', shutdown);
-            console.log(formatStartupMessage(url, options.host));
+            console.log(formatStartupMessage(url, lanAddresses(options.host)));
             return;
         }
         case 'list': {

package/dist/cli/server-runtime.js

@@ -6,8 +6,8 @@ import { fileURLToPath } from 'node:url';
 import { buildApp } from "../server/app.js";
 import { createFileDatabase } from "../server/db/index.js";
 import { resolveDbPrefix } from "./config.js";
-import { isLoopbackHost } from "../shared/network/loopback.js";
 import { loadAgentPresets } from "../server/config/agents.js";
+import { WILDCARD_HOSTS } from "../server/utils/lan-addresses.js";
 const execFileAsync = promisify(execFile);
 function resolveStaticRoot() {
     // Compiled layout: dist/cli/server-runtime.js sits next to dist/web/.
@@ -58,6 +58,8 @@ export function resolveAgentsConfigPath(repositoryPath, dbPrefix) {
 export async function startServer(options) {
     const repositoryPath = await resolveRepositoryPath(process.cwd());
     const db = createFileDatabase(resolveReviewsDbPath(repositoryPath, options.dbPrefix));
+    // Agents and the terminal exist on every bind. Their hooks decide per
+    // request: a request from this machine or a trusted device (ADR 0079).
     const app = buildApp({
         staticRoot: resolveStaticRoot(),
         repositoryPath,
@@ -66,18 +68,19 @@ export async function startServer(options) {
         db,
         watchFiles: true,
         apiDocs: options.apiDocs === true,
-        loopbackBind: isLoopbackHost(options.host),
-        terminalEnabled: isLoopbackHost(options.host),
-        // Agents can run commands, so they are only offered on a loopback bind.
-        ...(isLoopbackHost(options.host)
-            ? {
-                agentPresets: loadAgentPresets(resolveAgentsConfigPath(repositoryPath, options.dbPrefix))
-            }
-            : {})
+        allowedHosts: options.allowedHosts ?? [],
+        onPairingRequest: device => console.log(`Pairing request from ${device.name} (${device.address}). Enter the code from the device in a localhost tab.`),
+        terminalEnabled: true,
+        agentPresets: loadAgentPresets(resolveAgentsConfigPath(repositoryPath, options.dbPrefix))
     });
     const address = await app.listen({ port: options.port, host: options.host });
+    // A wildcard bind reports its own address (`http://[::]:3847`), which is
+    // not a local Host. The operator tab must use localhost to approve devices.
+    const url = WILDCARD_HOSTS.has(options.host)
+        ? `http://localhost:${new URL(address).port}`
+        : address;
     if (options.open) {
-        openBrowser(address);
+        openBrowser(url);
     }
-    return { app, url: address };
+    return { app, url };
 }

package/dist/cli/startup-message.js

@@ -1,8 +1,9 @@
-import { isLoopbackHost } from "../shared/network/loopback.js";
-export function formatStartupMessage(url, host) {
+import { addressUrl } from "../shared/network/address-url.js";
+export function formatStartupMessage(url, lanAddresses) {
     const lines = [`githuman listening on ${url}`];
-    if (!isLoopbackHost(host)) {
-        lines.push('Warning: server is reachable from your local network without authentication.', 'Agent chat is disabled: it is only available when listening on localhost.');
+    if (lanAddresses.length > 0) {
+        const port = Number(new URL(url).port);
+        lines.push(...lanAddresses.map(address => `Local network: ${addressUrl(address, port)}`), 'Other devices request access at a local network address. Approve them in a localhost tab.', 'Warning: traffic is plain HTTP. Anyone on this network can read it, including device cookies.');
     }
     return lines.join('\n');
 }

package/dist/server/app.js

@@ -33,8 +33,21 @@ import { createSessionRegistry } from "./services/agent/session-registry.js";
 import { createTestDatabase } from "./db/index.js";
 import { createEventBus } from "./event-bus.js";
 import { watchRepository } from "./services/file-watcher.service.js";
+import fastifyCookie from '@fastify/cookie';
+import fastifyPlugin from 'fastify-plugin';
+import { DeviceService } from "./services/device.service.js";
+import { DeviceConnections } from "./services/device-connections.js";
+import { createAccessHook } from "./hooks/access/require-access.js";
+import { deviceRoutes } from "./routes/devices.js";
+import { AllowedHosts } from "./utils/allowed-hosts.js";
 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- documented workaround above
 const fastifySse = fastifySseImport;
+// Expired records leave the database within this time (ADR 0079, item 8).
+const DEVICE_SWEEP_MS = 60 * 60 * 1000;
+// Open connections of a device that lost access close within this time,
+// also when another server process on the same database revoked it.
+// One indexed SELECT per connected device.
+const DEVICE_RECHECK_MS = 2000;
 export function buildApp(options = {}) {
     const app = Fastify({
         logger: false,
@@ -51,12 +64,36 @@ export function buildApp(options = {}) {
     const repositoryPath = options.repositoryPath ?? process.cwd();
     const db = options.db ?? createTestDatabase();
     const eventBus = options.eventBus ?? createEventBus();
+    const devices = new DeviceService(db, {
+        ...(options.now ? { now: options.now } : {}),
+        onChange: () => eventBus.publish({ type: 'devices:changed' })
+    });
+    const deviceConnections = new DeviceConnections(devices);
+    devices.removeExpired();
+    const sweep = setInterval(() => devices.removeExpired(), DEVICE_SWEEP_MS);
+    sweep.unref();
+    const recheck = setInterval(() => deviceConnections.recheck(), DEVICE_RECHECK_MS);
+    recheck.unref();
+    app.addHook('onClose', async () => {
+        clearInterval(sweep);
+        clearInterval(recheck);
+    });
     // Windows includes a PTY binary, but the shell and process list are Unix-only.
     const terminalEnabled = options.terminalEnabled === true && terminalSupported();
     if (terminalEnabled) {
         app.register(fastifyWebsocket, TERMINAL_WEBSOCKET_OPTIONS);
     }
     app.register(fastifySse);
+    app.decorateRequest('access', null);
+    app.register(fastifyCookie);
+    // Registered after the cookie and WebSocket plugins: the hook needs parsed
+    // cookies, and a rejected upgrade before the WebSocket hook leaves the socket open.
+    app.register(fastifyPlugin(async (root) => {
+        root.addHook('onRequest', createAccessHook({
+            devices,
+            allowedHosts: new AllowedHosts(options.allowedHosts)
+        }));
+    }));
     // The spec collects routes as they are added, so it comes before them.
     app.register(fastifySwagger, openApiOptions());
     if (options.apiDocs) {
@@ -72,10 +109,7 @@ export function buildApp(options = {}) {
     });
     const projectPath = options.projectPath ?? repositoryPath;
     const notes = new NotesService(projectPath, resolve(projectPath, options.notesDir ?? '.githuman/notes'), options.notesDir === undefined, eventBus, db);
-    app.register(notesRoutes, {
-        service: notes,
-        loopbackBind: options.loopbackBind === true
-    });
+    app.register(notesRoutes, { service: notes });
     app.addHook('onClose', async () => {
         await notes.identity.close();
     });
@@ -90,12 +124,20 @@ export function buildApp(options = {}) {
     app.register(reviewRoutes, { repositoryPath, db, eventBus });
     app.register(commentRoutes, { db, eventBus });
     app.register(exportRoutes, { db, repositoryPath });
+    app.register(deviceRoutes, {
+        devices,
+        ...(options.onPairingRequest
+            ? { onPairingRequest: options.onPairingRequest }
+            : {})
+    });
     app.register(eventRoutes, {
         eventBus,
+        connections: deviceConnections,
         instanceId: options.instanceId ?? randomUUID()
     });
     if (terminalEnabled) {
         app.register(terminalRoutes, {
+            deviceConnections,
             registry: options.terminalRegistry ??
                 new TerminalRegistry({
                     repositoryPath,
@@ -112,7 +154,8 @@ export function buildApp(options = {}) {
             }),
             db,
             repositoryPath,
-            eventBus
+            eventBus,
+            connections: deviceConnections
         });
     }
     if (options.watchFiles) {

package/dist/server/db/migrations.js

@@ -87,6 +87,25 @@ export function applyMigrations(db) {
       ON review_files(file_path);
     CREATE INDEX IF NOT EXISTS review_files_review_id_idx
       ON review_files(review_id);
+
+    -- One row: the random id in the device cookie name (ADR 0079).
+    CREATE TABLE IF NOT EXISTS server_identity (
+      id TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS devices (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      secret_hash TEXT NOT NULL UNIQUE,
+      state TEXT NOT NULL,
+      code TEXT NOT NULL,
+      host TEXT NOT NULL,
+      address TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      last_seen_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS devices_address_idx ON devices(address);
   `);
     const noteColumns = db
         .prepare('PRAGMA table_info(note_catalog)')

package/dist/server/errors/devices.js

@@ -0,0 +1,7 @@
+import createError from '@fastify/error';
+export const DeviceNotFoundError = createError('GHT_DEVICE_NOT_FOUND', '%s', 404);
+/** The pairing request exists but its time is over. */
+export const PairingExpiredError = createError('GHT_PAIRING_EXPIRED', '%s', 410);
+/** The code does not match, or the device is already trusted. */
+export const PairingConflictError = createError('GHT_PAIRING_CONFLICT', '%s', 409);
+export const PairingRateLimitError = createError('GHT_PAIRING_RATE_LIMIT', '%s', 429);

package/dist/server/errors/http.js

@@ -2,3 +2,4 @@ import createError from '@fastify/error';
 export const BadRequestError = createError('GHT_HTTP_BAD_REQUEST', '%s', 400);
 export const NotFoundError = createError('GHT_HTTP_NOT_FOUND', '%s', 404);
 export const ForbiddenError = createError('GHT_HTTP_FORBIDDEN', '%s', 403);
+export const UnauthorizedError = createError('GHT_HTTP_UNAUTHORIZED', '%s', 401);

package/dist/server/hooks/access/local-request.js

@@ -0,0 +1,21 @@
+import { isLoopbackHost } from "../../../shared/network/loopback.js";
+import { forwardedAddresses, isLoopbackAddress, parseHost, sameOrigin } from "../../utils/request-origin.js";
+/**
+ * True when the request comes from a page or a client on this machine
+ * (ADR 0079). The `Host` header alone is not proof: with a bind on
+ * `0.0.0.0` any client sends `Host: localhost`. A proxy on this machine
+ * (the Quasar dev server, Tailscale Serve) connects from loopback, so a
+ * non-loopback `X-Forwarded-For` entry also makes the request remote.
+ * The loopback `Host` stays as the defence against DNS rebinding.
+ */
+export function isLocalRequest(request) {
+    const { host, origin } = request.headers;
+    const forwarded = forwardedAddresses(request.headers['x-forwarded-for']);
+    const target = parseHost(host);
+    return (isLoopbackAddress(request.socket.remoteAddress) &&
+        forwarded !== undefined &&
+        forwarded.every(isLoopbackAddress) &&
+        target !== undefined &&
+        isLoopbackHost(target.hostname) &&
+        (origin === undefined || sameOrigin(origin, host)));
+}

package/dist/server/hooks/access/require-access.js

@@ -0,0 +1,93 @@
+import { DEVICE_IDLE_TTL_MS } from "../../../shared/devices/constants.js";
+import { ForbiddenError, UnauthorizedError } from "../../errors/http.js";
+import { clientAddress, sameOrigin } from "../../utils/request-origin.js";
+import { isLocalRequest } from "./local-request.js";
+// Methods that do not change state; CSRF checks the others.
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+// API routes that a browser without access needs to request pairing.
+const PUBLIC_ROUTES = new Set([
+    'GET /api/access',
+    'HEAD /api/access',
+    'POST /api/devices/requests'
+]);
+export function deviceCookieName(serverId) {
+    return `ght_device_${serverId}`;
+}
+/**
+ * The cookie lives 30 days from the request or the last renewal. The
+ * database decides if the secret still gives access (ADR 0079, item 8).
+ * There is no `Secure` flag: the server speaks plain HTTP.
+ */
+export function setDeviceCookie(reply, serverId, secret) {
+    reply.setCookie(deviceCookieName(serverId), secret, {
+        httpOnly: true,
+        sameSite: 'strict',
+        path: '/',
+        maxAge: DEVICE_IDLE_TTL_MS / 1000
+    });
+}
+export function clearDeviceCookie(reply, serverId) {
+    reply.clearCookie(deviceCookieName(serverId), { path: '/' });
+}
+export function deviceSecret(request, serverId) {
+    return request.cookies[deviceCookieName(serverId)];
+}
+/**
+ * Global `onRequest` hook (ADR 0079, item 9). It runs for every bind, and
+ * decides by the matched route, not by `request.url`: Fastify finds
+ * `/api/reviews` for `/%61pi/reviews`. Static files, `/health` and the SPA
+ * fallback carry no data and pass.
+ */
+export function createAccessHook(options) {
+    const { devices, allowedHosts } = options;
+    return async function requireAccess(request, reply) {
+        const route = request.routeOptions.url;
+        const api = request.url.startsWith('/api/') || route?.startsWith('/api/') === true;
+        if (!api)
+            return;
+        reply.header('cache-control', 'no-store');
+        const { host, origin } = request.headers;
+        const local = isLocalRequest(request);
+        if (!local && !allowedHosts.allows(host)) {
+            throw new ForbiddenError(`Unknown Host "${host ?? '-'}". Open the app by the IP address of this machine, or start the server with --allowed-host.`);
+        }
+        if (origin !== undefined &&
+            !SAFE_METHODS.has(request.method) &&
+            !sameOrigin(origin, host)) {
+            throw new ForbiddenError('The request Origin does not match the server.');
+        }
+        if (local) {
+            request.access = { local: true, device: { status: 'none' } };
+            return;
+        }
+        const device = devices.access(deviceSecret(request, devices.serverId), clientAddress(request.socket.remoteAddress, request.headers['x-forwarded-for']));
+        request.access = { local: false, device };
+        if (device.status === 'device' && device.renewed) {
+            setDeviceCookie(reply, devices.serverId, deviceSecret(request, devices.serverId) ?? '');
+        }
+        if (route !== undefined &&
+            PUBLIC_ROUTES.has(`${request.method} ${route}`)) {
+            return;
+        }
+        if (device.status !== 'device') {
+            throw new UnauthorizedError('This device has no access. Open the app to request access.');
+        }
+    };
+}
+/**
+ * True for a request of a trusted device that the access hook let through.
+ * A browser sends no `Origin` on a same-origin GET or EventSource, so the
+ * check needs `Origin` only when `originRequired` is set.
+ */
+export function isTrustedDeviceRequest(request, originRequired) {
+    if (request.access?.device.status !== 'device')
+        return false;
+    const { host, origin } = request.headers;
+    return origin === undefined ? !originRequired : sameOrigin(origin, host);
+}
+/** Route hook for device management: only this machine may approve or revoke. */
+export async function requireLocalRequest(request) {
+    if (!isLocalRequest(request)) {
+        throw new ForbiddenError('Only this machine manages devices. Open the app via localhost.');
+    }
+}

package/dist/server/hooks/agents/local-origin.js

@@ -1,33 +1,16 @@
 import { ForbiddenError } from "../../errors/http.js";
-import { isLoopbackHost } from "../../../shared/network/loopback.js";
-function hostnameOf(hostWithPort) {
-    // "[::1]:3847" → "[::1]"; "localhost:3847" → "localhost"
-    return hostWithPort.startsWith('[')
-        ? hostWithPort.slice(0, hostWithPort.indexOf(']') + 1)
-        : (hostWithPort.split(':')[0] ?? '');
-}
+import { isLocalRequest } from "../access/local-request.js";
+import { isTrustedDeviceRequest } from "../access/require-access.js";
 /**
- * `onRequest` hook for the agent routes (ADR 0023). They are an RCE surface,
- * so besides only being registered on a loopback bind, each request must
- * prove it came from a page served by this very server: a loopback `Host`
- * (defeats DNS rebinding, where a hostile domain resolves to 127.0.0.1) and,
- * when the browser sends an `Origin`, one identical to that `Host`.
- * Non-browser clients (curl, tests) send no `Origin` and pass.
+ * `onRequest` hook for the agent routes (ADR 0023, ADR 0079). They are an
+ * RCE surface, so each request must come from this machine (see
+ * `isLocalRequest`) or from a trusted device. Non-browser clients (curl,
+ * tests) send no `Origin` and pass.
  */
 export async function requireLocalOrigin(request) {
-    const host = request.headers.host ?? '';
-    const origin = request.headers.origin;
-    let ok = isLoopbackHost(hostnameOf(host));
-    if (ok && origin !== undefined) {
-        try {
-            ok = new URL(origin).host === host;
-        }
-        catch {
-            ok = false;
-        }
-    }
-    if (ok) {
+    if (isLocalRequest(request) || isTrustedDeviceRequest(request, false)) {
         return;
     }
-    throw new ForbiddenError(`Agent endpoints only accept requests from this local server (Host: ${host || '-'}, Origin: ${origin ?? '-'}). Open the app via localhost.`);
+    const { host, origin } = request.headers;
+    throw new ForbiddenError(`Agent endpoints only accept requests from this machine or a trusted device (Host: ${host || '-'}, Origin: ${origin ?? '-'}).`);
 }

package/dist/server/hooks/notes/same-origin.js

@@ -1,37 +1,10 @@
-import { isLoopbackHost } from "../../../shared/network/loopback.js";
 import { ForbiddenError } from "../../errors/http.js";
-// Returns false on any malformed value: an invalid URL means an invalid origin.
-function isSameOrigin(host, origin) {
-    if (!host)
-        return false;
-    try {
-        return new URL(origin).host === new URL(`http://${host}`).host;
+import { sameOrigin } from "../../utils/request-origin.js";
+// The global access hook decides who may read and write notes (ADR 0079).
+// Notes also reject a foreign Origin on reads, unlike other routes.
+export async function requireNotesOrigin(request) {
+    const { host, origin } = request.headers;
+    if (origin && !sameOrigin(origin, host)) {
+        throw new ForbiddenError('Notes require the same origin as this server');
     }
-    catch {
-        return false;
-    }
-}
-function isLoopbackRequestHost(host) {
-    if (!host)
-        return false;
-    try {
-        return isLoopbackHost(new URL(`http://${host}`).hostname);
-    }
-    catch {
-        return false;
-    }
-}
-// A loopback bind also needs a loopback Host. A rebound hostile domain sends
-// matching Origin and Host, so the match alone does not stop DNS rebinding.
-// ADR 0008 allows LAN access without a password, so other binds skip this check.
-export function createNotesOriginHook(options) {
-    return async function requireNotesOrigin(request) {
-        const { host, origin } = request.headers;
-        if (options.loopbackBind && !isLoopbackRequestHost(host)) {
-            throw new ForbiddenError('Notes only accept requests from this local server. Open the app via localhost.');
-        }
-        if (origin && !isSameOrigin(host, origin)) {
-            throw new ForbiddenError('Notes require the same origin as this server');
-        }
-    };
 }

package/dist/server/hooks/terminal/local-origin.js

@@ -1,26 +1,12 @@
-import { isLoopbackHost } from "../../../shared/network/loopback.js";
 import { ForbiddenError } from "../../errors/http.js";
-// Returns false on any malformed value: an invalid URL means an invalid origin.
-function isTerminalOrigin(host, origin) {
-    if (!host || !origin)
-        return false;
-    try {
-        const source = new URL(origin);
-        const target = new URL(`http://${host}`);
-        return (isLoopbackHost(target.hostname) &&
-            target.host === host &&
-            source.host === target.host &&
-            source.protocol === 'http:' &&
-            source.origin === origin &&
-            !target.username &&
-            !target.password);
-    }
-    catch {
-        return false;
-    }
-}
+import { isLocalRequest } from "../access/local-request.js";
+import { isTrustedDeviceRequest } from "../access/require-access.js";
+// A browser always sends `Origin` on a WebSocket upgrade and a POST.
+// Without it the token could not be bound to a page (ADR 0037).
 export async function requireTerminalOrigin(request) {
-    if (!isTerminalOrigin(request.headers.host, request.headers.origin)) {
-        throw new ForbiddenError('Terminal endpoints only accept requests from this local server. Open the app via localhost.');
+    const allowed = request.headers.origin !== undefined &&
+        (isLocalRequest(request) || isTrustedDeviceRequest(request, true));
+    if (!allowed) {
+        throw new ForbiddenError('Terminal endpoints only accept requests from this machine or a trusted device.');
     }
 }