@ai-workbench/connect 0.0.0-stage → 0.7.6

package/lib/components.js

@@ -0,0 +1,154 @@
+import { ComponentDownloadError } from "./component-download.js";
+import { L_DEFAULTS } from "./defaults.js";
+import { fail } from "./needs.js";
+import { employeeMessage } from "./startup.js";
+export function registerComponents(ctx, inventory, temporaryDataParent, component, sources, observationIntervalMs = L_DEFAULTS.componentObservationIntervalMs) {
+    const api = () => ctx.get('aiWorkbenchConnect');
+    const getState = () => {
+        const network = ctx.get('aiWorkbenchNetwork'), connect = api(), state = connect?.getState(), networkState = network?.getState();
+        return { workspaceBindings: connect?.getWorkspaceBindingState?.() ?? null, loginComponent: { temporaryDataParent: temporaryDataParent ?? null, download: component?.getState() ?? null, source: sources?.getState() ?? null, observationIntervalMs }, startup: connect?.getLoginPromptState?.() ?? null, inventory: inventory ?? null, network: { serviceProvided: !!network, phase: networkState?.phase ?? 'missing', needCode: networkState?.error?.code ?? networkState?.need?.code }, enrollment: connect?.getEnrollmentState?.() ?? null, connection: connect?.getConnectionState?.() ?? null, connect: { serviceProvided: !!connect, phase: state?.phase ?? 'missing', message: state?.need ? employeeMessage(state.need.code) : '连接服务等待就绪' }, codex: inventory ? { installed: !!inventory.codex, message: inventory.codex ? 'Codex 组件已安装' : 'Codex 组件未安装' } : { installed: null, message: '组件清单未装配' } };
+    };
+    ctx.provide('aiWorkbenchComponents', { getState });
+    ctx.inject(['webServer', 'connection'], host => {
+        const web = host.get('webServer'), connection = host.get('connection');
+        host.effect(() => {
+            const streams = new Set();
+            const off = web.register({ kind: 'prefix', path: '/ai-workbench-connect', handler: async (req, res) => {
+                    const rejected = connection.requestRejection(req);
+                    res.setHeader('Cache-Control', 'no-store');
+                    if (rejected !== undefined) {
+                        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+                        res.statusCode = rejected;
+                        res.end(JSON.stringify({ error: 'forbidden' }));
+                        return;
+                    }
+                    const path = new URL(req.url ?? '/', 'http://dsh').pathname, service = api();
+                    if (req.method === 'GET' && path === '/ai-workbench-connect/events' && service) {
+                        res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+                        res.statusCode = 200;
+                        let closed = false;
+                        let unprompt = () => { }, unconnection = () => { }, unenrollment = () => { }, unnative = () => { }, undownload = () => { }, unsource = () => { };
+                        const close = () => { if (closed)
+                            return; closed = true; unprompt(); unconnection(); unenrollment(); unnative(); undownload(); unsource(); streams.delete(close); res.end(); };
+                        const send = () => { if (closed)
+                            return; try {
+                            if (!res.write('data: ' + JSON.stringify(getState()) + '\n\n'))
+                                close();
+                        }
+                        catch {
+                            close();
+                        } };
+                        unprompt = service.onLoginPromptState(send);
+                        unconnection = service.onConnectionState(send);
+                        unenrollment = service.onEnrollmentState?.(send) ?? (() => { });
+                        unnative = service.onWorkspaceBindingState?.(send) ?? (() => { });
+                        undownload = component?.onState(send) ?? (() => { });
+                        unsource = sources?.onState(send) ?? (() => { });
+                        streams.add(close);
+                        res.once('close', close);
+                        send();
+                        return;
+                    }
+                    if (req.method === 'POST' && /^\/ai-workbench-connect\/component-download\/cancel\/[a-zA-Z0-9-]+$/.test(path) && component) {
+                        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+                        if (Number(req.headers?.['content-length'] ?? 0) > 0 || req.headers?.['transfer-encoding']) {
+                            res.statusCode = 400;
+                            res.end(JSON.stringify({ error: 'no-input-accepted' }));
+                            return;
+                        }
+                        const cancelled = component.cancel(path.split('/').at(-1));
+                        res.statusCode = cancelled ? 200 : 409;
+                        res.end(JSON.stringify({ ...getState(), ...(!cancelled ? { actionErrorCode: 'COMPONENT_DOWNLOAD_NOT_ACTIVE', actionError: '该组件下载已经结束或更新，请使用当前状态。' } : {}) }));
+                        return;
+                    }
+                    if (req.method === 'POST' && /^\/ai-workbench-connect\/component-source\/(github|npmmirror)$/.test(path) && sources) {
+                        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+                        if (Number(req.headers?.['content-length'] ?? 0) > 0 || req.headers?.['transfer-encoding']) {
+                            res.statusCode = 400;
+                            res.end(JSON.stringify({ error: 'no-input-accepted' }));
+                            return;
+                        }
+                        try {
+                            await sources.select(path.split('/').at(-1));
+                            res.statusCode = 200;
+                            res.end(JSON.stringify(getState()));
+                        }
+                        catch (e) {
+                            res.statusCode = 409;
+                            res.end(JSON.stringify({ ...getState(), actionErrorCode: e instanceof ComponentDownloadError ? e.message : 'COMPONENT_SOURCE_STATE_INVALID', actionError: '下载源未更改；请结束当前下载或授权后重选，或检查技术详情。' }));
+                        }
+                        return;
+                    }
+                    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+                    let actionError, actionErrorCode;
+                    if (req.method === 'POST' && service) {
+                        let result;
+                        if (path === '/ai-workbench-connect/enrollment/import') {
+                            if (Number(req.headers?.['content-length'] ?? 0) > 0 || req.headers?.['transfer-encoding']) {
+                                res.statusCode = 400;
+                                res.end(JSON.stringify({ error: 'no-input-accepted' }));
+                                return;
+                            }
+                            result = await service.importEnrollment();
+                        }
+                        else if (/^\/ai-workbench-connect\/workspace-notice\/[a-zA-Z0-9-]+\/displayed$/.test(path)) {
+                            if (Number(req.headers?.['content-length'] ?? 0) > 0 || req.headers?.['transfer-encoding']) {
+                                res.statusCode = 400;
+                                res.end(JSON.stringify({ error: 'no-input-accepted' }));
+                                return;
+                            }
+                            const id = /\/workspace-notice\/([a-zA-Z0-9-]+)\/displayed$/.exec(path)[1];
+                            result = await service.acknowledgeWorkspaceNotice({ noticeId: id, surface: 'settings', outcome: 'displayed' });
+                        }
+                        else if (path === '/ai-workbench-connect/check')
+                            result = await service.refreshLoginPrompts();
+                        else if (/^\/ai-workbench-connect\/start-login\/(claude|codex)\/[a-zA-Z0-9-]+\/\d+$/.test(path)) {
+                            const [, provider, instance, revision] = /\/start-login\/(claude|codex)\/([a-zA-Z0-9-]+)\/(\d+)$/.exec(path);
+                            const brand = provider, shown = service.getLoginPromptState(), before = service.getConnectionState();
+                            if (before.phase !== 'connected' || shown.instanceId !== instance || shown.revision !== Number(revision) || shown.phase === 'authorizing' || shown.logins[brand] !== false || shown.checkingProviders.includes(brand) || shown.providerNeeds[brand])
+                                result = fail('LOGIN_PROMPT_INVALID');
+                            else {
+                                const requested = await service.requestLoginPrompt(brand, 'user'), after = service.getConnectionState();
+                                if (after.phase !== 'connected' || after.instanceId !== before.instanceId || after.epoch !== before.epoch)
+                                    result = fail('LOGIN_PROMPT_INVALID');
+                                else if (!requested.ok)
+                                    result = requested;
+                                else if (requested.value.phase !== 'login-required' || requested.value.provider !== brand || !requested.value.requestId)
+                                    result = fail('LOGIN_PROMPT_INVALID');
+                                else
+                                    result = await service.respondLoginPrompt(requested.value.requestId, 'authorize');
+                            }
+                        }
+                        else if (/^\/ai-workbench-connect\/(request|authorize)\/(claude|codex)$/.test(path)) {
+                            const provider = /\/(claude|codex)$/.exec(path)[1];
+                            result = await service.requestLoginPrompt(provider, 'user');
+                        }
+                        else if (/^\/ai-workbench-connect\/respond\/[a-zA-Z0-9-]+\/(authorize|defer)$/.test(path)) {
+                            const [, id, action] = /\/respond\/([a-zA-Z0-9-]+)\/(authorize|defer)$/.exec(path);
+                            result = await service.respondLoginPrompt(id, action);
+                        }
+                        else {
+                            res.statusCode = 404;
+                            res.end(JSON.stringify({ error: 'not-found' }));
+                            return;
+                        }
+                        if (!result.ok) {
+                            res.statusCode = 409;
+                            actionErrorCode = result.error.code;
+                            actionError = result.error.code === 'LOGIN_PROMPT_INVALID' ? result.error.message : employeeMessage(result.error.code);
+                        }
+                    }
+                    else if (req.method !== 'GET' || path !== '/ai-workbench-connect/status') {
+                        res.statusCode = 404;
+                        res.end(JSON.stringify({ error: 'not-found' }));
+                        return;
+                    }
+                    if (!actionError)
+                        res.statusCode = 200;
+                    res.end(JSON.stringify({ ...getState(), ...(actionError ? { actionError, actionErrorCode } : {}) }));
+                } });
+            return () => { off(); for (const close of [...streams])
+                close(); };
+        });
+    });
+}

