@tequila99/githuman 0.9.0 → 0.10.0

package/dist/server/repositories/device.repo.js

@@ -0,0 +1,74 @@
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        secretHash: row.secret_hash,
+        state: row.state,
+        code: row.code,
+        host: row.host,
+        address: row.address,
+        createdAt: row.created_at,
+        expiresAt: row.expires_at,
+        lastSeenAt: row.last_seen_at
+    };
+}
+/** Reads the server id, or stores the one from `create` on first use. */
+export function ensureServerId(db, create) {
+    const row = db.prepare('SELECT id FROM server_identity LIMIT 1').get();
+    if (row)
+        return row.id;
+    const id = create();
+    db.prepare('INSERT INTO server_identity (id) VALUES (?)').run(id);
+    return id;
+}
+export function insertDevice(db, device) {
+    db.prepare(`INSERT INTO devices (id, name, secret_hash, state, code, host, address, created_at, expires_at, last_seen_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(device.id, device.name, device.secretHash, device.state, device.code, device.host, device.address, device.createdAt, device.expiresAt, device.lastSeenAt);
+}
+export function findDeviceById(db, id) {
+    const row = db.prepare('SELECT * FROM devices WHERE id = ?').get(id);
+    return row ? rowToRecord(row) : undefined;
+}
+export function findDeviceBySecretHash(db, secretHash) {
+    const row = db
+        .prepare('SELECT * FROM devices WHERE secret_hash = ?')
+        .get(secretHash);
+    return row ? rowToRecord(row) : undefined;
+}
+export function listDevices(db) {
+    const rows = db
+        .prepare('SELECT * FROM devices ORDER BY created_at')
+        .all();
+    return rows.map(rowToRecord);
+}
+export function countPendingDevices(db) {
+    const row = db
+        .prepare("SELECT COUNT(*) AS count FROM devices WHERE state = 'pending'")
+        .get();
+    return row.count;
+}
+/** Ids of records whose time is over. ISO times in UTC compare as text. */
+export function expiredDeviceIds(db, nowIso, state) {
+    const sql = state === undefined
+        ? 'SELECT id FROM devices WHERE expires_at <= ?'
+        : 'SELECT id FROM devices WHERE expires_at <= ? AND state = ?';
+    const params = state === undefined ? [nowIso] : [nowIso, state];
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(row => row.id);
+}
+export function updateDevice(db, id, fields) {
+    const columns = {
+        name: fields.name,
+        state: fields.state,
+        address: fields.address,
+        expires_at: fields.expiresAt,
+        last_seen_at: fields.lastSeenAt
+    };
+    const entries = Object.entries(columns).filter((entry) => entry[1] !== undefined);
+    if (entries.length === 0)
+        return;
+    db.prepare(`UPDATE devices SET ${entries.map(([column]) => `${column} = ?`).join(', ')} WHERE id = ?`).run(...entries.map(([, value]) => value), id);
+}
+export function deleteDevice(db, id) {
+    return db.prepare('DELETE FROM devices WHERE id = ?').run(id).changes > 0;
+}

package/dist/server/routes/agent.js

@@ -21,7 +21,7 @@ const AGENT_ERROR_RESPONSES = {
     }
 };
 export async function agentRoutes(app, opts) {
-    const { registry, db, repositoryPath, eventBus } = opts;
+    const { registry, db, repositoryPath, eventBus, connections } = opts;
     const typedApp = app.withTypeProvider();
     const fileIndex = createFileIndex(repositoryPath, eventBus);
     app.addHook('onRequest', requireLocalOrigin);
@@ -237,6 +237,11 @@ export async function agentRoutes(app, opts) {
         if (!reply.sse.isConnected) {
             return;
         }
+        // No `await` between this check of the device and the subscription.
+        const release = connections.track(request, () => reply.sse.close());
+        if (!release) {
+            return;
+        }
         const unsubscribe = registry.subscribe(message => {
             if (message.type === 'event') {
                 safeSend(reply.sse, {
@@ -262,8 +267,12 @@ export async function agentRoutes(app, opts) {
         // have run then, so the listener is removed here.
         if (!reply.sse.isConnected) {
             unsubscribe();
+            release();
             return;
         }
-        reply.sse.onClose(unsubscribe);
+        reply.sse.onClose(() => {
+            unsubscribe();
+            release();
+        });
     });
 }

package/dist/server/routes/devices.js

@@ -0,0 +1,130 @@
+import { BadRequestError } from "../errors/http.js";
+import { clearDeviceCookie, deviceSecret, requireLocalRequest, setDeviceCookie } from "../hooks/access/require-access.js";
+import { machineAddresses } from "../utils/lan-addresses.js";
+import { clientAddress } from "../utils/request-origin.js";
+import { AccessSchema, ApproveDeviceBody, CreatePairingRequestBody, DeviceListSchema, DeviceParams, DeviceSchema, LanAddressesSchema, RenameDeviceBody } from "../../shared/devices/schemas.js";
+import { ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['devices'];
+// The secret hash and the pairing code never reach the operator's browser:
+// the code is shown on the device only (ADR 0080).
+function toDevice({ secretHash: _secretHash, code: _code, ...device }) {
+    return device;
+}
+function pendingAccess(device, now) {
+    return {
+        status: 'pending',
+        pairing: {
+            code: device.code,
+            expiresAt: device.expiresAt,
+            remainingMs: Math.max(0, Date.parse(device.expiresAt) - now)
+        }
+    };
+}
+export async function deviceRoutes(app, opts) {
+    const { devices, onPairingRequest } = opts;
+    const typedApp = app.withTypeProvider();
+    typedApp.get('/api/access', {
+        schema: {
+            tags: TAGS,
+            summary: 'Access of this browser',
+            response: { 200: AccessSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        const access = request.access;
+        if (access?.local)
+            return { status: 'local' };
+        const device = access?.device ?? { status: 'none' };
+        if (device.status === 'device')
+            return { status: 'device' };
+        if (device.status === 'pending') {
+            return pendingAccess(device.device, devices.now());
+        }
+        // A stale secret blocks nothing, but a new request should start clean.
+        if (deviceSecret(request, devices.serverId) !== undefined) {
+            clearDeviceCookie(reply, devices.serverId);
+        }
+        return { status: 'none' };
+    });
+    typedApp.post('/api/devices/requests', {
+        schema: {
+            tags: TAGS,
+            summary: 'Request access for this browser',
+            body: CreatePairingRequestBody,
+            response: { 200: AccessSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
+        if (request.access?.local) {
+            throw new BadRequestError('This machine needs no pairing.');
+        }
+        const { device, secret } = devices.createRequest({
+            secret: deviceSecret(request, devices.serverId),
+            ...(request.body.name === undefined ? {} : { name: request.body.name }),
+            ...(request.headers['user-agent'] === undefined
+                ? {}
+                : { userAgent: request.headers['user-agent'] }),
+            address: clientAddress(request.socket.remoteAddress, request.headers['x-forwarded-for']),
+            host: request.headers.host ?? ''
+        });
+        if (secret === undefined)
+            return { status: 'device' };
+        setDeviceCookie(reply, devices.serverId, secret);
+        onPairingRequest?.(toDevice(device));
+        return pendingAccess(device, devices.now());
+    });
+    // Device management: only this machine may see, approve or revoke devices.
+    app.register(async (local) => {
+        local.addHook('onRequest', requireLocalRequest);
+        const typedLocal = local.withTypeProvider();
+        typedLocal.get('/api/devices', {
+            schema: {
+                tags: TAGS,
+                summary: 'List pending and trusted devices',
+                response: { 200: DeviceListSchema, ...ERROR_RESPONSES }
+            }
+        }, async () => devices.list().map(toDevice));
+        typedLocal.post('/api/devices/:id/approve', {
+            schema: {
+                tags: TAGS,
+                summary: 'Approve a pairing request',
+                params: DeviceParams,
+                body: ApproveDeviceBody,
+                response: {
+                    200: { ...DeviceSchema, description: 'The trusted device.' },
+                    ...ERROR_RESPONSES
+                }
+            }
+        }, async (request) => toDevice(devices.approve(request.params.id, request.body.code)));
+        typedLocal.patch('/api/devices/:id', {
+            schema: {
+                tags: TAGS,
+                summary: 'Rename a device',
+                params: DeviceParams,
+                body: RenameDeviceBody,
+                response: {
+                    200: { ...DeviceSchema, description: 'The renamed device.' },
+                    ...ERROR_RESPONSES
+                }
+            }
+        }, async (request) => toDevice(devices.rename(request.params.id, request.body.name)));
+        typedLocal.delete('/api/devices/:id', {
+            schema: {
+                tags: TAGS,
+                summary: 'Reject a pairing request or revoke a device',
+                params: DeviceParams,
+                response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+            }
+        }, async (request, reply) => {
+            devices.revoke(request.params.id);
+            reply.code(204);
+            return null;
+        });
+        typedLocal.get('/api/devices/lan-addresses', {
+            schema: {
+                tags: TAGS,
+                summary: 'LAN addresses of this machine for a QR code',
+                response: { 200: LanAddressesSchema, ...ERROR_RESPONSES }
+            }
+        }, async () => machineAddresses());
+    });
+}

package/dist/server/routes/events.js

@@ -1,7 +1,7 @@
 import { safeSend } from "../utils/sse.js";
 import { EventStreamSchema } from "../../shared/events/schemas.js";
 export async function eventRoutes(app, opts) {
-    const { eventBus, instanceId } = opts;
+    const { eventBus, instanceId, connections } = opts;
     const hello = { instanceId };
     app.get('/api/events', {
         sse: true,
@@ -22,6 +22,11 @@ export async function eventRoutes(app, opts) {
         if (!reply.sse.isConnected) {
             return;
         }
+        // No `await` between this check of the device and the subscription.
+        const release = connections.track(request, () => reply.sse.close());
+        if (!release) {
+            return;
+        }
         const unsubscribe = eventBus.subscribe(event => {
             safeSend(reply.sse, {
                 event: event.type,
@@ -30,6 +35,7 @@ export async function eventRoutes(app, opts) {
         });
         reply.sse.onClose(() => {
             unsubscribe();
+            release();
         });
     });
 }

package/dist/server/routes/notes.js

@@ -7,14 +7,14 @@ import { NoteRecordSchema, NoteIdQuery, NoteDescriptorSchema, NoteResolveBody, N
 import { ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
 import { BadRequestError } from "../errors/http.js";
 import { withRequestSignal } from "../utils/request-abort.js";
-import { createNotesOriginHook } from "../hooks/notes/same-origin.js";
-export async function notesRoutes(app, { service, loopbackBind = false, externalAssets = new NotesExternalAssetsService() }) {
+import { requireNotesOrigin } from "../hooks/notes/same-origin.js";
+export async function notesRoutes(app, { service, externalAssets = new NotesExternalAssetsService() }) {
     await app.register(multipart, {
         attachFieldsToBody: true,
         limits: { fileSize: MAX_NOTE_ASSET_BYTES, files: 1, fields: 0, parts: 1 }
     });
     const typed = app.withTypeProvider();
-    app.addHook('onRequest', createNotesOriginHook({ loopbackBind }));
+    app.addHook('onRequest', requireNotesOrigin);
     app.post('/api/notes/assets', {
         preValidation: async (request) => {
             if (!request.isMultipart()) {

package/dist/server/routes/terminal.js

@@ -49,9 +49,17 @@ export async function terminalRoutes(app, options) {
                 throw new ForbiddenError('Terminal connection token is invalid or expired.');
             }
         }
-    }, socket => {
+    }, (socket, request) => {
+        // No `await` between this check of the device and the attach.
+        const release = options.deviceConnections.track(request, () => socket.terminate());
+        if (!release) {
+            return;
+        }
         const connection = attachTerminalSocket(socket, options.registry, {
-            onDisconnect: () => connections.delete(connection)
+            onDisconnect: () => {
+                connections.delete(connection);
+                release();
+            }
         });
         connections.add(connection);
     });

package/dist/server/services/device-connections.js

@@ -0,0 +1,79 @@
+/**
+ * Open streams and sockets of trusted devices (ADR 0079, item 13). A revoke
+ * in this process closes the connections in the same synchronous step.
+ * A revoke by another process and an expiry close them at the next
+ * `recheck`.
+ *
+ * Between the access hook and the registration of a stream there are
+ * `await` steps, and the device can lose access in them. So `track` checks
+ * the device again and adds the connection without an `await` between the
+ * two: `node:sqlite` is synchronous, and JS runs one step at a time.
+ */
+export class DeviceConnections {
+    byDevice = new Map();
+    devices;
+    constructor(devices) {
+        this.devices = devices;
+        devices.onRemoved(id => this.closeDevice(id));
+    }
+    /**
+     * Registers `close` for the device of this request. Returns the release
+     * function for a normal close. Returns undefined when the device has no
+     * access any more: then `close` was already called. A local request has
+     * no device, so its release function does nothing.
+     */
+    track(request, close) {
+        const access = request.access;
+        if (!access || access.local)
+            return () => { };
+        const id = access.device.status === 'device' ? access.device.device.id : undefined;
+        if (id === undefined || !this.devices.isTrusted(id)) {
+            close();
+            return undefined;
+        }
+        let closers = this.byDevice.get(id);
+        if (!closers) {
+            closers = new Set();
+            this.byDevice.set(id, closers);
+        }
+        closers.add(close);
+        return () => {
+            closers.delete(close);
+            if (closers.size === 0 && this.byDevice.get(id) === closers) {
+                this.byDevice.delete(id);
+            }
+        };
+    }
+    /**
+     * Closes the connections of devices that lost access without a call of
+     * the local service: another server process on the same database revoked
+     * them, or their time is over. The listener of the local service cannot
+     * see such a change.
+     */
+    recheck() {
+        // Deleting the current key during Map iteration is safe.
+        for (const id of this.byDevice.keys()) {
+            if (!this.devices.isTrusted(id))
+                this.closeDevice(id);
+        }
+    }
+    /** Closes every connection of the device. A repeated call does nothing. */
+    closeDevice(id) {
+        const closers = this.byDevice.get(id);
+        if (!closers)
+            return;
+        this.byDevice.delete(id);
+        for (const close of closers) {
+            try {
+                close();
+            }
+            catch {
+                // One broken connection must not keep the others open.
+            }
+        }
+    }
+    /** Number of open connections of the device; for tests. */
+    count(id) {
+        return this.byDevice.get(id)?.size ?? 0;
+    }
+}

package/dist/server/services/device.service.js

@@ -0,0 +1,222 @@
+import { randomBytes, randomInt, randomUUID } from 'node:crypto';
+import { DEVICE_IDLE_TTL_MS, DEVICE_TOUCH_INTERVAL_MS, MAX_PAIRING_REQUESTS_PER_MINUTE, MAX_PENDING_REQUESTS, PAIRING_CODE_LENGTH, PAIRING_REQUEST_INTERVAL_MS, PAIRING_REQUEST_TTL_MS } from "../../shared/devices/constants.js";
+import { cleanDeviceName } from "../../shared/devices/name.js";
+import { toIsoString } from "../../shared/utils/date.js";
+import { DeviceNotFoundError, PairingConflictError, PairingExpiredError, PairingRateLimitError } from "../errors/devices.js";
+import { BadRequestError } from "../errors/http.js";
+import { countPendingDevices, deleteDevice, ensureServerId, expiredDeviceIds, findDeviceById, findDeviceBySecretHash, insertDevice, listDevices, updateDevice } from "../repositories/device.repo.js";
+import { deviceNameFromUserAgent } from "../utils/device-name.js";
+import { addressKey } from "../utils/address-key.js";
+import { sha256Hex } from "../utils/hash.js";
+// Random bytes in a device secret: 256 bits, 43 base64url characters.
+const SECRET_BYTES = 32;
+// A cookie value of another length is not a secret of this server.
+const SECRET_LENGTH = 43;
+// Window of the global request limit.
+const RATE_WINDOW_MS = 60 * 1000;
+/**
+ * Pairing requests and trusted devices (ADR 0079). The secret lives only in
+ * the browser cookie; the database keeps its SHA-256. A random 256-bit
+ * secret cannot be found from response times, so a lookup by the hash
+ * index is safe without a constant-time compare.
+ */
+export class DeviceService {
+    /** Random id in the cookie name: instances for other repositories keep their own cookie. */
+    serverId;
+    /** Clock of the service; routes use it for the time left of a request. */
+    now;
+    onChange;
+    lastRequestAt = new Map();
+    recentRequests = [];
+    removeListeners = new Set();
+    db;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.now = options.now ?? Date.now;
+        this.onChange = options.onChange ?? (() => { });
+        this.serverId = ensureServerId(db, () => randomBytes(6).toString('base64url'));
+    }
+    /** Calls `listener` with the id of each removed device. Returns the unsubscribe function. */
+    onRemoved(listener) {
+        this.removeListeners.add(listener);
+        return () => this.removeListeners.delete(listener);
+    }
+    /**
+     * Creates a pairing request. A browser that is already trusted gets its
+     * device back and no new request. A new request from the same address
+     * or with the same cookie replaces the old one.
+     */
+    createRequest(input) {
+        const current = this.access(input.secret, input.address);
+        if (current.status === 'device') {
+            return { device: current.device };
+        }
+        this.removeExpiredPending();
+        this.checkRate(addressKey(input.address));
+        if (current.status === 'pending') {
+            this.remove(current.device.id);
+        }
+        const key = addressKey(input.address);
+        for (const device of listDevices(this.db)) {
+            if (device.state === 'pending' && addressKey(device.address) === key) {
+                this.remove(device.id);
+            }
+        }
+        // A full list drops the oldest request: otherwise a few addresses could
+        // keep every slot and lock the real device out.
+        while (countPendingDevices(this.db) >= MAX_PENDING_REQUESTS) {
+            const oldest = listDevices(this.db).find(device => device.state === 'pending');
+            if (!oldest)
+                break;
+            this.remove(oldest.id);
+        }
+        const now = this.now();
+        this.lastRequestAt.set(key, now);
+        this.recentRequests.push(now);
+        const secret = randomBytes(SECRET_BYTES).toString('base64url');
+        const device = {
+            id: randomUUID(),
+            name: cleanDeviceName(input.name) || deviceNameFromUserAgent(input.userAgent),
+            secretHash: sha256Hex(secret),
+            state: 'pending',
+            code: randomInt(0, 10 ** PAIRING_CODE_LENGTH)
+                .toString()
+                .padStart(PAIRING_CODE_LENGTH, '0'),
+            host: input.host,
+            address: input.address,
+            createdAt: toIsoString(now),
+            expiresAt: toIsoString(now + PAIRING_REQUEST_TTL_MS),
+            lastSeenAt: toIsoString(now)
+        };
+        insertDevice(this.db, device);
+        this.onChange();
+        return { device, secret };
+    }
+    /**
+     * Access of the browser with this cookie secret. An expired record never
+     * gives access. A trusted device records activity at most once per
+     * `DEVICE_TOUCH_INTERVAL_MS`.
+     */
+    access(secret, address) {
+        if (secret?.length !== SECRET_LENGTH)
+            return { status: 'none' };
+        const device = findDeviceBySecretHash(this.db, sha256Hex(secret));
+        const now = this.now();
+        if (!device || Date.parse(device.expiresAt) <= now) {
+            return { status: 'none' };
+        }
+        if (device.state === 'pending') {
+            return { status: 'pending', device };
+        }
+        if (now - Date.parse(device.lastSeenAt) < DEVICE_TOUCH_INTERVAL_MS) {
+            return { status: 'device', device, renewed: false };
+        }
+        const fields = {
+            lastSeenAt: toIsoString(now),
+            expiresAt: toIsoString(now + DEVICE_IDLE_TTL_MS),
+            ...(address === undefined ? {} : { address })
+        };
+        updateDevice(this.db, device.id, fields);
+        return { status: 'device', device: { ...device, ...fields }, renewed: true };
+    }
+    /** True when the device exists, is trusted and its time is not over. */
+    isTrusted(id) {
+        const device = findDeviceById(this.db, id);
+        return (device?.state === 'trusted' && Date.parse(device.expiresAt) > this.now());
+    }
+    /**
+     * Makes a pending request trusted. The code proves that the operator saw
+     * this request: a replaced request has another id, and a matching id with
+     * another code is a conflict.
+     */
+    approve(id, code) {
+        const device = findDeviceById(this.db, id);
+        if (!device) {
+            throw new DeviceNotFoundError('The pairing request does not exist. It was replaced, rejected or removed.');
+        }
+        if (device.state === 'trusted') {
+            throw new PairingConflictError('The device is already trusted.');
+        }
+        const now = this.now();
+        if (Date.parse(device.expiresAt) <= now) {
+            throw new PairingExpiredError('The pairing request has expired.');
+        }
+        if (device.code !== code) {
+            throw new PairingConflictError('The code does not match the pairing request.');
+        }
+        const fields = {
+            state: 'trusted',
+            lastSeenAt: toIsoString(now),
+            expiresAt: toIsoString(now + DEVICE_IDLE_TTL_MS)
+        };
+        updateDevice(this.db, id, fields);
+        this.onChange();
+        return { ...device, ...fields };
+    }
+    rename(id, name) {
+        const device = findDeviceById(this.db, id);
+        if (!device) {
+            throw new DeviceNotFoundError('The device does not exist.');
+        }
+        const trimmed = cleanDeviceName(name);
+        if (!trimmed) {
+            throw new BadRequestError('The device name is empty.');
+        }
+        updateDevice(this.db, id, { name: trimmed });
+        this.onChange();
+        return { ...device, name: trimmed };
+    }
+    /** Rejects a request or revokes a device. */
+    revoke(id) {
+        if (!this.remove(id)) {
+            throw new DeviceNotFoundError('The device does not exist.');
+        }
+    }
+    /** Devices with time left. Expired pending requests are removed first. */
+    list() {
+        this.removeExpiredPending();
+        const now = this.now();
+        return listDevices(this.db).filter(device => Date.parse(device.expiresAt) > now);
+    }
+    /** Removes every expired record through the revoke path. Returns their ids. */
+    removeExpired() {
+        const ids = expiredDeviceIds(this.db, toIsoString(this.now()));
+        for (const id of ids)
+            this.remove(id);
+        return ids;
+    }
+    removeExpiredPending() {
+        for (const id of expiredDeviceIds(this.db, toIsoString(this.now()), 'pending')) {
+            this.remove(id);
+        }
+    }
+    /**
+     * Deletes the record and tells listeners synchronously, so that open
+     * connections close in the same step (ADR 0079, item 13). A repeated call
+     * returns false and changes nothing.
+     */
+    remove(id) {
+        if (!deleteDevice(this.db, id))
+            return false;
+        for (const listener of this.removeListeners)
+            listener(id);
+        this.onChange();
+        return true;
+    }
+    checkRate(key) {
+        const now = this.now();
+        const last = this.lastRequestAt.get(key);
+        if (last !== undefined && now - last < PAIRING_REQUEST_INTERVAL_MS) {
+            throw new PairingRateLimitError('Pairing requests from this address are too frequent. Wait a few seconds.');
+        }
+        this.recentRequests = this.recentRequests.filter(time => now - time < RATE_WINDOW_MS);
+        if (this.recentRequests.length >= MAX_PAIRING_REQUESTS_PER_MINUTE) {
+            throw new PairingRateLimitError('Too many pairing requests. Try again in a minute.');
+        }
+        for (const [storedKey, time] of this.lastRequestAt) {
+            if (now - time >= PAIRING_REQUEST_INTERVAL_MS) {
+                this.lastRequestAt.delete(storedKey);
+            }
+        }
+    }
+}

package/dist/server/utils/address-key.js

@@ -0,0 +1,33 @@
+import { isIPv4, isIPv6 } from 'node:net';
+// An IPv6 client owns a whole /64 and can take any address inside it.
+const IPV6_PREFIX_GROUPS = 4;
+const IPV4_MAPPED_PREFIX = '::ffff:';
+/** Expands an IPv6 address into 8 groups. The address must be valid. */
+function ipv6Groups(address) {
+    const [head = '', tail] = address.split('::');
+    const headGroups = head === '' ? [] : head.split(':');
+    if (tail === undefined)
+        return headGroups;
+    const tailGroups = tail === '' ? [] : tail.split(':');
+    const gap = 8 - headGroups.length - tailGroups.length;
+    return [...headGroups, ...Array(gap).fill('0'), ...tailGroups];
+}
+/**
+ * Key that limits pairing requests of one client. An IPv6 address maps to
+ * its /64 prefix, an IPv4-mapped address to the IPv4 address. Any other
+ * text stays as it is.
+ */
+export function addressKey(address) {
+    const plain = address.split('%')[0] ?? address;
+    if (plain.toLowerCase().startsWith(IPV4_MAPPED_PREFIX)) {
+        const mapped = plain.slice(IPV4_MAPPED_PREFIX.length);
+        if (isIPv4(mapped))
+            return mapped;
+    }
+    if (!isIPv6(plain))
+        return address;
+    const groups = ipv6Groups(plain.toLowerCase())
+        .slice(0, IPV6_PREFIX_GROUPS)
+        .map(group => parseInt(group, 16).toString(16));
+    return `${groups.join(':')}::/64`;
+}

package/dist/server/utils/allowed-hosts.js

@@ -0,0 +1,38 @@
+import { machineAddresses } from "./lan-addresses.js";
+import { parseHost } from "./request-origin.js";
+// DHCP can change an address; a short cache keeps the lookup cheap per request.
+const ADDRESS_CACHE_MS = 5000;
+/**
+ * `Host` values that a LAN request may use (ADR 0079): addresses of this
+ * machine and the exact names from `--allowed-host`. A page of a rebound
+ * hostile domain sends its own name, so it cannot reach the API or start
+ * a pairing request.
+ */
+export class AllowedHosts {
+    names;
+    addresses;
+    now;
+    cached;
+    constructor(names = [], addresses = machineAddresses, now = Date.now) {
+        this.names = new Set(names.map(name => name.toLowerCase()));
+        this.addresses = addresses;
+        this.now = now;
+    }
+    allows(host) {
+        const hostname = parseHost(host)?.hostname;
+        if (hostname === undefined)
+            return false;
+        const bare = hostname.startsWith('[') ? hostname.slice(1, -1) : hostname;
+        return this.names.has(bare) || this.machineHosts().has(bare);
+    }
+    machineHosts() {
+        const now = this.now();
+        if (!this.cached || now - this.cached.at >= ADDRESS_CACHE_MS) {
+            this.cached = {
+                at: now,
+                hosts: new Set(this.addresses().map(address => address.toLowerCase()))
+            };
+        }
+        return this.cached.hosts;
+    }
+}