termdock 1.4.174 → 1.4.175

package/dist/server/entry.js

@@ -1,7 +1,14 @@
+import { createOpenAccessRouter } from './federation/openAccess.js';
+import { createPasswordLoginRouter } from './federation/passwordLoginRoutes.js';
 import { apiAccessGate, isTrustedLocalRequest } from './utils/apiAccess.js';
+import { isEncryptedRequest } from './federation/requestContext.js';
+import { createFederationRuntime } from './federation/runtime.js';
+import { RouteAccess } from './federation/routeAccess.js';
+import { RouteInvitationStore } from './federation/routeInvitations.js';
+import { attachRegisteredDirectTargets, verifyDirectTarget } from './federation/directRoutes.js';
+import { secureChannelOriginAllowed } from './federation/originPolicy.js';
+import { RelayRouter } from './federation/relay.js';
 import { assertPublicSecurity, securityHeaders } from './utils/publicSecurity.js';
-import { guardWebSocketSession } from './utils/webSocketSecurity.js';
-import { readTerminalHandshakeDimensions } from './utils/terminalHandshakeDimensions.js';
 import { apiCachePolicy } from './utils/apiCachePolicy.js';
 import 'dotenv/config';
 import express from 'express';
@@ -23,7 +30,7 @@ import { createOnboardingRouter } from './routes/onboarding.js';
 import { createLocalRouter } from './routes/local.js';
 import { csrfProtection } from './utils/csrfProtection.js';
 import { pathValidator } from './utils/pathValidator.js';
-import { isUpgradeRequestAuthenticated, requireAuth, renewSessionMiddleware } from './utils/authProtection.js';
+import { requireAuth, renewSessionMiddleware } from './utils/authProtection.js';
 import { localAccessManager } from './utils/localAccess.js';
 import { isAllowedHost, isUpgradeOriginAllowed, validateHostMiddleware, validateOriginMiddleware, } from './utils/requestSecurity.js';
 import { getCookieSecurityOptions, setSecureCookieMode } from './utils/cookieSecurity.js';
@@ -37,22 +44,6 @@ import { getTermdockVersion, TERMDOCK_CAPABILITIES, TERMDOCK_PROTOCOL_VERSION, }
 import { PORT, DEFAULT_HOST } from './config.js';
 const CLIENT_STATE_COOKIE = 'termdock-client';
 export const DEFAULT_PORT = PORT.backend;
-/** Read one cookie from a raw Cookie header (upgrade requests bypass the
- *  cookie-parser middleware). Values are percent-encoded. */
-function getCookieValue(cookieHeader, name) {
-    if (!cookieHeader)
-        return undefined;
-    const pattern = new RegExp(`(?:^|;\\s*)${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}=([^;]*)`);
-    const match = cookieHeader.match(pattern);
-    if (!match)
-        return undefined;
-    try {
-        return decodeURIComponent(match[1]);
-    }
-    catch {
-        return match[1];
-    }
-}
 const CLIENT_LOG_DEDUP_WINDOW_MS = 5_000;
 const CLIENT_LOG_RATE_WINDOW_MS = 10_000;
 const CLIENT_LOG_RATE_LIMIT = 120;
@@ -146,6 +137,17 @@ export function createApp(options = {}) {
     app.disable('x-powered-by');
     app.use(securityHeaders);
     app.use(validateHostMiddleware);
+    if (options.secureRequired)
+        app.use('/api/auth/open', createOpenAccessRouter(() => app.locals.passwordRuntime?.serviceId));
+    if (options.secureRequired)
+        app.use('/api/auth/password', createPasswordLoginRouter(() => app.locals.passwordRuntime));
+    app.use('/api', (req, res, next) => {
+        if (!options.secureRequired || isEncryptedRequest(req) || isTrustedLocalRequest(req, options.localApiToken))
+            return next();
+        if (req.method === 'GET' && ['/meta', '/auth/status'].includes(req.path))
+            return next();
+        res.status(426).json({ error: 'Pair this device to use an encrypted connection', code: 'E2EE_REQUIRED' });
+    });
     // Authenticate before allocating request bodies, including future API routes.
     app.use(cookieParser());
     app.use('/api', renewSessionMiddleware);
@@ -393,12 +395,78 @@ export function startServer(options = {}) {
     });
     runtimeMonitor.start();
     const app = createApp({
+        secureRequired: true,
         port: options.onboardingPort ?? port,
         httpsCaPath: options.httpsCaPath,
         localApiToken: options.localApiToken,
         runtimeMonitor,
     });
     const { server, scheme } = createServerForApp(app, options);