package/lib/connect.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectApi, ConnectState, Provider, ConnectionState, LoginPromptState, LoginPromptResult } from './api.ts';
+import type { Enrollment, Ports } from './ports.ts';
+export declare function validEnrollment(e: Enrollment): boolean;
+export interface ConnectOptions {
+    providers?: Provider[];
+    onConnectionState?: (s: ConnectionState) => void;
+    onPromptState?: (s: LoginPromptState) => void;
+    onPromptResult?: (r: LoginPromptResult) => void;
+}
+export declare function createConnect(ports: Ports, emit: (s: ConnectState) => void, options?: ConnectOptions): ConnectApi;

package/lib/connect.js

@@ -0,0 +1,246 @@
+import { randomUUID } from 'node:crypto';
+import { dependency, fail, ok, need } from "./needs.js";
+import { isProjectName } from "./projects.js";
+import { createStartup } from "./startup.js";
+import { parseLoginStatus } from "./auth-status.js";
+export function validEnrollment(e) {
+    return typeof e === 'object' && e !== null && typeof e.host === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9.-]*$/.test(e.host)
+        && typeof e.username === 'string' && /^emp-[a-z0-9][a-z0-9-]*$/.test(e.username)
+        && Number.isInteger(e.port) && e.port > 0 && e.port <= 65535
+        && e.session?.protocolVersion === 1 && [e.session.command, e.session.root, e.session.settingsPath].every(v => typeof v === 'string' && v.startsWith('/') && !/[\x00-\x1f\x7f]/.test(v))
+        && typeof e.knownHostsFile === 'string' && e.knownHostsFile.startsWith('/') && !/[\x00-\x1f\x7f]/.test(e.knownHostsFile)
+        && typeof e.projectRoot === 'string' && e.projectRoot.length > 0 && !/[\x00-\x1f\x7f]/.test(e.projectRoot);
+}
+export function createConnect(ports, emit, options = {}) {
+    let state = { phase: 'idle' }, generation = 0, disposed = false;
+    let flight;
+    const instanceId = randomUUID();
+    let connection = { instanceId, phase: 'unavailable', epoch: 0 };
+    const connectionListeners = new Set();
+    let startup;
+    const setConnection = (phase, need) => {
+        const next = { instanceId, phase, epoch: generation, ...(need ? { need } : {}) };
+        if (JSON.stringify(next) === JSON.stringify(connection))
+            return;
+        connection = structuredClone(next);
+        startup?.connectionChanged(next);
+        options.onConnectionState?.(structuredClone(next));
+        for (const listener of connectionListeners)
+            listener(structuredClone(next));
+    };
+    let controller = new AbortController();
+    const loginFlights = new Map();
+    const pending = new Set();
+    let disposal;
+    const track = (promise) => { pending.add(promise); void promise.then(() => pending.delete(promise), () => pending.delete(promise)); return promise; };
+    const publish = (s) => { state = structuredClone(s); emit(structuredClone(state)); };
+    const invalid = (g) => disposed ? fail('DISPOSED') : g !== generation ? fail('CONNECTION_LOST') : undefined;
+    const block = (r) => { if (!r.ok && !disposed) {
+        publish({ phase: 'blocked', need: r.error });
+        if (connection.phase !== 'connected')
+            setConnection('unavailable', r.error);
+    } return r; };
+    const transportBlock = (r) => { if (!r.ok && !disposed && connection.phase === 'connected') {
+        generation++;
+        controller.abort();
+        controller = new AbortController();
+        flight = undefined;
+        loginFlights.clear();
+    } const value = block(r); if (!r.ok && !disposed)
+        setConnection('unavailable', r.error); return value; };
+    const connect = () => {
+        if (disposed)
+            return Promise.resolve(fail('DISPOSED'));
+        if (state.target)
+            return Promise.resolve(ok(structuredClone(state.target)));
+        if (flight)
+            return flight;
+        const g = generation, signal = controller.signal;
+        if (connection.phase !== 'connected')
+            setConnection('connecting');
+        const run = async () => {
+            if (!ports.enrollment)
+                return transportBlock(dependency('S host-layout/enroll.json 适配器'));
+            if (!ports.network)
+                return transportBlock(dependency('N net-helper 生命周期/状态适配器'));
+            if (!ports.ssh)
+                return transportBlock(dependency('系统 SSH 适配器'));
+            try {
+                publish({ phase: 'enrolling' });
+                const e = await ports.enrollment.read(signal);
+                let stale = invalid(g);
+                if (stale)
+                    return stale;
+                if (!e.ok)
+                    return transportBlock(e);
+                if (!validEnrollment(e.value))
+                    return transportBlock(fail('ENROLLMENT_INVALID'));
+                publish({ phase: 'network' });
+                const n = await ports.network.connect(e.value, signal);
+                stale = invalid(g);
+                if (stale)
+                    return stale;
+                if (!n.ok)
+                    return transportBlock(n);
+                if (typeof n.value.proxyCommand !== 'string' || n.value.proxyCommand.length === 0 || /[\r\n\x00]/.test(n.value.proxyCommand))
+                    return transportBlock(dependency('有效的 N ProxyCommand'));
+                const { host, username, port, projectRoot, knownHostsFile, session, hostContext } = e.value;
+                const target = { host, username, port, projectRoot, knownHostsFile, session, ...(hostContext ? { hostContext } : {}), proxyCommand: n.value.proxyCommand };
+                publish({ phase: 'ssh' });
+                const verified = await ports.ssh.verify(target, signal);
+                stale = invalid(g);
+                if (stale)
+                    return stale;
+                if (!verified.ok)
+                    return transportBlock(verified);
+                publish({ phase: 'connected', target });
+                setConnection('connected');
+                return ok(structuredClone(target));
+            }
+            catch {
+                return invalid(g) ?? transportBlock(dependency('提供方调用失败，根因未查明；请检查 S/N/SSH 适配器'));
+            }
+        };
+        const promise = track(run());
+        flight = promise;
+        const clear = () => { if (flight === promise)
+            flight = undefined; };
+        void promise.then(clear, clear);
+        return promise;
+    };
+    const checkLogin = async (provider) => {
+        if (provider !== 'claude' && provider !== 'codex')
+            return fail('AUTH_STATUS_INVALID');
+        const g = generation;
+        const connected = await connect();
+        const staleConnection = invalid(g);
+        if (staleConnection)
+            return staleConnection;
+        if (!connected.ok)
+            return connected;
+        publish({ phase: 'checking-login', target: connected.value, provider });
+        try {
+            const raw = await ports.ssh.status(connected.value, provider, controller.signal);
+            const stale = invalid(g);
+            if (stale)
+                return stale;
+            const status = raw.ok ? parseLoginStatus(provider, raw.value) : raw;
+            if (!status.ok)
+                return ['network', 'ssh', 'enrollment'].includes(status.error.layer) ? transportBlock(status) : block(status);
+            publish(status.value.loggedIn ? { phase: 'ready', target: connected.value, provider } : { phase: 'connected', target: connected.value, provider });
+            return status;
+        }
+        catch {
+            return invalid(g) ?? block(fail('AUTH_STATUS_INVALID'));
+        }
+    };
+    const login = (provider) => {
+        if (provider !== 'claude' && provider !== 'codex')
+            return Promise.resolve(fail('LOGIN_FAILED'));
+        if (disposed)
+            return Promise.resolve(fail('DISPOSED'));
+        const prior = loginFlights.get(provider);
+        if (prior)
+            return prior;
+        const run = async () => {
+            const g = generation;
+            const connected = await connect();
+            const staleConnection = invalid(g);
+            if (staleConnection)
+                return staleConnection;
+            if (!connected.ok)
+                return connected;
+            if (!ports.login)
+                return block(dependency('Electron 登录助手及已确认设置'));
+            publish({ phase: 'login', target: connected.value, provider });
+            try {
+                const r = await ports.login.run(connected.value, provider, controller.signal);
+                const stale = invalid(g);
+                if (stale)
+                    return stale;
+                if (!r.ok)
+                    return ['network', 'ssh', 'enrollment'].includes(r.error.layer) ? transportBlock(r) : block(r);
+                const checked = await checkLogin(provider);
+                return checked.ok && !checked.value.loggedIn ? block(fail('LOGIN_FAILED')) : checked;
+            }
+            catch {
+                return invalid(g) ?? block(fail('LOGIN_FAILED'));
+            }
+        };
+        const promise = track(run());
+        loginFlights.set(provider, promise);
+        const clear = () => { if (loginFlights.get(provider) === promise)
+            loginFlights.delete(provider); };
+        void promise.then(clear, clear);
+        return promise;
+    };
+    const projectOperation = (operation, name) => track((async () => {
+        if (disposed)
+            return fail('DISPOSED');
+        if (operation === 'create' && !isProjectName(name))
+            return fail('PROJECT_NAME_INVALID');
+        const g = generation, connected = await connect();
+        const stale = invalid(g);
+        if (stale)
+            return stale;
+        if (!connected.ok)
+            return connected;
+        if (!ports.projects)
+            return dependency('L 主机项目接口适配器');
+        try {
+            const r = operation === 'list' ? await ports.projects.list(connected.value, controller.signal) : await ports.projects.create(connected.value, name, controller.signal);
+            return invalid(g) ?? r;
+        }
+        catch {
+            return invalid(g) ?? fail(operation === 'list' ? 'PROJECT_LIST_FAILED' : 'PROJECT_CREATE_FAILED');
+        }
+    })());
+    const unsubscribe = ports.network?.onState(event => {
+        if (disposed)
+            return;
+        if (event.kind === 'lost') {
+            generation++;
+            controller.abort();
+            controller = new AbortController();
+            flight = undefined;
+            loginFlights.clear();
+            block(fail('CONNECTION_LOST'));
+            setConnection('unavailable', need('CONNECTION_LOST'));
+        }
+        else {
+            void connect();
+        }
+    });
+    const operations = { getState: () => structuredClone(state), connect, checkLogin: provider => track(checkLogin(provider)), login };
+    startup = createStartup(operations, options.providers ?? ['codex', 'claude'], options.onPromptState, options.onPromptResult, instanceId);
+    return {
+        ...operations,
+        getContractInfo: () => ({ apiVersion: '0.7.0', status: 'implemented', workspaceBinding: 'native-local-v1' }),
+        getEnrollmentState: () => ({ instanceId, revision: 0, phase: 'blocked', need: need('DEPENDENCY_REQUIRED') }), onEnrollmentState: () => () => { },
+        importEnrollment: async () => dependency('官方profileContext与原生目录选择服务'),
+        getWorkspaceBindingState: () => ({ instanceId, revision: 0, items: [] }), onWorkspaceBindingState: () => () => { }, acknowledgeWorkspaceNotice: async () => dependency('官方工作区说明回执'), resolveSessionProject: async () => dependency('官方会话存储与L可信工作区关联'),
+        listProjects: () => projectOperation('list'), createProject: name => projectOperation('create', name), getSshTarget: connect,
+        getConnectionState: () => structuredClone(connection), onConnectionState: listener => { connectionListeners.add(listener); return () => { connectionListeners.delete(listener); }; },
+        getLoginPromptState: startup.getState, onLoginPromptState: startup.subscribe,
+        requestLoginPrompt: startup.request, respondLoginPrompt: startup.respond,
+        refreshLoginPrompts: async () => { await startup.check(); const s = startup.getState(); return s.phase === 'disposed' ? fail('DISPOSED') : s.phase === 'blocked' ? fail(s.technicalDetails.code ?? 'AUTH_STATUS_INVALID') : ok(s); },
+        login: async (provider) => { const request = await startup.request(provider, 'automatic'); if (!request.ok)
+            return request; return request.value.logins[provider] === true ? ok({ provider, loggedIn: true }) : fail('LOGIN_REQUIRED'); },
+        ensureReady: provider => track((async () => {
+            const g = generation;
+            const r = await checkLogin(provider);
+            const stale = invalid(g);
+            if (stale)
+                return stale;
+            if (!r.ok)
+                return r;
+            if (!r.value.loggedIn) {
+                const request = await startup.request(provider, 'automatic');
+                return invalid(g) ?? (!request.ok ? request : fail('LOGIN_REQUIRED'));
+            }
+            return connect();
+        })()),
+        dispose: () => { if (disposal)
+            return disposal; startup.stop(); disposed = true; generation++; controller.abort(); unsubscribe?.(); publish({ phase: 'disposed' }); setConnection('disposed'); connectionListeners.clear(); disposal = Promise.allSettled([...pending]).then(() => startup.dispose()); return disposal; },
+    };
+}

