termdock 1.4.173 → 1.4.175

package/dist/server/federation/authorization.js

@@ -0,0 +1,226 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+const id = (v) => typeof v === 'string' && v.length > 0 && v.length <= 512 && !/[\s\x00-\x1f]/.test(v);
+const action = (v) => typeof v === 'string' && (v === 'service:*' || /^[a-z][a-z0-9_-]*\.[a-z][a-z0-9_-]*$/.test(v));
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function assert(value, message) { if (!value)
+    throw new Error(`Invalid authorization: ${message}`); }
+function keys(v, allowed) { assert(Object.keys(v).every(k => allowed.includes(k)), 'unknown field'); }
+function ids(v) { return Array.isArray(v) && v.length > 0 && v.length <= 10000 && v.every(id) && new Set(v).size === v.length; }
+function validateInput(v) {
+    assert(object(v), 'grant object');
+    assert(id(v.subjectId), 'subject identity');
+    assert(object(v.scope), 'scope');
+    if (v.scope.kind === 'service')
+        keys(v.scope, ['kind']);
+    else {
+        assert(v.scope.kind === 'sessions' && ids(v.scope.sessionIds), 'session scope');
+        keys(v.scope, ['kind', 'sessionIds']);
+    }
+    assert(Array.isArray(v.actions) && v.actions.length > 0 && v.actions.length <= 256 && v.actions.every(action) && new Set(v.actions).size === v.actions.length, 'actions');
+    if (v.scope.kind === 'sessions')
+        assert(v.actions.every(a => a.startsWith('session.')), 'session scope cannot grant service or file capabilities');
+    assert(v.expiresAt === undefined || (Number.isSafeInteger(v.expiresAt) && Number(v.expiresAt) > 0), 'expiry');
+    assert(v.canDelegate === undefined || typeof v.canDelegate === 'boolean', 'delegation flag');
+    if (v.conditions !== undefined) {
+        assert(object(v.conditions), 'conditions');
+        keys(v.conditions, ['entryServiceIds', 'relayIds']);
+        for (const list of Object.values(v.conditions))
+            assert(ids(list), 'condition identities');
+    }
+}
+function isSubset(child, parent) {
+    if (child.serviceId !== parent.serviceId || !parent.canDelegate)
+        return false;
+    if (parent.expiresAt !== undefined && (child.expiresAt === undefined || child.expiresAt > parent.expiresAt))
+        return false;
+    if (parent.scope.kind === 'sessions' && (child.scope.kind !== 'sessions' || !child.scope.sessionIds.every(s => parent.scope.kind === 'sessions' && parent.scope.sessionIds.includes(s))))
+        return false;
+    if (!parent.actions.includes('service:*') && !child.actions.every(a => parent.actions.includes(a)))
+        return false;
+    for (const key of ['entryServiceIds', 'relayIds']) {
+        const limit = parent.conditions?.[key];
+        if (limit && (!child.conditions?.[key] || !child.conditions[key].every(x => limit.includes(x))))
+            return false;
+    }
+    return true;
+}
+function active(g, grants, now, seen = new Set(), passwordCredential) {
+    if (seen.has(g.id) || g.createdAt > now || g.revokedAt !== undefined || (g.expiresAt !== undefined && g.expiresAt <= now))
+        return false;
+    if (g.passwordCredential && g.passwordCredential !== passwordCredential)
+        return false;
+    seen.add(g.id);
+    if (!g.parentGrantId)
+        return true;
+    const parent = grants.find(p => p.id === g.parentGrantId);
+    return !!parent && isSubset(g, parent) && active(parent, grants, now, seen, passwordCredential);
+}
+/** Target-service authority. Root mutations must only be exposed to authenticated administrators.
+ * Every operation reloads disk; synchronous atomic writes support one owning server process.
+ * Do not share this file between concurrently writing processes. */
+export class AuthorizationStore {
+    options;
+    now;
+    constructor(options) {
+        this.options = options;
+        assert(id(options.serviceId), 'service identity');
+        this.now = options.now ?? Date.now;
+        this.read();
+    }
+    read() {
+        let raw;
+        try {
+            raw = readFileSync(this.options.filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const data = JSON.parse(raw);
+        assert(object(data) && data.version === 1 && data.serviceId === this.options.serviceId && Array.isArray(data.grants), 'store header');
+        keys(data, ['version', 'serviceId', 'grants']);
+        const grants = [];
+        for (const value of data.grants) {
+            validateInput(value);
+            const g = value;
+            keys(g, ['id', 'serviceId', 'createdAt', 'parentGrantId', 'revokedAt', 'subjectId', 'scope', 'actions', 'expiresAt', 'canDelegate', 'conditions', 'passwordCredential']);
+            assert(id(g.id) && g.serviceId === this.options.serviceId && Number.isSafeInteger(g.createdAt) && g.createdAt >= 0, 'grant metadata');
+            assert(g.parentGrantId === undefined || id(g.parentGrantId), 'parent identity');
+            assert(g.revokedAt === undefined || (Number.isSafeInteger(g.revokedAt) && g.revokedAt >= 0), 'revocation');
+            assert(g.passwordCredential === undefined || /^[a-f0-9]{64}$/.test(g.passwordCredential), 'password credential');
+            assert(!grants.some(p => p.id === g.id), 'duplicate grant');
+            grants.push(g);
+        }
+        return grants;
+    }
+    save(grants) {
+        mkdirSync(dirname(this.options.filePath), { recursive: true, mode: 0o700 });
+        const temp = `${this.options.filePath}.${randomUUID()}.tmp`;
+        let fd;
+        try {
+            fd = openSync(temp, 'wx', 0o600);
+            writeFileSync(fd, JSON.stringify({ version: 1, serviceId: this.options.serviceId, grants }, null, 2));
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            renameSync(temp, this.options.filePath);
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+            try {
+                unlinkSync(temp);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    create(input) {
+        validateInput(input);
+        keys(input, ['subjectId', 'scope', 'actions', 'expiresAt', 'canDelegate', 'conditions']);
+        const now = this.now();
+        assert(input.expiresAt === undefined || input.expiresAt > now, 'already expired');
+        return { ...structuredClone(input), id: randomUUID(), serviceId: this.options.serviceId, createdAt: now };
+    }
+    /** Trusted target administrator only; never authorize this from a relay's identity. */
+    grant(input) {
+        const grants = this.read();
+        const grant = this.create(input);
+        grants.push(grant);
+        this.save(grants);
+        return structuredClone(grant);
+    }
+    /** Only call after a successful mutually authenticated password proof. */
+    grantPassword(subjectId) {
+        const passwordCredential = this.options.passwordCredential?.();
+        assert(passwordCredential && /^[a-f0-9]{64}$/.test(passwordCredential), 'password unavailable');
+        const grants = this.read();
+        for (const grant of grants)
+            if (grant.subjectId === subjectId && grant.passwordCredential)
+                grant.revokedAt = this.now();
+        const grant = { ...this.create({ subjectId, scope: { kind: 'service' }, actions: ['service:*'], canDelegate: true, expiresAt: this.now() + 30 * 24 * 60 * 60 * 1000 }), passwordCredential };
+        grants.push(grant);
+        this.save(grants);
+        return structuredClone(grant);
+    }
+    delegate(parentGrantId, authenticatedSubjectId, input) {
+        const grants = this.read();
+        const parent = grants.find(g => g.id === parentGrantId);
+        assert(parent && parent.subjectId === authenticatedSubjectId && active(parent, grants, this.now(), new Set(), this.options.passwordCredential?.()), 'inactive or unowned parent');
+        const child = { ...this.create(input), parentGrantId };
+        assert(isSubset(child, parent), 'delegation exceeds parent');
+        grants.push(child);
+        this.save(grants);
+        return structuredClone(child);
+    }
+    /** Trusted target administrator only. Descendants become ineffective immediately on next check. */
+    revoke(grantId) {
+        const grants = this.read();
+        const grant = grants.find(g => g.id === grantId);
+        if (!grant || grant.revokedAt !== undefined)
+            return false;
+        grant.revokedAt = this.now();
+        this.save(grants);
+        return true;
+    }
+    list() { return this.read(); }
+    listEffective(request) {
+        if (!request || !id(request.subjectId) || request.serviceId !== this.options.serviceId)
+            return [];
+        let grants;
+        try {
+            grants = this.read();
+        }
+        catch {
+            return [];
+        }
+        const now = this.now();
+        return grants.filter(g => g.subjectId === request.subjectId && active(g, grants, now, new Set(), this.options.passwordCredential?.())
+            && (!g.conditions?.entryServiceIds || (!!request.entryServiceId && g.conditions.entryServiceIds.includes(request.entryServiceId)))
+            && (!g.conditions?.relayIds || (!!request.relayId && g.conditions.relayIds.includes(request.relayId))));
+    }
+    /** Tests the actual wildcard, not an invented action that custom grants could allow. */
+    hasFullServiceAccess(request) {
+        return this.listEffective(request).some(g => g.scope.kind === 'service' && g.actions.includes('service:*'));
+    }
+    authorize(request) {
+        const deny = { allowed: false, grantIds: [] };
+        if (!request || !id(request.subjectId) || request.serviceId !== this.options.serviceId || !action(request.action) || request.action === 'service:*')
+            return deny;
+        if (request.action.startsWith('session.') && !id(request.sessionId))
+            return deny;
+        if (request.sessionId !== undefined && !id(request.sessionId))
+            return deny;
+        if (request.entryServiceId !== undefined && !id(request.entryServiceId))
+            return deny;
+        if (request.relayId !== undefined && !id(request.relayId))
+            return deny;
+        let grants;
+        try {
+            grants = this.read();
+        }
+        catch {
+            return deny;
+        }
+        const now = this.now();
+        const grantIds = grants.filter(g => {
+            if (g.subjectId !== request.subjectId || !active(g, grants, now, new Set(), this.options.passwordCredential?.()))
+                return false;
+            if (!g.actions.includes('service:*') && !g.actions.includes(request.action))
+                return false;
+            if (g.scope.kind === 'sessions' && (!request.action.startsWith('session.') || !request.sessionId || !g.scope.sessionIds.includes(request.sessionId)))
+                return false;
+            if (g.conditions?.entryServiceIds && (!request.entryServiceId || !g.conditions.entryServiceIds.includes(request.entryServiceId)))
+                return false;
+            if (g.conditions?.relayIds && (!request.relayId || !g.conditions.relayIds.includes(request.relayId)))
+                return false;
+            return true;
+        }).map(g => g.id);
+        return { allowed: grantIds.length > 0, grantIds };
+    }
+}

package/dist/server/federation/bootstrapCors.js

@@ -0,0 +1,23 @@
+import { isAllowedOrigin } from '../utils/requestSecurity.js';
+import { secureChannelOriginAllowed } from './originPolicy.js';
+/** These endpoints exchange explicit password proofs, never cookies or grants
+ * from the caller's browser session. Business routes retain their strict policy. */
+export const bootstrapCors = (req, res, next) => {
+    const origin = req.headers.origin;
+    if (!secureChannelOriginAllowed(origin, () => isAllowedOrigin(origin, req.headers.host))) {
+        res.status(403).json({ error: 'Origin is not allowed', code: 'ORIGIN_NOT_ALLOWED' });
+        return;
+    }
+    res.setHeader('Cache-Control', 'no-store');
+    if (origin) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.vary('Origin');
+    }
+    if (req.method === 'OPTIONS') {
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        res.status(204).end();
+        return;
+    }
+    next();
+};

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]));
+    }
+}