+    let entrySubjectAllowed = (_subjectId) => false;
+    let routeInvitations;
+    const routeAccess = new RouteAccess(path.join(homedir(), '.termdock', 'federation', 'routes.json'), Date.now, (subjectId, targetServiceId) => routeInvitations?.allows(subjectId, targetServiceId) === true);
+    const relayRouter = new RelayRouter({
+        authenticate: context => context,
+        allowRegister: (principal, serviceId) => routeAccess.allowRegister(principal, serviceId),
+        allowRoute: (principal, serviceId) => routeAccess.allowRoute(principal, serviceId),
+    });
+    const dynamicDirectTargets = new Map();
+    server.once('close', () => { for (const close of dynamicDirectTargets.values())
+        close(); });
+    try {
+        const detachDirectTargets = attachRegisteredDirectTargets(relayRouter, routeAccess.configuredDirectTargets(), path.join(homedir(), '.termdock', 'federation'));
+        server.once('close', detachDirectTargets);
+    }
+    catch {
+        console.error('Configured direct routes unavailable; target access remains closed.');
+    }
+    server.once('close', () => relayRouter.close());
+    const federation = createFederationRuntime(app, path.join(homedir(), '.termdock', 'federation'), {
+        terminal: handleTerminalWebSocket, control: handleControlWebSocket,
+    }, {
+        listRouteAccess: () => routeInvitations?.list() || [],
+        grantRouteAccess: async (issuerId, targetServiceId, subjectId, url) => {
+            if (!routeInvitations)
+                throw new Error('ROUTE_NOT_AVAILABLE');
+            if (!routeAccess.hasConfiguredTarget(targetServiceId)) {
+                if (!url)
+                    throw new Error('ROUTE_TARGET_NOT_CONFIGURED');
+                const target = { serviceId: targetServiceId, url };
+                await verifyDirectTarget(target);
+                const runtime = await federation;
+                if (!runtime.store.authorize({ subjectId: issuerId, serviceId: runtime.serviceId, action: 'authorization.manage' }).allowed)
+                    throw new Error('AUTHORIZATION_DENIED');
+                routeAccess.addDirectTarget(target);
+                if (!dynamicDirectTargets.has(targetServiceId))
+                    dynamicDirectTargets.set(targetServiceId, attachRegisteredDirectTargets(relayRouter, [target]));
+            }
+            return routeInvitations.grant(issuerId, targetServiceId, subjectId);
+        },
+        revokeRouteAccess: id => routeInvitations?.revoke(id) || false,
+        issueRouteTicket: (subjectId, serviceId) => routeAccess.issueRouteTicket(subjectId, serviceId),
+        hasRouteGrant: (subjectId, serviceId) => routeInvitations?.allows(subjectId, serviceId) === true,
+        createRouteInvitation: (issuerId, serviceId) => {
+            if (!routeInvitations)
+                throw new Error('ROUTE_NOT_AVAILABLE');
+            return routeInvitations.create(issuerId, serviceId);
+        },
+        consumeRouteInvitation: (code, subjectId) => {
+            if (!routeInvitations)
+                throw new Error('ROUTE_NOT_AVAILABLE');
+            return routeInvitations.consume(code, subjectId);
+        },
+    });
+    void federation.then(runtime => {
+        app.locals.passwordRuntime = runtime;
+        entrySubjectAllowed = subjectId => runtime.store.authorize({ subjectId, serviceId: runtime.serviceId, action: 'authorization.manage' }).allowed;
+        routeInvitations = new RouteInvitationStore({
+            filePath: path.join(homedir(), '.termdock', 'federation', 'route-invitations.json'), serviceId: runtime.serviceId,
+            issuerAllowed: subjectId => entrySubjectAllowed(subjectId),
+            targetAvailable: serviceId => routeAccess.hasConfiguredTarget(serviceId) && relayRouter.hasRoute(serviceId),
+        });
+    }).catch(() => console.error('Route invitations unavailable; uninitialized route grants remain denied.'));
+    void federation.catch(() => console.error('Encrypted access initialization failed; business access remains closed.'));
+    server.once('close', () => { void federation.then(runtime => runtime.close()).catch(() => { }); });
     server.headersTimeout = 10_000;
     server.requestTimeout = 120_000;
     server.keepAliveTimeout = 5_000;