package/lib/cordis.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectApi, ConnectState, ConnectionState, LoginPromptState, LoginPromptResult, EnrollmentState, WorkspaceBindingState } from './api.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        aiWorkbenchConnect: ConnectApi;
+    }
+    interface Events {
+        'ai-workbench/enrollment-state': (state: EnrollmentState) => void;
+        'ai-workbench/workspace-binding-state': (state: WorkspaceBindingState) => void;
+        'ai-workbench/workspace-diagnostic': (error: unknown) => void;
+        'ai-workbench/connect-state': (state: ConnectState) => void;
+        'ai-workbench/connection-state': (state: ConnectionState) => void;
+        'ai-workbench/login-prompt-state': (state: LoginPromptState) => void;
+        'ai-workbench/login-prompt-result': (result: LoginPromptResult) => void;
+    }
+}

package/lib/cordis.js

@@ -0,0 +1 @@
+export {};

package/lib/defaults.d.ts

@@ -0,0 +1,30 @@
+export declare const L_DEFAULTS: Readonly<{
+    enrollmentMetadataMaxBytes: 1048576;
+    commandOutputMaxBytes: 1048576;
+    remoteKillGraceMs: 1000;
+    componentDownloadMaxRedirects: 3;
+    componentObservationIntervalMs: 1000;
+    maxDownloadBytes: 200000000;
+    maxExtractedBytes: 600000000;
+    loginOutputMaxBytes: 1048576;
+    ipcMaxBytes: 1048576;
+}>;
+export declare const ELECTRON_PIN: Readonly<{
+    source: "https://github.com/electron/electron/releases/download/v44.0.0/electron-v44.0.0-darwin-arm64.zip";
+    sha256: "076d79742986e1b100b69ebecc691cb07368045e54c9087cef631b8622b76a80";
+    executable: "Electron.app/Contents/MacOS/Electron";
+}>;
+export declare const NETWORK_DEFAULTS: Readonly<{
+    proxyListen: "127.0.0.1:0";
+    logUpload: false;
+    statusRefreshIntervalSeconds: 2;
+    dialTimeoutSeconds: 20;
+    headerTimeoutSeconds: 10;
+    enrollmentObservationSeconds: 30;
+    httpMaxHeaderBytes: 1048576;
+    httpMaxResponseHeaderBytes: 1048576;
+    startupObservationSeconds: 35;
+    shutdownObservationSeconds: 10;
+    controlResponseMaxBytes: 65536;
+    downloadMaxRedirects: 3;
+}>;

