termdock 1.4.174 → 1.4.176

package/dist/server/federation/cli.js

@@ -0,0 +1,185 @@
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import WebSocket from 'ws';
+import QRCode from 'qrcode';
+import { RelayClient } from './relay.js';
+function secureEndpoint(value, endpoint) {
+    const url = new URL(value);
+    if (!['https:', 'wss:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+        throw new Error('Federation relay URLs must use HTTPS/WSS without credentials, query or fragment');
+    if (url.pathname !== '/' && url.pathname !== endpoint)
+        throw new Error('Federation relay URL must be a service origin or the exact tunnel endpoint');
+    url.protocol = 'wss:';
+    url.pathname = endpoint;
+    return url.toString();
+}
+export function parseRelayConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid relay config');
+    const v = value;
+    if (Object.keys(v).some(k => !['entryUrl', 'relayToken', 'caPath', 'targets'].includes(k)) || typeof v.entryUrl !== 'string' || typeof v.relayToken !== 'string' || v.relayToken.length < 32 || /[\r\n]/.test(v.relayToken) || !Array.isArray(v.targets) || !v.targets.length || v.targets.length > 64 || (v.caPath !== undefined && typeof v.caPath !== 'string'))
+        throw new Error('Invalid relay config fields');
+    secureEndpoint(v.entryUrl, '/api/federation/relay');
+    const seen = new Set();
+    for (const target of v.targets) {
+        if (!target || typeof target !== 'object' || Array.isArray(target) || Object.keys(target).some(k => !['serviceId', 'url', 'caPath'].includes(k)) || typeof target.serviceId !== 'string' || !/^[a-zA-Z0-9_.:-]{1,160}$/.test(target.serviceId) || typeof target.url !== 'string' || (target.caPath !== undefined && typeof target.caPath !== 'string') || seen.has(target.serviceId))
+            throw new Error('Invalid or duplicate relay target');
+        secureEndpoint(target.url, '/api/federation/secure');
+        seen.add(target.serviceId);
+    }
+    return structuredClone(v);
+}
+function connect(url, ca, sockets, token, readyHandshake = false) {
+    return new Promise((accept, reject) => {
+        const ws = new WebSocket(url, { ca, rejectUnauthorized: true, followRedirects: false, handshakeTimeout: 10_000, maxPayload: 256 * 1024, ...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}) });
+        sockets.add(ws);
+        ws.once('close', () => sockets.delete(ws));
+        const failed = () => { ws.terminate(); reject(new Error('Secure relay connection failed')); };
+        ws.once('error', failed);
+        ws.once('close', failed);
+        ws.once('open', () => {
+            ws.off('error', failed);
+            ws.off('close', failed);
+            ws.on('error', () => ws.terminate());
+            if (readyHandshake)
+                void awaitReady(ws).then(() => accept(ws), reject);
+            else
+                accept(ws);
+        });
+    });
+}
+async function awaitReady(ws) {
+    return new Promise((accept, reject) => {
+        const timer = setTimeout(() => fail(), 10_000);
+        const cleanup = () => { clearTimeout(timer); ws.off('message', ready); ws.off('close', fail); };
+        const fail = () => { cleanup(); ws.terminate(); reject(new Error('Relay authentication failed')); };
+        const ready = (raw) => {
+            try {
+                const frame = JSON.parse(raw.toString());
+                if (frame.type !== 'ready') {
+                    fail();
+                    return;
+                }
+                cleanup();
+                accept();
+            }
+            catch {
+                fail();
+            }
+        };
+        ws.once('message', ready);
+        ws.once('close', fail);
+    });
+}
+export function pairingInviteUrl(serviceId, code, value) {
+    const url = new URL(value);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/')
+        throw new Error('配对地址必须是服务的 HTTP(S) 根地址，不含账号、参数或片段。');
+    if (url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+        throw new Error('远程配对地址必须使用 HTTPS。');
+    if (!/^[A-Za-z0-9_-]{43}$/.test(code) || !/^[A-Za-z0-9_.:-]{1,160}$/.test(serviceId))
+        throw new Error('Invalid pairing information');
+    const origin = url.origin;
+    url.hash = 'termdock-invite=' + Buffer.from(JSON.stringify({ v: 1, serviceId, code, entryUrl: origin, serviceUrl: origin })).toString('base64url');
+    return url.href;
+}
+export async function runFederationCli(args) {
+    try {
+        if (args[0] === '--federation-pairing') {
+            let explicitUrl;
+            let json = false;
+            for (let i = 1; i < args.length; i++) {
+                if (args[i] === '--json' && !json)
+                    json = true;
+                else if (args[i] === '--url' && explicitUrl === undefined && args[i + 1])
+                    explicitUrl = args[++i];
+                else
+                    throw new Error('Usage: termdock --federation-pairing [--url https://service:port] [--json]');
+            }
+            const file = resolve(homedir(), '.termdock/federation/pairing.json');
+            if (process.platform !== 'win32' && (statSync(file).mode & 0o077) !== 0)
+                throw new Error('配对文件权限异常，请先 chmod 600 配对文件。');
+            const data = JSON.parse(readFileSync(file, 'utf8'));
+            if (!data || typeof data.serviceId !== 'string' || typeof data.pairingCode !== 'string')
+                throw new Error('Invalid pairing file; start the service to initialize pairing');
+            if (json) {
+                process.stdout.write(`${JSON.stringify({ serviceId: data.serviceId, pairingCode: data.pairingCode, ...(explicitUrl ? { url: explicitUrl } : typeof data.url === 'string' ? { url: data.url } : {}) })}\n`);
+                return 0;
+            }
+            let serviceUrl = explicitUrl ?? (typeof data.url === 'string' ? data.url : undefined);
+            if (!serviceUrl) {
+                try {
+                    const state = JSON.parse(readFileSync(resolve(homedir(), '.termdock/server.json'), 'utf8'));
+                    serviceUrl = typeof state.lanUrl === 'string' ? state.lanUrl : typeof state.localUrl === 'string' ? state.localUrl : undefined;
+                }
+                catch { /* Require an explicit usable service URL below. */ }
+            }
+            if (!serviceUrl)
+                throw new Error('请添加 --url https://服务地址:端口，生成可直接打开的配对链接。');
+            const invitation = pairingInviteUrl(data.serviceId, data.pairingCode, serviceUrl);
+            process.stdout.write(`用新设备打开链接或扫描二维码，即可一次性配对本服务：\n${invitation}\n`);
+            process.stdout.write(await QRCode.toString(invitation, { type: 'terminal', small: true }));
+            return 0;
+        }
+        if (args[0] !== '--federation-relay' || args.length !== 2)
+            throw new Error('Usage: termdock --federation-pairing [--url https://service:port] [--json] | termdock --federation-relay <config.json>');
+        const configPath = resolve(args[1]);
+        if (process.platform !== 'win32' && (statSync(configPath).mode & 0o077) !== 0)
+            throw new Error('Relay config contains a token: chmod 600 the config file first');
+        const config = parseRelayConfig(JSON.parse(readFileSync(configPath, 'utf8')));
+        const loadCa = (file) => file ? readFileSync(resolve(dirname(configPath), file)) : undefined;
+        const entryCa = loadCa(config.caPath);
+        const targets = config.targets.map(t => ({ ...t, ca: loadCa(t.caPath ?? config.caPath) }));
+        const sockets = new Set();
+        let stopped = false;
+        let client;
+        let wake;
+        const stop = () => { stopped = true; wake?.(); client?.close(); for (const socket of sockets)
+            socket.terminate(); };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        let delay = 1000;
+        try {
+            while (!stopped) {
+                try {
+                    const upstream = await connect(secureEndpoint(config.entryUrl, '/api/federation/relay'), entryCa, sockets, config.relayToken, true);
+                    if (stopped) {
+                        upstream.terminate();
+                        break;
+                    }
+                    client = new RelayClient(upstream, { targets: new Map(targets.map(t => [t.serviceId, () => connect(secureEndpoint(t.url, '/api/federation/secure'), t.ca, sockets)])) });
+                    process.stderr.write('加密中继已连接。\n');
+                    delay = 1000;
+                    await new Promise(done => { if (upstream.readyState !== WebSocket.OPEN)
+                        done();
+                    else
+                        upstream.once('close', () => done()); });
+                }
+                catch {
+                    if (!stopped)
+                        process.stderr.write('中继连接失败或已断开，将重试；请检查授权和证书。\n');
+                }
+                client?.close();
+                client = undefined;
+                for (const socket of sockets)
+                    socket.terminate();
+                if (!stopped)
+                    await new Promise(done => { const timer = setTimeout(() => { wake = undefined; done(); }, delay); wake = () => { clearTimeout(timer); wake = undefined; done(); }; });
+                delay = Math.min(delay * 2, 30_000);
+            }
+        }
+        finally {
+            stop();
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+        }
+        return 0;
+    }
+    catch (error) {
+        // Config parsing and network failures must not echo the config or its token.
+        const message = error instanceof Error && !('code' in error) && !(error instanceof SyntaxError) ? error.message : '无法读取有效配置或配对信息。';
+        process.stderr.write(`${message}\n`);
+        return 1;
+    }
+}

package/dist/server/federation/deviceNames.js

@@ -0,0 +1,29 @@
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+/** Display metadata only; never participates in authorization. */
+export class DeviceNames {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    list() {
+        try {
+            return Object.fromEntries(Object.entries(JSON.parse(readFileSync(this.file, 'utf8'))).filter(([, name]) => typeof name === 'string'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return {};
+            throw error;
+        }
+    }
+    set(subjectId, name, onlyIfMissing) {
+        if (typeof name !== 'string' || !name.trim() || name.length > 80 || /[\x00-\x1f\x7f]/.test(name))
+            throw new Error('INVALID_DEVICE_NAME');
+        const names = this.list();
+        if (onlyIfMissing && Object.hasOwn(names, subjectId))
+            return names[subjectId];
+        const next = Object.fromEntries([...Object.entries(names).filter(([id]) => id !== subjectId), [subjectId, name.trim()]]);
+        writeFileSync(`${this.file}.tmp`, JSON.stringify(next), { mode: 0o600 });
+        renameSync(`${this.file}.tmp`, this.file);
+        return name.trim();
+    }
+}

package/dist/server/federation/directRoutes.js

@@ -0,0 +1,72 @@
+import { createIdentity, secureConnection } from './secureProtocol.js';
+import { socketDuplex } from './socketDuplex.js';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import WebSocket from 'ws';
+function endpoint(config) {
+    if (!config || typeof config !== 'object' || Object.keys(config).some(key => !['serviceId', 'url', 'caPath'].includes(key)) || !/^[a-zA-Z0-9_.:-]{1,160}$/.test(config.serviceId) || typeof config.url !== 'string' || (config.caPath !== undefined && typeof config.caPath !== 'string'))
+        throw new Error('Invalid direct target configuration');
+    const url = new URL(config.url);
+    if (!['https:', 'wss:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || !['/', '/api/federation/secure'].includes(url.pathname))
+        throw new Error('Direct targets require a verified HTTPS/WSS origin');
+    url.protocol = 'wss:';
+    url.pathname = '/api/federation/secure';
+    return url.toString();
+}
+/** Registers only administrator-configured destinations. TLS validation and redirect
+ * refusal apply even though the inner session also has end-to-end encryption. */
+export function attachRegisteredDirectTargets(router, configs, baseDir = process.cwd()) {
+    if (!Array.isArray(configs) || configs.length > 64)
+        throw new Error('Invalid direct target registry');
+    const ids = new Set();
+    const targets = configs.map(config => {
+        const url = endpoint(config);
+        if (ids.has(config.serviceId))
+            throw new Error('Duplicate direct target');
+        ids.add(config.serviceId);
+        return { serviceId: config.serviceId, url, ca: config.caPath ? readFileSync(resolve(baseDir, config.caPath)) : undefined };
+    });
+    let stopped = false;
+    const sockets = new Set();
+    const cleanups = [];
+    const cleanup = () => { stopped = true; for (const close of cleanups.splice(0))
+        close(); for (const ws of sockets)
+        ws.terminate(); };
+    try {
+        for (const target of targets)
+            cleanups.push(router.registerDirect(target.serviceId, () => new Promise((accept, reject) => {
+                if (stopped) {
+                    reject(new Error('Direct target stopped'));
+                    return;
+                }
+                const ws = new WebSocket(target.url, { ca: target.ca, rejectUnauthorized: true, followRedirects: false, handshakeTimeout: 10000, maxPayload: 256 * 1024 });
+                sockets.add(ws);
+                ws.once('close', () => sockets.delete(ws));
+                const failed = () => { reject(new Error('Direct target unavailable')); ws.terminate(); };
+                ws.once('error', failed);
+                ws.once('close', failed);
+                ws.once('open', () => { ws.off('error', failed); ws.off('close', failed); ws.on('error', () => ws.terminate()); if (stopped)
+                    failed();
+                else
+                    accept(ws); });
+            })));
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+    return cleanup;
+}
+/** An administrator enabling a new backup first proves the target's pinned
+ * identity; HTTPS validation remains enabled throughout. */
+export async function verifyDirectTarget(config) {
+    const ws = new WebSocket(endpoint(config), { rejectUnauthorized: true, followRedirects: false, handshakeTimeout: 5000, maxPayload: 256 * 1024 });
+    const duplex = socketDuplex(ws);
+    try {
+        await new Promise((resolve, reject) => { ws.once('open', resolve); ws.once('error', reject); ws.once('close', () => reject(new Error('Target closed'))); });
+        await secureConnection({ identity: await createIdentity(), initiator: true, targetPinnedPeerId: config.serviceId, duplex, signal: AbortSignal.timeout(5000) });
+    }
+    finally {
+        ws.close();
+    }
+}

package/dist/server/federation/invitations.js

@@ -0,0 +1,123 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync, chmodSync } from 'node:fs';
+import { dirname } from 'node:path';
+const TTL = 10 * 60 * 1000;
+const actions = new Set(['session.view', 'session.input', 'session.resize', 'session.terminate']);
+const identity = (v) => typeof v === 'string' && v.length > 0 && v.length <= 512 && !/[\s\x00-\x1f]/.test(v);
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function requireValid(ok) { if (!ok)
+    throw new Error('INVALID_INVITATION'); }
+export function validateInvitation(input) {
+    requireValid(record(input) && Object.keys(input).every(k => ['scope', 'actions', 'label', 'expiresAt'].includes(k)));
+    requireValid(record(input.scope) && Array.isArray(input.actions) && input.actions.length > 0 && new Set(input.actions).size === input.actions.length);
+    const scope = input.scope;
+    if (scope.kind === 'service') {
+        requireValid(Object.keys(scope).length === 1 && ((input.actions.length === 1 && input.actions[0] === 'service:*') || input.actions.every(a => typeof a === 'string' && actions.has(a))));
+    }
+    else {
+        requireValid(scope.kind === 'sessions' && Object.keys(scope).every(k => ['kind', 'sessionIds'].includes(k))
+            && Array.isArray(scope.sessionIds) && scope.sessionIds.length > 0 && scope.sessionIds.length <= 256
+            && scope.sessionIds.every(identity) && new Set(scope.sessionIds).size === scope.sessionIds.length
+            && input.actions.every(a => typeof a === 'string' && actions.has(a)));
+    }
+    requireValid(input.label === undefined || (typeof input.label === 'string' && input.label.trim().length > 0 && input.label.length <= 80 && !/[\x00-\x1f\x7f]/.test(input.label)));
+    requireValid(input.expiresAt === undefined || (Number.isSafeInteger(input.expiresAt) && Number(input.expiresAt) > 0));
+}
+/** Single owning process, synchronous consume-before-grant: a crash may burn an invite,
+ * but can never redeem it twice. Raw invitation codes are never persisted. */
+export class InvitationStore {
+    options;
+    now;
+    constructor(options) {
+        this.options = options;
+        requireValid(identity(options.serviceId));
+        this.now = options.now ?? Date.now;
+        this.read();
+    }
+    hash(code) { return createHash('sha256').update(`termdock-invitation-v1:${this.options.serviceId}:`).update(code).digest('hex'); }
+    read() {
+        let raw;
+        try {
+            raw = readFileSync(this.options.filePath, 'utf8');
+            chmodSync(this.options.filePath, 0o600);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const data = JSON.parse(raw);
+        requireValid(record(data) && data.version === 1 && data.serviceId === this.options.serviceId && Array.isArray(data.invitations) && data.invitations.length <= 2048);
+        const seen = new Set();
+        for (const item of data.invitations) {
+            requireValid(record(item) && Object.keys(item).every(k => ['scope', 'actions', 'label', 'expiresAt', 'hash', 'issuerId', 'createdAt', 'invitationExpiresAt', 'consumedAt', 'consumedBy'].includes(k)));
+            const { scope, actions, label, expiresAt, hash, issuerId, createdAt, invitationExpiresAt, consumedAt, consumedBy } = item;
+            validateInvitation({ scope, actions, ...(label === undefined ? {} : { label }), ...(expiresAt === undefined ? {} : { expiresAt }) });
+            requireValid(typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash) && !seen.has(hash) && identity(issuerId));
+            seen.add(hash);
+            requireValid(Number.isSafeInteger(createdAt) && Number.isSafeInteger(invitationExpiresAt) && Number(invitationExpiresAt) === Number(createdAt) + TTL);
+            requireValid((consumedAt === undefined && consumedBy === undefined) || (Number.isSafeInteger(consumedAt) && identity(consumedBy)));
+        }
+        return data.invitations;
+    }
+    save(invitations) {
+        mkdirSync(dirname(this.options.filePath), { recursive: true, mode: 0o700 });
+        const temporary = `${this.options.filePath}.${randomUUID()}.tmp`;
+        let fd;
+        try {
+            fd = openSync(temporary, 'wx', 0o600);
+            writeFileSync(fd, JSON.stringify({ version: 1, serviceId: this.options.serviceId, invitations }, null, 2));
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            renameSync(temporary, this.options.filePath);
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+            try {
+                unlinkSync(temporary);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    create(issuerId, input) {
+        requireValid(identity(issuerId));
+        validateInvitation(input);
+        const now = this.now();
+        requireValid(input.expiresAt === undefined || input.expiresAt > now);
+        const current = this.read().filter(i => i.consumedAt !== undefined || i.invitationExpiresAt > now);
+        if (current.filter(i => i.consumedAt === undefined).length >= 256)
+            throw new Error('INVITATION_LIMIT');
+        // Keep bounded device-friendly metadata; retain all still-active invitations.
+        while (current.length >= 2048) {
+            const index = current.findIndex(i => i.consumedAt !== undefined);
+            if (index < 0)
+                throw new Error('INVITATION_LIMIT');
+            current.splice(index, 1);
+        }
+        const code = randomBytes(32).toString('base64url');
+        const invitation = { ...structuredClone(input), ...(input.label ? { label: input.label.trim() } : {}), hash: this.hash(code), issuerId, createdAt: now, invitationExpiresAt: now + TTL };
+        current.push(invitation);
+        this.save(current);
+        return { code, expiresAt: invitation.invitationExpiresAt };
+    }
+    consume(code, subjectId, issuerAllowed) {
+        if (!/^[A-Za-z0-9_-]{43}$/.test(code) || !identity(subjectId))
+            throw new Error('PAIRING_DENIED');
+        const current = this.read(), hash = this.hash(code), now = this.now();
+        const invite = current.find(i => i.hash === hash);
+        if (!invite || invite.consumedAt !== undefined || invite.invitationExpiresAt <= now || (invite.expiresAt !== undefined && invite.expiresAt <= now) || !issuerAllowed(invite.issuerId))
+            throw new Error('PAIRING_DENIED');
+        invite.consumedAt = now;
+        invite.consumedBy = subjectId;
+        this.save(current);
+        return { subjectId, scope: structuredClone(invite.scope), actions: [...invite.actions], ...(invite.expiresAt === undefined ? {} : { expiresAt: invite.expiresAt }), canDelegate: false };
+    }
+    subjectLabels() {
+        return Object.fromEntries(this.read().filter(i => i.consumedBy && i.label).map(i => [i.consumedBy, i.label]));
+    }
+}

package/dist/server/federation/openAccess.js

@@ -0,0 +1,25 @@
+import express from 'express';
+import { isAuthEnabled } from '../utils/authProtection.js';
+import { bootstrapCors } from './bootstrapCors.js';
+/** Open mode is per connection and transient; it must never create persisted grants. */
+export function openAccessAllowed(direct, authEnabled, action) {
+    return direct && !authEnabled && (!action || !action.startsWith('authorization.') && !action.startsWith('route.'));
+}
+export function createOpenAccessRouter(serviceIdentity) {
+    const router = express.Router();
+    router.use(bootstrapCors);
+    router.get('/parameters', (_req, res) => {
+        res.setHeader('Cache-Control', 'no-store');
+        if (isAuthEnabled()) {
+            res.status(403).json({ error: 'Password authentication required' });
+            return;
+        }
+        const identity = serviceIdentity();
+        if (!identity) {
+            res.status(503).json({ error: 'Encrypted access is starting' });
+            return;
+        }
+        res.json({ serviceIdentity: identity });
+    });
+    return router;
+}

package/dist/server/federation/originPolicy.js

@@ -0,0 +1,19 @@
+/** Noise endpoints never use cookies as authority. A browser may legitimately
+ * connect to a pinned target from another HTTPS service's PWA; possession of
+ * the paired device key is still required before any business operation.
+ * Legacy cookie-authenticated endpoints must not use this relaxed policy. */
+export function secureChannelOriginAllowed(origin, sameOriginAllowed) {
+    if (origin === undefined)
+        return true; // Native CLI/Mac relay.
+    try {
+        const parsed = new URL(origin);
+        if (parsed.origin !== origin)
+            return false;
+        if (parsed.protocol === 'https:')
+            return true;
+        return parsed.protocol === 'http:' && sameOriginAllowed();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/server/federation/packets.js

@@ -0,0 +1,116 @@
+/** Bounded queues are also used at the untrusted, pre-handshake boundary. */
+export class AsyncQueue {
+    limit;
+    items = [];
+    wake;
+    ended = false;
+    error;
+    constructor(limit = 64) {
+        this.limit = limit;
+    }
+    push(value) {
+        if (this.ended)
+            throw new Error('Channel closed');
+        if (this.items.length >= this.limit) {
+            this.end(new Error('Channel queue exceeded'));
+            throw this.error;
+        }
+        this.items.push(value);
+        this.wake?.();
+    }
+    end(error) { this.ended = true; this.error ??= error; this.wake?.(); }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            if (this.error)
+                throw this.error;
+            const item = this.items.shift();
+            if (item !== undefined) {
+                yield item;
+                continue;
+            }
+            if (this.ended)
+                return;
+            await new Promise(resolve => { this.wake = resolve; });
+            this.wake = undefined;
+        }
+    }
+}
+const MAX_PACKET = 2 * 1024 * 1024;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+/** Application records live entirely inside Noise; transport routing never sees them. */
+export class PacketChannel {
+    duplex;
+    outgoing = new AsyncQueue(256);
+    outgoingBytes = 0;
+    done;
+    constructor(duplex) {
+        this.duplex = duplex;
+        const self = this;
+        this.done = duplex.sink((async function* () {
+            for await (const bytes of self.outgoing) {
+                try {
+                    yield bytes;
+                }
+                finally {
+                    self.outgoingBytes -= bytes.byteLength;
+                }
+            }
+        })());
+        void this.done.catch(error => this.close(error instanceof Error ? error : new Error('Transport failed')));
+    }
+    send(packet) {
+        const body = encoder.encode(JSON.stringify(packet));
+        if (body.length > MAX_PACKET)
+            throw new Error('Record too large');
+        const bytes = new Uint8Array(body.length + 4);
+        new DataView(bytes.buffer).setUint32(0, body.length);
+        bytes.set(body, 4);
+        if (this.outgoingBytes + bytes.byteLength > 4 * 1024 * 1024)
+            throw new Error('Record queue byte budget exceeded');
+        this.outgoingBytes += bytes.byteLength;
+        try {
+            this.outgoing.push(bytes);
+        }
+        catch (error) {
+            this.outgoingBytes -= bytes.byteLength;
+            throw error;
+        }
+    }
+    close(error) { this.outgoing.end(error); this.duplex.close?.(error); }
+    async *read() {
+        let pending = new Uint8Array(0);
+        for await (const chunk of this.duplex.source) {
+            if (pending.length + chunk.length > MAX_PACKET * 2 + 8)
+                throw new Error('Record buffer exceeded');
+            const next = new Uint8Array(pending.length + chunk.length);
+            next.set(pending);
+            next.set(chunk, pending.length);
+            pending = next;
+            while (pending.length >= 4) {
+                const size = new DataView(pending.buffer, pending.byteOffset, 4).getUint32(0);
+                if (size > MAX_PACKET || size === 0)
+                    throw new Error('Invalid record size');
+                if (pending.length < size + 4)
+                    break;
+                const packet = JSON.parse(decoder.decode(pending.subarray(4, size + 4)));
+                if (!packet || typeof packet !== 'object' || typeof packet.id !== 'string' || typeof packet.type !== 'string')
+                    throw new Error('Invalid record');
+                yield packet;
+                pending = pending.slice(size + 4);
+            }
+        }
+        if (pending.length)
+            throw new Error('Truncated record');
+    }
+}
+export function toBase64(bytes) {
+    let value = '';
+    for (let offset = 0; offset < bytes.length; offset += 8192)
+        value += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+    return btoa(value);
+}
+export function fromBase64(value) {
+    const raw = atob(value);
+    return Uint8Array.from(raw, c => c.charCodeAt(0));
+}

package/dist/server/federation/passwordBootstrap.js

@@ -0,0 +1,86 @@
+import * as opaque from '@serenity-kit/opaque';
+import { scryptAsync } from '@noble/hashes/scrypt.js';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+// Existing credentials are password-equivalent here. Never send the stored hash
+// over the wire. OPAQUE authenticates both Noise identities before any grant.
+const keyStretching = 'memory-constrained';
+const userIdentifier = 'termdock-password-bootstrap-v1';
+const TTL = 60_000;
+function identifiers(clientIdentity, serverIdentity, origin) {
+    if (!clientIdentity || clientIdentity.length > 256 || !serverIdentity || serverIdentity.length > 256 ||
+        origin.length > 2048 || new URL(origin).origin !== origin)
+        throw new Error('Invalid bootstrap identity');
+    return { client: JSON.stringify([userIdentifier, origin, clientIdentity]), server: serverIdentity };
+}
+function bounded(value) {
+    if (typeof value !== 'string' || value.length < 1 || value.length > 8192)
+        throw new Error('Invalid OPAQUE message');
+}
+export async function startPasswordBootstrap(password, saltHex) {
+    if (!/^[0-9a-f]{32}$/.test(saltHex) || !password || password.length > 1024 || new TextEncoder().encode(password).length > 4096)
+        throw new Error('Invalid password parameters');
+    await opaque.ready;
+    const passwordKey = bytesToHex(await scryptAsync(password, hexToBytes(saltHex), { N: 32768, r: 8, p: 1, dkLen: 64, maxmem: 67108864 }));
+    return { ...opaque.client.startLogin({ password: passwordKey }), passwordKey };
+}
+export async function finishPasswordBootstrap(state, response, binding) {
+    await opaque.ready;
+    bounded(response.loginResponse);
+    const result = opaque.client.finishLogin({ clientLoginState: state.clientLoginState, password: state.passwordKey,
+        loginResponse: response.loginResponse, keyStretching,
+        identifiers: identifiers(binding.clientIdentity, response.serverIdentity, binding.origin) });
+    if (!result)
+        throw new Error('Password authentication failed');
+    return { attemptId: response.attemptId, finishLoginRequest: result.finishLoginRequest, serverIdentity: response.serverIdentity };
+}
+export class PasswordBootstrapServer {
+    options;
+    setup;
+    pending = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    now() { return this.options.now?.() ?? Date.now(); }
+    credential() {
+        const hash = this.options.getPasswordHash();
+        if (!hash || !/^scrypt\$[0-9a-f]{32}\$[0-9a-f]{128}$/.test(hash))
+            throw new Error('Password authentication unavailable');
+        return hash;
+    }
+    parameters() { return { saltHex: this.credential().split('$')[1] }; }
+    async start(input) {
+        bounded(input.startLoginRequest);
+        const ids = identifiers(input.clientIdentity, this.options.serverIdentity, input.origin);
+        for (const [id, entry] of this.pending)
+            if (entry.expiresAt <= this.now())
+                this.pending.delete(id);
+        if (this.pending.size >= 32)
+            throw new Error('Too many password login attempts');
+        const credential = this.credential();
+        await opaque.ready;
+        if (this.pending.size >= 32)
+            throw new Error('Too many password login attempts');
+        this.setup ??= opaque.server.createSetup();
+        const password = credential.split('$')[2];
+        // Registration is local migration from the existing scrypt credential; no
+        // unauthenticated network registration endpoint or password reset is needed.
+        const registration = opaque.client.startRegistration({ password });
+        const { registrationResponse } = opaque.server.createRegistrationResponse({ ...registration, serverSetup: this.setup, userIdentifier });
+        const { registrationRecord } = opaque.client.finishRegistration({ ...registration, registrationResponse, password, identifiers: ids, keyStretching });
+        const result = opaque.server.startLogin({ serverSetup: this.setup, registrationRecord, userIdentifier,
+            startLoginRequest: input.startLoginRequest, identifiers: ids });
+        const attemptId = globalThis.crypto.randomUUID();
+        this.pending.set(attemptId, { serverLoginState: result.serverLoginState, clientIdentity: input.clientIdentity, credential, expiresAt: this.now() + TTL });
+        return { attemptId, loginResponse: result.loginResponse, serverIdentity: this.options.serverIdentity };
+    }
+    async finish(input) {
+        bounded(input.finishLoginRequest);
+        const entry = this.pending.get(input.attemptId);
+        this.pending.delete(input.attemptId);
+        if (!entry || entry.expiresAt <= this.now() || entry.credential !== this.credential())
+            throw new Error('Password login expired');
+        await opaque.ready;
+        opaque.server.finishLogin({ serverLoginState: entry.serverLoginState, finishLoginRequest: input.finishLoginRequest });
+        return { clientIdentity: entry.clientIdentity, serverIdentity: this.options.serverIdentity };
+    }
+}