@@ -464,14 +532,12 @@ export function startServer(options = {}) {
             zlibDeflateOptions: { level: 6, memLevel: 7 },
         },
     });
-    const WS_PATH_RE = /^\/api\/terminal\/([^/]+)\/ws$/;
-    const CONTROL_WS_PATH = '/api/control/ws';
     server.on('upgrade', (request, socket, head) => {
         if (wss.clients.size >= 256) {
             socket.end('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n');
             return;
         }
-        if (!isAllowedHost(request.headers.host) || !isUpgradeOriginAllowed(request.headers.origin, request.headers.host)) {
+        if (!isAllowedHost(request.headers.host)) {
             socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
             socket.destroy();
             return;
@@ -485,41 +551,38 @@ export function startServer(options = {}) {
             return;
         }
         const pathname = url.pathname;
-        // Reject the upgrade before the WebSocket handshake completes if auth
-        // is enabled and the client cookie is missing/expired. We respond with
-        // a real HTTP 401 so the browser surfaces a useful error. Applied to
-        // both per-terminal and control paths.
-        const cookieHeader = request.headers.cookie;
-        if (!isUpgradeRequestAuthenticated(typeof cookieHeader === 'string' ? cookieHeader : undefined)) {
-            socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
-            socket.destroy();
+        if (pathname === '/api/federation/relay') {
+            // Native relay peers have no Origin. Authenticate explicitly before upgrade.
+            if (scheme !== 'https' || (request.headers.origin && !isUpgradeOriginAllowed(request.headers.origin, request.headers.host))) {
+                socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+                return;
+            }
+            const principal = routeAccess.authenticate(request.headers.authorization, url.searchParams.get('routeToken'));
+            if (!principal) {
+                socket.end('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+                return;
+            }
+            wss.handleUpgrade(request, socket, head, ws => {
+                void relayRouter.attach(ws, principal).then(attached => { if (attached)
+                    ws.send(JSON.stringify({ type: 'ready' })); });
+            });
             return;
         }
-        // Control WS: server-pushed global client-state events. One per browser.
-        if (pathname === CONTROL_WS_PATH) {
-            const clientId = crypto.randomUUID();
+        if (pathname === '/api/federation/secure') {
+            // This exception applies only to the cookie-independent Noise handshake.
+            // Target pinning and device authorization remain mandatory inside it.
+            if (!secureChannelOriginAllowed(request.headers.origin, () => isUpgradeOriginAllowed(request.headers.origin, request.headers.host))) {
+                socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+                return;
+            }
             wss.handleUpgrade(request, socket, head, (ws) => {
-                handleControlWebSocket(ws, clientId);
-                guardWebSocketSession(ws, cookieHeader);
+                void federation.then(runtime => runtime.accept(ws, { allowOpenAccess: !!request.headers.origin && isUpgradeOriginAllowed(request.headers.origin, request.headers.host) })).catch(() => ws.close(1011, 'Encrypted access unavailable'));
             });
             return;
         }
-        // Per-terminal WS: bidirectional I/O for a single terminal session.
-        const match = pathname.match(WS_PATH_RE);
-        if (!match) {
-            socket.destroy();
-            return;
-        }
-        const sessionId = match[1];
-        const clientId = crypto.randomUUID();
-        const pushClientId = getCookieValue(cookieHeader, CLIENT_STATE_COOKIE);
-        // 短线重连时客户端会带上 ?since=<lastSeq>，让服务端只补发增量。
-        const sinceParam = url.searchParams.get('since');
-        const sinceSeq = sinceParam ? Math.max(0, Number.parseInt(sinceParam, 10) || 0) : 0;
-        wss.handleUpgrade(request, socket, head, (ws) => {
-            handleTerminalWebSocket(ws, sessionId, clientId, { sinceSeq, pushClientId, streamEpoch: url.searchParams.get('epoch') ?? undefined, flowControl: url.searchParams.get('flow') === '2', independentTmux: url.searchParams.get('transport') === 'tmux-client', outputActive: url.searchParams.get('active') !== '0' }, readTerminalHandshakeDimensions(url.searchParams));
-            guardWebSocketSession(ws, cookieHeader);
-        });
+        // Business WebSockets have no plaintext fallback after pairing migration.
+        socket.end('HTTP/1.1 426 Upgrade Required\r\nConnection: close\r\n\r\n');
+        return;
     });
     server.listen(port, host, () => {
         const displayHost = host === '0.0.0.0' ? 'localhost' : host;

package/dist/server/federation/accessPolicy.js

@@ -0,0 +1,122 @@
+const METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export function canonicalApiPath(path) {
+    if (typeof path !== 'string' || !path.startsWith('/api/') || /[\\\x00-\x20\x7f#]/.test(path))
+        return null;
+    const pathname = path.split('?')[0];
+    if (pathname.includes('//'))
+        return null;
+    try {
+        const segments = pathname.split('/').map((segment, index) => {
+            if (index === 0 || (segment === '' && index === pathname.split('/').length - 1))
+                return segment;
+            const value = decodeURIComponent(segment);
+            // Decode exactly once. Never allow an encoded separator, traversal segment,
+            // control byte, invalid UTF-8 or a second escape layer to change routing.
+            if (!value || value === '.' || value === '..' || /[\\/\x00-\x1f\x7f]/.test(value) || /%[a-f0-9]{2}/i.test(value))
+                throw new Error('Ambiguous API path');
+            return value;
+        });
+        const canonical = segments.join('/');
+        if (canonical.endsWith('/') && !canonical.startsWith('/api/terminal/fs/preview/'))
+            return null;
+        return canonical;
+    }
+    catch {
+        return null;
+    }
+}
+const pathOnly = canonicalApiPath;
+/** Restricts a full-service tunnel to business APIs, excluding authentication,
+ * local-only operations and recursive federation/bootstrap endpoints. */
+export function isBusinessApiPath(method, path) {
+    if (!METHODS.has(method))
+        return false;
+    const pathname = pathOnly(path);
+    if (!pathname)
+        return false;
+    return !/^\/api\/(?:auth|local|federation|onboarding|csrf)(?:\/|$)/i.test(pathname);
+}
+const fileReads = new Set(['list', 'watch', 'search', 'read', 'git-blob', 'eda-preview', 'eda-inspect', 'blob', 'video', 'download', 'diff', 'diff-files', 'untracked-files', 'git-context', 'git-bundle', 'change-audit', 'branch-diff', 'commit-diff', 'git-recent-commits', 'branch-audit', 'git-action/status', 'local-open-availability']);
+const filePosts = new Set(['git-action', 'apply-hunk', 'upload', 'open-in-file-browser']);
+const settings = new Set(['settings', 'toolbar-presets', 'program-detection', 'context-draft']);
+const serviceReads = new Set(['update', 'auto-title/catalog', 'agent-hooks', 'agent-launchers', 'agent-plugins', 'quota', 'tmux/status', 'tmux/sessions', 'agent-resume-history']);
+const reservedSessionIds = new Set(['fs', 'settings', 'client-state', 'session-inventory', 'operations', 'tmux', 'create', 'force-kill', 'serialize-state', 'agent-resume-history', 'toolbar-presets', 'context-draft', 'program-detection', 'update', 'quota', 'agent-hooks', 'agent-launchers', 'agent-plugins', 'agent-plugin-icon', 'auto-title', 'directory-suggestions']);
+export function resolveAccessRequest(method, path) {
+    if (!isBusinessApiPath(method, path))
+        return null;
+    const pathname = pathOnly(path);
+    const read = method === 'GET' || method === 'HEAD';
+    if (/^\/api\/notifications\/(status|subscribe|preferences|unsubscribe)$/.test(pathname)) {
+        if (read && pathname.endsWith('/status'))
+            return { action: 'service.view' };
+        if (method === 'POST' && !pathname.endsWith('/status'))
+            return { action: 'service.configure' };
+        return null;
+    }
+    const prefix = '/api/terminal/';
+    if (!pathname.startsWith(prefix))
+        return null;
+    const route = pathname.slice(prefix.length);
+    if (route.startsWith('fs/')) {
+        const op = route.slice(3);
+        if (read && (fileReads.has(op) || /^preview\/.+/.test(op)))
+            return { action: 'file.read' };
+        if ((method === 'POST' && filePosts.has(op)) || (method === 'DELETE' && ['file', 'change-audit', 'branch-audit'].includes(op)) || (method === 'GET' && op === 'cancel-slot'))
+            return { action: 'file.write' };
+        return null;
+    }
+    if (read && route === 'session-inventory')
+        return { action: 'service.view', metadata: 'session-inventory' };
+    if (read && route === 'client-state')
+        return { action: 'service.view', metadata: 'global-client-state' };
+    if (settings.has(route)) {
+        if (read)
+            return { action: 'service.view' };
+        if (method === 'PUT' || (method === 'DELETE' && route === 'program-detection'))
+            return { action: 'service.configure' };
+        return null;
+    }
+    if (read && serviceReads.has(route))
+        return { action: 'service.view' };
+    if (read && route === 'directory-suggestions')
+        return { action: 'file.read' };
+    if (method === 'POST' && route === 'create')
+        return { action: 'service.create-session' };
+    const session = /^([^/]+)(?:\/(health|attach|stream|input|resize|tmux|restart|agent-resume))?$/.exec(route);
+    if (session && !reservedSessionIds.has(session[1].toLowerCase())) {
+        const sessionId = session[1];
+        const op = session[2];
+        if (read && ['health', 'attach', 'stream', 'agent-resume'].includes(op))
+            return { action: 'session.view', sessionId };
+        if (method === 'POST' && op === 'input')
+            return { action: 'session.input', sessionId };
+        if (method === 'POST' && op === 'resize')
+            return { action: 'session.resize', sessionId };
+        if (method === 'DELETE' && !op)
+            return { action: 'session.terminate', sessionId };
+        // tmux switch-session can reach other backends; restart/agent-resume accept
+        // launch configuration. Their unrestricted bodies require service authority.
+        if (method === 'POST' && ['tmux', 'restart', 'agent-resume'].includes(op))
+            return { action: 'service.configure' };
+    }
+    // Complex operations manipulate global state or accept additional resource IDs.
+    // An unregistered operation intentionally receives no custom-grant mapping.
+    return null;
+}
+/** WS control mapping; caller must bind sessionId to the opened channel. */
+export function terminalMessageAction(type) {
+    switch (type) {
+        case 'input':
+        case 'focus':
+        case 'agent-review-ack': return 'session.input';
+        case 'resize': return 'session.resize';
+        case 'tmux': return 'service.configure';
+        case 'ping':
+        case 'viewing':
+        case 'output-subscription':
+        case 'output-ack': return 'session.view';
+        // Legacy flow-control can pause the shared PTY; grant only to controllers.
+        case 'flow-control': return 'session.input';
+        default: return null;
+    }
+}

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