package/lib/defaults.js

@@ -0,0 +1,4 @@
+// Owner-approved technical settings (2026-10-20, part two). One source for schema and composition.
+export const L_DEFAULTS = Object.freeze({ enrollmentMetadataMaxBytes: 1048576, commandOutputMaxBytes: 1048576, remoteKillGraceMs: 1000, componentDownloadMaxRedirects: 3, componentObservationIntervalMs: 1000, maxDownloadBytes: 200000000, maxExtractedBytes: 600000000, loginOutputMaxBytes: 1048576, ipcMaxBytes: 1048576 });
+export const ELECTRON_PIN = Object.freeze({ source: 'https://github.com/electron/electron/releases/download/v44.0.0/electron-v44.0.0-darwin-arm64.zip', sha256: '076d79742986e1b100b69ebecc691cb07368045e54c9087cef631b8622b76a80', executable: 'Electron.app/Contents/MacOS/Electron' });
+export const NETWORK_DEFAULTS = Object.freeze({ proxyListen: '127.0.0.1:0', logUpload: false, statusRefreshIntervalSeconds: 2, dialTimeoutSeconds: 20, headerTimeoutSeconds: 10, enrollmentObservationSeconds: 30, httpMaxHeaderBytes: 1048576, httpMaxResponseHeaderBytes: 1048576, startupObservationSeconds: 35, shutdownObservationSeconds: 10, controlResponseMaxBytes: 65536, downloadMaxRedirects: 3 });

package/lib/electron.d.ts

@@ -0,0 +1,8 @@
+import type { LoginBoot, LoginWindow } from './login.ts';
+export interface ElectronLaunch {
+    executable: string;
+    entry: string;
+    cacheDir: string;
+    ipcMaxBytes: number;
+}
+export declare function launchElectron(settings: ElectronLaunch, boot: LoginBoot, onCode: (code: string) => Promise<void>, signal: AbortSignal): Promise<LoginWindow>;

package/lib/electron.js

@@ -0,0 +1,83 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { privateDirectory } from "./private-files.js";
+export async function launchElectron(settings, boot, onCode, signal) {
+    if (signal.aborted || !isAbsolute(settings.executable) || !isAbsolute(settings.entry) || !Number.isSafeInteger(settings.ipcMaxBytes) || settings.ipcMaxBytes < 1)
+        throw new Error('HELPER_SETTINGS_REQUIRED');
+    await privateDirectory(settings.cacheDir);
+    if (signal.aborted)
+        throw new Error('HELPER_CANCELLED');
+    const userDataDir = await mkdtemp(join(settings.cacheDir, 'session-'));
+    if (signal.aborted) {
+        await rm(userDataDir, { recursive: true });
+        throw new Error('HELPER_CANCELLED');
+    }
+    const child = spawn(settings.executable, [settings.entry], { shell: false, stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined, ELECTRON_ENABLE_LOGGING: undefined } });
+    let resolveReady = () => { }, rejectReady = () => { };
+    const ready = new Promise((yes, no) => { resolveReady = yes; rejectReady = no; });
+    let failed = false, line = '', size = 0;
+    const decoder = new StringDecoder('utf8');
+    const abort = () => { failed = true; child.kill('SIGTERM'); };
+    const close = () => { if (child.exitCode === null && child.signalCode === null && !child.stdin.destroyed) {
+        child.stdin.end(JSON.stringify({ type: 'close' }) + '\n');
+    } return closed; };
+    child.stdout.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > settings.ipcMaxBytes) {
+            abort();
+            return;
+        }
+        line += decoder.write(chunk);
+        const lines = line.split('\n');
+        line = lines.pop();
+        for (const value of lines) {
+            try {
+                const e = JSON.parse(value);
+                if (e.type === 'ready')
+                    resolveReady();
+                else if (e.type === 'claude-code' && boot.provider === 'claude' && typeof e.code === 'string')
+                    void onCode(e.code).catch(abort);
+                else if (e.type === 'closed') { /* process exit owns cleanup acknowledgement */ }
+                else
+                    abort();
+            }
+            catch {
+                abort();
+            }
+        }
+    });
+    // Chromium diagnostics are deliberately not forwarded to logs; failures use fixed public codes.
+    child.stderr.resume();
+    child.stdin.on('error', abort);
+    child.once('error', () => { failed = true; });
+    const closed = new Promise((yes, no) => child.once('close', async (code) => {
+        signal.removeEventListener('abort', abort);
+        rejectReady(new Error('HELPER_CLOSED'));
+        try {
+            await rm(userDataDir, { recursive: true });
+            if (failed || code !== 0)
+                no(new Error('HELPER_FAILED'));
+            else
+                yes();
+        }
+        catch {
+            no(new Error('HELPER_CLEANUP_FAILED'));
+        }
+    }));
+    // The child may fail before the caller receives its handle.
+    void closed.catch(() => { });
+    signal.addEventListener('abort', abort, { once: true });
+    child.stdin.write(JSON.stringify({ ...boot, userDataDir }) + '\n');
+    if (signal.aborted)
+        abort();
+    try {
+        await ready;
+        return { closed, close };
+    }
+    catch {
+        await closed.catch(() => { });
+        throw new Error('HELPER_FAILED');
+    }
+}

package/lib/enrollment.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from './api.ts';
+import type { Enrollment } from './ports.ts';
+export declare function readEnrollment(packageDir: string, trustDir: string, maxMetadataBytes?: number): Promise<Result<Enrollment>>;

package/lib/enrollment.js

@@ -0,0 +1,78 @@
+import { lstat, open, rename, rm } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fail, ok } from "./needs.js";
+import { privateDirectory, privateFile, readPrivate } from "./private-files.js";
+export async function readEnrollment(packageDir, trustDir, maxMetadataBytes) {
+    try {
+        if (!isAbsolute(packageDir) || !isAbsolute(trustDir))
+            return fail('ENROLLMENT_INVALID');
+        const dir = await lstat(packageDir);
+        if (!dir.isDirectory() || dir.isSymbolicLink() || dir.uid !== process.getuid() || (dir.mode & 0o077) !== 0)
+            return fail('ENROLLMENT_INVALID');
+        const wire = JSON.parse(await readPrivate(join(packageDir, 'enroll.json'), maxMetadataBytes));
+        if (wire.schemaVersion !== 1 || !/^emp-[a-z0-9][a-z0-9-]*$/.test(wire.employee?.username) || wire.employee.username.length > 32)
+            return fail('ENROLLMENT_INVALID');
+        const user = wire.employee.username, home = '/Users/' + user;
+        const rows = (v) => Array.isArray(v) && v.every(r => r && typeof r.id === 'string' && typeof r.status === 'string' && !/[\x00-\x1f\x7f]/.test(r.id + r.status));
+        if (!['production', 'test'].includes(wire.hostEnforcement) || wire.host?.enforcement !== wire.hostEnforcement || ![0, 1].includes(wire.checkExitCode) || !rows(wire.failedChecks) || !rows(wire.unverifiedChecks))
+            return fail('ENROLLMENT_INVALID');
+        const hasIssues = wire.failedChecks.length + wire.unverifiedChecks.length > 0;
+        if ((wire.checkExitCode === 0 && hasIssues) || (wire.checkExitCode === 1 && !hasIssues) || (wire.hostEnforcement === 'production' && (hasIssues || wire.checkExitCode !== 0)))
+            return fail('ENROLLMENT_INVALID');
+        const hostContext = { enforcement: wire.hostEnforcement, checkExitCode: wire.checkExitCode, failedChecks: wire.failedChecks.map(({ id, status }) => ({ id, status })), unverifiedChecks: wire.unverifiedChecks.map(({ id, status }) => ({ id, status })) };
+        if (wire.employee.home !== home || wire.employee.projectsRoot !== home + '/projects' || wire.employee.tag !== 'tag:aw-' + user || wire.host?.tag !== 'tag:aw-host' || !Number.isInteger(wire.host?.sshPort) || wire.host.sshPort < 1 || wire.host.sshPort > 65535 || !(/^[a-zA-Z0-9][a-zA-Z0-9.-]*$/).test(wire.host?.name))
+            return fail('ENROLLMENT_INVALID');
+        if (wire.session?.protocolVersion !== 1 || typeof wire.session.command !== 'string' || !wire.session.command.startsWith('/') || typeof wire.session.settingsPath !== 'string' || !wire.session.settingsPath.startsWith('/') || wire.session.root !== home + '/.aw/s' || [wire.session.command, wire.session.settingsPath].some((v) => /[\x00-\x1f\x7f]/.test(v)) || wire.authKeyDelivery?.mode !== 'file' || wire.authKeyDelivery.source !== 'administrator-stdin' || typeof wire.authKeyDelivery.path !== 'string' || !(/^[a-zA-Z0-9._-]+$/).test(wire.authKeyDelivery.path) || ['.', '..'].includes(wire.authKeyDelivery.path))
+            return fail('ENROLLMENT_INVALID');
+        // Metadata only. The enrollment secret is opened exclusively by N.
+        let authKeyFile = join(packageDir, wire.authKeyDelivery.path);
+        try {
+            await privateFile(authKeyFile);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                authKeyFile = undefined;
+            else
+                throw error;
+        }
+        const keys = wire.host.knownHosts;
+        if (!Array.isArray(keys) || keys.length === 0)
+            return fail('HOST_TRUST_REQUIRED');
+        if (keys.some((k) => typeof k !== 'string' || /[\r\n\x00]/.test(k) || !(/^(\S+) (ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp\d+|sk-ssh-ed25519@openssh.com) [A-Za-z0-9+/=]+(?: .*)?$/).test(k)))
+            return fail('HOST_TRUST_REQUIRED');
+        const expected = wire.host.sshPort === 22 ? wire.host.name : `[${wire.host.name}]:${wire.host.sshPort}`;
+        if (keys.some((k) => !k.split(' ')[0].split(',').includes(expected)))
+            return fail('HOST_TRUST_REQUIRED');
+        await privateDirectory(trustDir);
+        const destination = join(trustDir, 'known_hosts'), temp = join(trustDir, 'known_hosts-' + randomUUID());
+        // N holds this immutable handoff path; reopening must never replace its inode.
+        let exists = false;
+        try {
+            const cached = await readPrivate(destination, maxMetadataBytes);
+            if (cached !== keys.join('\n') + '\n')
+                return fail('HOST_KEY_MISMATCH');
+            exists = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (!exists) {
+            const file = await open(temp, 'wx', 0o600);
+            try {
+                await file.writeFile(keys.join('\n') + '\n');
+                await file.close();
+                await rename(temp, destination);
+            }
+            finally {
+                await file.close();
+                await rm(temp, { force: true });
+            }
+        }
+        return ok({ authKeyFile, hostContext, host: wire.host.name, username: user, port: wire.host.sshPort, projectRoot: wire.employee.projectsRoot, knownHostsFile: destination, session: { command: wire.session.command, root: wire.session.root, settingsPath: wire.session.settingsPath, protocolVersion: 1 } });
+    }
+    catch {
+        return fail('ENROLLMENT_INVALID');
+    }
+}