@ai-workbench/connect 0.0.0-stage → 0.7.6

package/lib/profile-enrollment.js

@@ -0,0 +1,275 @@
+import { lstat, realpath, open, rename, rm } from 'node:fs/promises';
+import { join, isAbsolute, resolve } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { readEnrollment } from "./enrollment.js";
+import { privateDirectory, privateFile, readPrivate } from "./private-files.js";
+import { ok, fail, need, NeedError } from "./needs.js";
+// Only metadata about authkey is examined here. Its contents belong exclusively to N.
+export function createProfileEnrollment(options) {
+    const instanceId = randomUUID(), listeners = new Set(), abort = new AbortController();
+    let state = { instanceId, revision: 0, phase: 'empty' }, record, loaded = false, disposed = false;
+    const pending = new Set();
+    let disposal;
+    let loadFlight, flight;
+    const dataDir = join(options.profileDir, 'ai-workbench-connect'), file = join(dataDir, 'enrollment.json'), trustDir = join(dataDir, 'trust');
+    const snapshot = () => structuredClone(state);
+    const publish = (phase, reason) => { if (disposed)
+        return; state = { instanceId, revision: state.revision + 1, phase, ...(reason ? { need: typeof reason === 'string' ? need(reason) : structuredClone(reason) } : {}) }; options.onState?.(snapshot()); for (const fn of listeners)
+        fn(snapshot()); };
+    const validOptions = () => isAbsolute(options.profileDir) && Number.isSafeInteger(options.metadataMaxBytes) && options.metadataMaxBytes > 0 && options.metadataMaxBytes <= 2147483647;
+    const canonical = async (path) => { if (!isAbsolute(path) || await realpath(path) !== resolve(path))
+        throw Error('NON_CANONICAL_DIRECTORY'); };
+    const sourceFile = async (path) => { await privateFile(path); const stat = await lstat(path); if ((stat.mode & 0o777) !== 0o600 || stat.nlink !== 1)
+        throw Error('SOURCE_FILE_INVALID'); return stat; };
+    async function load() {
+        if (disposed)
+            return fail('DISPOSED');
+        if (loaded)
+            return ok(undefined);
+        if (loadFlight)
+            return loadFlight;
+        loadFlight = (async () => {
+            try {
+                if (!validOptions())
+                    return fail('SETTINGS_REQUIRED');
+                await canonical(options.profileDir);
+                try {
+                    await lstat(dataDir);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT') {
+                        if (disposed)
+                            return fail('DISPOSED');
+                        loaded = true;
+                        return ok(undefined);
+                    }
+                    throw error;
+                }
+                await privateDirectory(dataDir);
+                await canonical(dataDir);
+                try {
+                    const value = JSON.parse(await readPrivate(file, options.metadataMaxBytes));
+                    if (value.schemaVersion !== 1 || typeof value.requestId !== 'string' || !value.requestId || typeof value.source !== 'string' || !/^[a-f0-9]{64}$/.test(value.digest) || !['host', 'username', 'projectRoot'].every(k => typeof value[k] === 'string') || !Number.isInteger(value.port))
+                        throw Error('REGISTRATION_INVALID');
+                    record = value;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                if (disposed)
+                    return fail('DISPOSED');
+                loaded = true;
+                if (record)
+                    publish('imported');
+                return ok(undefined);
+            }
+            catch {
+                publish('blocked', 'ENROLLMENT_INVALID');
+                return fail('ENROLLMENT_INVALID');
+            }
+        })();
+        const result = await loadFlight;
+        if (!result.ok)
+            loadFlight = undefined;
+        return result;
+    }
+    async function validate(source) {
+        try {
+            await canonical(source);
+            const d = await lstat(source);
+            if (!d.isDirectory() || d.uid !== process.getuid() || (d.mode & 0o777) !== 0o700)
+                return fail('ENROLLMENT_INVALID');
+            await sourceFile(join(source, 'enroll.json'));
+            const metadata = await readPrivate(join(source, 'enroll.json'), options.metadataMaxBytes);
+            const rule = await sourceFile(join(source, 'ssh-rule.json'));
+            if (rule.size > options.metadataMaxBytes)
+                return fail('ENROLLMENT_INVALID');
+            const value = JSON.parse(metadata), keyName = value.authKeyDelivery?.path;
+            if (typeof keyName !== 'string' || !(/^[a-zA-Z0-9._-]+$/).test(keyName) || ['.', '..'].includes(keyName))
+                return fail('ENROLLMENT_INVALID');
+            const key = join(source, keyName);
+            try {
+                if ((await sourceFile(key)).size === 0)
+                    return fail('ENROLLMENT_REQUIRED');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT' || !record || !options.activate)
+                    return fail(error.code === 'ENOENT' ? 'ENROLLMENT_REQUIRED' : 'ENROLLMENT_INVALID');
+            }
+            // Validate the source digest before replacing our trust cache on an existing registration.
+            const digest = createHash('sha256').update(metadata).digest('hex');
+            if (record && (record.source !== source || record.digest !== digest))
+                return fail('ENROLLMENT_INVALID');
+            if (disposed)
+                return fail('DISPOSED');
+            await privateDirectory(dataDir);
+            await canonical(dataDir);
+            if (disposed)
+                return fail('DISPOSED');
+            const normalized = await readEnrollment(source, trustDir, options.metadataMaxBytes);
+            if (!normalized.ok)
+                return normalized;
+            if (await readPrivate(join(source, 'enroll.json'), options.metadataMaxBytes) !== metadata)
+                return fail('ENROLLMENT_INVALID');
+            await canonical(source);
+            const { host, username, port, projectRoot } = normalized.value;
+            return ok({ enrollment: normalized.value, registration: { schemaVersion: 1, requestId: record?.requestId ?? randomUUID(), source, digest, host, username, port, projectRoot } });
+        }
+        catch {
+            return fail('ENROLLMENT_INVALID');
+        }
+    }
+    return {
+        getState: snapshot,
+        onState(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; },
+        read() {
+            const promise = (async () => {
+                if (disposed)
+                    return fail('DISPOSED');
+                const ready = await load();
+                if (disposed)
+                    return fail('DISPOSED');
+                if (!ready.ok)
+                    return ready;
+                if (!record)
+                    return fail('ENROLLMENT_REQUIRED');
+                if (!options.activate)
+                    return fail('DEPENDENCY_REQUIRED');
+                const result = await validate(record.source);
+                if (disposed)
+                    return fail('DISPOSED');
+                if (!result.ok) {
+                    publish('blocked', result.error.code);
+                    return result;
+                }
+                if (!options.activate)
+                    return fail('DEPENDENCY_REQUIRED');
+                const activated = await options.activate(result.value.enrollment, abort.signal);
+                if (disposed)
+                    return fail('DISPOSED');
+                if (!activated.ok) {
+                    publish('blocked', activated.error.code);
+                    return activated;
+                }
+                if (state.phase !== 'imported' || state.need)
+                    publish('imported');
+                return ok(result.value.enrollment);
+            })();
+            pending.add(promise);
+            void promise.then(() => pending.delete(promise), () => pending.delete(promise));
+            return promise;
+        },
+        importEnrollment() {
+            if (disposed)
+                return Promise.resolve(fail('DISPOSED'));
+            if (flight)
+                return flight;
+            const run = async () => {
+                const ready = await load();
+                if (disposed)
+                    return fail('DISPOSED');
+                if (!ready.ok)
+                    return ready;
+                const blocked = options.blockedByNetwork?.();
+                if (blocked) {
+                    publish('blocked', blocked.code);
+                    return fail(blocked.code);
+                }
+                if (options.active?.())
+                    return fail('ENROLLMENT_INVALID');
+                const previous = record ? 'imported' : 'empty';
+                publish('importing');
+                let temp;
+                try {
+                    const source = await options.pick(abort.signal);
+                    if (disposed)
+                        return fail('DISPOSED');
+                    if (source === null) {
+                        publish(previous);
+                        return ok({ outcome: 'cancelled', state: snapshot() });
+                    }
+                    const blocked = options.blockedByNetwork?.();
+                    if (blocked) {
+                        publish('blocked', blocked.code);
+                        return fail(blocked.code);
+                    }
+                    if (options.active?.()) {
+                        publish('blocked', 'ENROLLMENT_INVALID');
+                        return fail('ENROLLMENT_INVALID');
+                    }
+                    const result = await validate(source);
+                    if (!result.ok) {
+                        publish('blocked', result.error.code);
+                        return result;
+                    }
+                    if (disposed)
+                        return fail('DISPOSED');
+                    const bytes = JSON.stringify(result.value.registration) + '\n';
+                    if (Buffer.byteLength(bytes) > options.metadataMaxBytes) {
+                        publish('blocked', 'ENROLLMENT_INVALID');
+                        return fail('ENROLLMENT_INVALID');
+                    }
+                    temp = join(dataDir, '.enrollment-' + randomUUID());
+                    const handle = await open(temp, 'wx', 0o600);
+                    try {
+                        if (disposed)
+                            return fail('DISPOSED');
+                        await handle.writeFile(bytes);
+                        if (disposed)
+                            return fail('DISPOSED');
+                        await handle.sync();
+                    }
+                    finally {
+                        await handle.close();
+                    }
+                    if (disposed)
+                        return fail('DISPOSED');
+                    await rename(temp, file);
+                    temp = undefined;
+                    const directory = await open(dataDir, 'r');
+                    try {
+                        await directory.sync();
+                    }
+                    finally {
+                        await directory.close();
+                    }
+                    if (disposed)
+                        return fail('DISPOSED');
+                    record = result.value.registration;
+                    if (!options.activate) {
+                        publish('blocked', 'DEPENDENCY_REQUIRED');
+                        return fail('DEPENDENCY_REQUIRED');
+                    }
+                    const activated = await options.activate(result.value.enrollment, abort.signal);
+                    if (disposed)
+                        return fail('DISPOSED');
+                    if (!activated.ok) {
+                        publish('blocked', activated.error.code);
+                        return activated;
+                    }
+                    publish('imported');
+                    return ok({ outcome: 'imported', state: snapshot() });
+                }
+                catch (error) {
+                    if (disposed)
+                        return fail('DISPOSED');
+                    const reason = error instanceof NeedError ? structuredClone(error.need) : need('ENROLLMENT_INVALID');
+                    publish('blocked', reason);
+                    return { ok: false, error: reason };
+                }
+                finally {
+                    if (temp)
+                        await rm(temp, { force: true });
+                }
+            };
+            const promise = run();
+            flight = promise;
+            void promise.finally(() => { if (flight === promise)
+                flight = undefined; }).catch(() => { });
+            return promise;
+        },
+        dispose() { if (disposal)
+            return disposal; disposed = true; abort.abort(); listeners.clear(); disposal = Promise.allSettled([...pending, ...(flight ? [flight] : []), ...(loadFlight ? [loadFlight] : [])]).then(() => { }); return disposal; },
+    };
+}

package/lib/profile-runtime.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ConnectApi } from './api.ts';
+import type { Ports } from './ports.ts';
+import type { Config } from './index.ts';
+import type { NetworkProvider } from './provider.ts';
+export declare function attachProfileRuntime(ctx: Context, api: ConnectApi, ports: Ports, config: Config, network?: NetworkProvider): void;

package/lib/profile-runtime.js

@@ -0,0 +1,47 @@
+import { mapNetworkNeed } from "./provider.js";
+import { createProfileEnrollment } from "./profile-enrollment.js";
+import { createWorkspaceBindings } from "./workspace-bindings.js";
+import { NeedError, need, fail } from "./needs.js";
+import { createNativeImportPicker } from "./native-import-picker.js";
+import { L_DEFAULTS } from "./defaults.js";
+import { createProfileActivation } from "./profile-activation.js";
+// Composition only: consume official services; never provide replacements or alter default entries.
+export function attachProfileRuntime(ctx, api, ports, config, network) {
+    const profile = ctx.get('profileContext');
+    if (!profile || typeof profile.dir !== 'string')
+        return;
+    const activation = createProfileActivation({ profileDir: profile.dir, metadataMaxBytes: config.enrollmentMetadataMaxBytes ?? L_DEFAULTS.enrollmentMetadataMaxBytes, network, settings: config.network });
+    const manager = createProfileEnrollment({ profileDir: profile.dir, metadataMaxBytes: config.enrollmentMetadataMaxBytes ?? L_DEFAULTS.enrollmentMetadataMaxBytes,
+        pick: createNativeImportPicker(() => ctx.get('directoryPicker')),
+        blockedByNetwork: () => { const error = network?.getState().error; return error && ['ENROLLMENT_RESULT_UNKNOWN', 'ENROLLMENT_REJECTED', 'LOCAL_STATE_INVALID', 'ALREADY_RUNNING'].includes(error.code) ? mapNetworkNeed(error) : undefined; },
+        activate: activation.activate, onState: state => ctx.emit('ai-workbench/enrollment-state', state) });
+    ports.enrollment = { read: () => manager.read() };
+    api.getEnrollmentState = manager.getState;
+    api.onEnrollmentState = manager.onState;
+    api.importEnrollment = async () => { const result = await manager.importEnrollment(); if (result.ok && result.value.outcome === 'imported')
+        await api.refreshLoginPrompts(); return result; };
+    ctx.effect(() => () => manager.dispose());
+    let workspaceRevision = 0;
+    let lastWorkspaceError;
+    ctx.provide('aiWorkbenchWorkspaceDiagnostics', { getLatest: () => lastWorkspaceError });
+    ctx.inject(['workspaceRegistry', 'sessions', 'sessionPersistence'], native => {
+        const registry = native.get('workspaceRegistry');
+        const bindings = createWorkspaceBindings({ profileDir: profile.dir, metadataMaxBytes: config.enrollmentMetadataMaxBytes ?? L_DEFAULTS.enrollmentMetadataMaxBytes, api, registry,
+            readHeader: async (id) => {
+                const live = native.get('sessions');
+                const session = live?.get(id);
+                if (session)
+                    return session.header;
+                const persistence = native.get('sessionPersistence');
+                if (!persistence)
+                    throw new NeedError(need('DEPENDENCY_REQUIRED'));
+                return (await persistence.list()).find(s => s.header.id === id)?.header;
+            }, nextRevision: () => ++workspaceRevision, onState: state => ctx.emit('ai-workbench/workspace-binding-state', state), diagnostic: error => { lastWorkspaceError = error; ctx.emit('ai-workbench/workspace-diagnostic', error); } });
+        native.effect(() => api.onConnectionState(bindings.observeConnection));
+        api.getWorkspaceBindingState = bindings.getWorkspaceBindingState;
+        api.onWorkspaceBindingState = bindings.onWorkspaceBindingState;
+        api.acknowledgeWorkspaceNotice = bindings.acknowledgeWorkspaceNotice;
+        api.resolveSessionProject = bindings.resolveSessionProject;
+        native.effect(() => () => { api.resolveSessionProject = async () => fail('DEPENDENCY_REQUIRED'); api.acknowledgeWorkspaceNotice = async () => fail('DEPENDENCY_REQUIRED'); return bindings.dispose(); });
+    });
+}

package/lib/profile-settings.d.ts

@@ -0,0 +1,2 @@
+import type { Config } from './index.ts';
+export declare function profileSettings(config: Config, profileDir?: string, platform?: string, arch?: string): Config;

package/lib/profile-settings.js

@@ -0,0 +1,13 @@
+import { isAbsolute, join } from 'node:path';
+import { COMPONENT_SOURCES, preset } from "./component-source.js";
+import { L_DEFAULTS, ELECTRON_PIN } from "./defaults.js";
+// Owner approved technical values, 2026-10-20 settings decision, part two.
+// 组件直接来自自己的官方地址；OAuth网页仍通过N主机出口。
+export function profileSettings(config, profileDir, platform = process.platform, arch = process.arch) {
+    if (typeof profileDir !== 'string' || !isAbsolute(profileDir))
+        return config;
+    const runtime = platform === 'darwin' && arch === 'arm64' ? { ...ELECTRON_PIN, source: COMPONENT_SOURCES.npmmirror.source } : {};
+    const chosen = config.helper?.componentDownloadSource;
+    const selected = chosen === undefined ? {} : { source: preset(chosen) ? COMPONENT_SOURCES[chosen].source : '' };
+    return { ...config, commandOutputMaxBytes: config.commandOutputMaxBytes === undefined ? L_DEFAULTS.commandOutputMaxBytes : config.commandOutputMaxBytes, helper: { ...runtime, componentDownloadMaxRedirects: L_DEFAULTS.componentDownloadMaxRedirects, componentObservationIntervalMs: L_DEFAULTS.componentObservationIntervalMs, maxDownloadBytes: L_DEFAULTS.maxDownloadBytes, maxExtractedBytes: L_DEFAULTS.maxExtractedBytes, loginOutputMaxBytes: L_DEFAULTS.loginOutputMaxBytes, ipcMaxBytes: L_DEFAULTS.ipcMaxBytes, remoteKillGraceMs: L_DEFAULTS.remoteKillGraceMs, ...config.helper, ...selected, cacheDir: config.helper?.cacheDir === undefined ? join(profileDir, 'ai-workbench-connect', 'login-component-cache') : config.helper.cacheDir } };
+}

package/lib/projects.d.ts

@@ -0,0 +1,4 @@
+import type { Ports } from './ports.ts';
+import type { Runner } from './ssh.ts';
+export declare function isProjectName(name: string): boolean;
+export declare function createProjects(runner: Runner): NonNullable<Ports['projects']>;

package/lib/projects.js

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { runRemote } from "./ssh.js";
+import { fail, ok } from "./needs.js";
+export function isProjectName(name) { return typeof name === 'string' && name !== '' && name !== '.' && name !== '..' && !/[\\/\x00-\x1f\x7f]/.test(name); }
+const codes = ['PROJECT_ROOT_INVALID', 'PROJECT_EXISTS', 'PROJECT_INIT_FAILED', 'PROJECT_CREATE_FAILED', 'PROJECT_LIST_FAILED', 'PROJECT_NAME_INVALID'];
+const reasons = new Set(['invalid-name', 'symlink', 'not-directory', 'permissions', 'not-git', 'invalid-git', 'outside-root']);
+function validProject(value, root) {
+    return typeof value === 'object' && value !== null && 'name' in value && typeof value.name === 'string' && isProjectName(value.name) && 'path' in value && value.path === root + '/' + value.name;
+}
+export function createProjects(runner) {
+    const request = async (t, operation, signal, name) => {
+        if (operation === 'create' && !isProjectName(name))
+            return fail('PROJECT_NAME_INVALID');
+        try {
+            const source = await readFile(new URL('../helper/projects.cjs', import.meta.url), 'utf8');
+            const command = 'node -e ' + "'" + (source + '\nmain();').replaceAll("'", "'\\''") + "'";
+            const raw = await runRemote(runner, t, command, signal, JSON.stringify({ protocolVersion: 1, operation, root: t.projectRoot, ...(operation === 'create' ? { name } : {}) }));
+            if (signal.aborted)
+                return fail('CONNECTION_LOST');
+            if (raw.exitCode !== 0)
+                return fail(operation === 'list' ? 'PROJECT_LIST_FAILED' : 'PROJECT_CREATE_FAILED');
+            const result = JSON.parse(raw.stdout);
+            if (result.protocolVersion !== 1 || typeof result.ok !== 'boolean')
+                return fail('PROJECT_PROTOCOL_INVALID');
+            if (!result.ok) {
+                const code = codes.find(code => code === result.error?.code);
+                return fail(code ?? 'PROJECT_PROTOCOL_INVALID');
+            }
+            if (operation === 'create')
+                return validProject(result.value, t.projectRoot) && result.value.name === name ? ok(result.value) : fail('PROJECT_PROTOCOL_INVALID');
+            const list = result.value;
+            if (!list || !Array.isArray(list.projects) || !Array.isArray(list.unavailable) || !list.projects.every((p) => validProject(p, t.projectRoot)) || !list.unavailable.every((p) => p && typeof p.name === 'string' && reasons.has(p.reason)))
+                return fail('PROJECT_PROTOCOL_INVALID');
+            return ok(list);
+        }
+        catch {
+            return fail(operation === 'list' ? 'PROJECT_LIST_FAILED' : 'PROJECT_CREATE_FAILED');
+        }
+    };
+    return { list: (t, s) => request(t, 'list', s), create: (t, n, s) => request(t, 'create', s, n) };
+}

package/lib/provider.d.ts

@@ -0,0 +1,73 @@
+import type { Ports } from './ports.ts';
+import type { ProxyLease } from './login.ts';
+interface NNeed {
+    code: string;
+}
+type NResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: NNeed;
+};
+export interface ActivationSettings {
+    configFile: string;
+    helperLogFile: string;
+    startupObservationSeconds: number;
+    shutdownObservationSeconds: number;
+    controlResponseMaxBytes: number;
+    downloadMaxRedirects: number;
+}
+export interface ActivationState {
+    instanceId: string;
+    revision: number;
+    phase: 'unconfigured' | 'activating' | 'active' | 'blocked' | 'stopped';
+    receipt: {
+        apiVersion: 1;
+        session: 'key' | 'identity';
+        key: 'not-required' | 'unattempted' | 'attempted' | 'confirmed' | 'unknown';
+        identity: 'unconfirmed' | 'resumable';
+        cleanup: 'not-required' | 'pending' | 'complete';
+    } | null;
+    error: NNeed | null;
+}
+export interface NetworkProvider {
+    activate?(settings: ActivationSettings, signal: AbortSignal): Promise<NResult<ActivationState>>;
+    getActivationState?(): ActivationState;
+    onActivationState?(listener: (state: ActivationState) => void): () => void;
+    getState(): {
+        phase: string;
+        error?: NNeed;
+        status?: {
+            host: {
+                lastSeenAt: string | null;
+            };
+        };
+    };
+    connect(target: {
+        host: string;
+        username: string;
+        port: number;
+        knownHostsFile: string;
+    }, signal: AbortSignal): Promise<NResult<{
+        proxyCommand: string;
+    }>>;
+    onState(listener: (event: {
+        kind: 'lost' | 'restored';
+    }) => void): () => void;
+    openLoginProxy(signal: AbortSignal): Promise<NResult<{
+        credentials: {
+            url: string;
+            username: string;
+            password: string;
+        };
+        release(): Promise<void>;
+    }>>;
+    download(source: string, signal: AbortSignal): Promise<NResult<Response>>;
+}
+export declare function mapNetworkNeed(value: NNeed): import("./api.ts").ConnectNeed;
+export declare function adaptNetwork(provider: NetworkProvider): NonNullable<Ports['network']> & {
+    acquireProxy(signal: AbortSignal): Promise<ProxyLease>;
+    download(source: string, signal: AbortSignal): Promise<Response>;
+};
+export {};

package/lib/provider.js

@@ -0,0 +1,39 @@
+import { NeedError, need } from "./needs.js";
+export function mapNetworkNeed(value) {
+    const code = { NEED_ENROLLMENT: 'ENROLLMENT_REQUIRED', ENROLLMENT_REJECTED: 'ENROLLMENT_REJECTED', ENROLLMENT_RESULT_UNKNOWN: 'ENROLLMENT_RESULT_UNKNOWN', LOCAL_STATE_INVALID: 'ENROLLMENT_INVALID', HOST_OFFLINE: 'HOST_OFFLINE', HOST_TRUST_REQUIRED: 'HOST_TRUST_REQUIRED', HOST_KEY_MISMATCH: 'HOST_KEY_MISMATCH', ENROLLMENT_MISMATCH: 'ENROLLMENT_INVALID', CONFIG_INVALID: 'SETTINGS_REQUIRED', SETTINGS_REQUIRED: 'SETTINGS_REQUIRED', SSH_FAILED: 'SSH_FAILED', NETWORK_INTERRUPTED: 'CONNECTION_LOST', CONTROL_UNAVAILABLE: 'CONNECTION_LOST', NETWORK_NOT_READY: 'CONNECTION_LOST', DISPOSED: 'DISPOSED' }[value.code] ?? 'DEPENDENCY_REQUIRED';
+    const direct = ['ACTIVATION_CONFLICT', 'ACTIVATION_CANCELLED', 'ENROLLMENT_CLEANUP_UNBOUND', 'ENROLLMENT_CLEANUP_FAILED', 'ENROLLMENT_MISMATCH', 'LOCAL_STATE_INVALID', 'ALREADY_RUNNING', 'ENROLLMENT_RECEIPT_REQUIRED', 'CONTROL_PROTOCOL_INVALID', 'HELPER_HANDOFF_FAILED', 'HELPER_SHUTDOWN_FORCED'];
+    const result = need(direct.includes(value.code) ? value.code : code);
+    result.officialReason = /^[A-Z][A-Z0-9_]*$/.test(value.code) ? value.code : 'NETWORK_NEED_INVALID';
+    return result;
+}
+export function adaptNetwork(provider) {
+    return {
+        async connect(e, signal) {
+            const result = await provider.connect({ host: e.host, username: e.username, port: e.port, knownHostsFile: e.knownHostsFile }, signal);
+            if (result.ok)
+                return result;
+            const error = mapNetworkNeed(result.error), lastSeen = provider.getState().status?.host.lastSeenAt;
+            if (error.code === 'HOST_OFFLINE' && typeof lastSeen === 'string' && !Number.isNaN(Date.parse(lastSeen)))
+                error.lastSeen = lastSeen;
+            return { ok: false, error };
+        },
+        onState(listener) { return provider.onState(event => { if (event.kind === 'lost' || event.kind === 'restored')
+            listener({ kind: event.kind }); }); },
+        async acquireProxy(signal) {
+            const result = await provider.openLoginProxy(signal);
+            if (!result.ok)
+                throw new NeedError(mapNetworkNeed(result.error));
+            const source = result.value, credentials = source.credentials;
+            let release;
+            return { url: credentials.url, get username() { return credentials.username; }, get password() { return credentials.password; }, release: () => release ??= (async () => { try {
+                    await source.release();
+                }
+                finally {
+                    credentials.username = '';
+                    credentials.password = '';
+                } })() };
+        },
+        async download(source, signal) { const result = await provider.download(source, signal); if (!result.ok)
+            throw new NeedError(mapNetworkNeed(result.error)); return result.value; },
+    };
+}

package/lib/remote-login.d.ts

@@ -0,0 +1,2 @@
+import type { Provider } from './api.ts';
+export declare function remoteLoginCommand(provider: Provider, killGraceMs: number, probeIsolate?: boolean): string;

package/lib/remote-login.js

@@ -0,0 +1,9 @@
+import { readFileSync } from 'node:fs';
+export function remoteLoginCommand(provider, killGraceMs, probeIsolate = false) {
+    if (provider !== 'claude' && provider !== 'codex')
+        throw Error('LOGIN_PROVIDER_INVALID');
+    if (!Number.isSafeInteger(killGraceMs) || killGraceMs < 0 || killGraceMs > 2147483647)
+        throw Error('REMOTE_KILL_GRACE_REQUIRED');
+    const source = readFileSync(new URL('../helper/remote-login.cjs', import.meta.url), 'utf8');
+    return "node -e '" + source.replaceAll("'", "'\\''") + "' -- " + provider + ' ' + killGraceMs + (probeIsolate ? ' --probe-isolate' : '');
+}

package/lib/ssh.d.ts

@@ -0,0 +1,10 @@
+import type { SshTarget } from './api.ts';
+import type { CommandResult, Ports } from './ports.ts';
+export declare function shellQuote(s: string): string;
+export declare function proxyCommand(binary: string, runtimeDir: string): string;
+export declare function sshArgs(t: SshTarget): string[];
+export interface Runner {
+    run(cmd: string, args: string[], signal: AbortSignal, input?: string): Promise<CommandResult>;
+}
+export declare function runRemote(runner: Runner, t: SshTarget, command: string, signal: AbortSignal, input?: string): Promise<CommandResult>;
+export declare function createSsh(runner: Runner, maxOutputBytes?: number): NonNullable<Ports['ssh']>;

package/lib/ssh.js

@@ -0,0 +1,78 @@
+import { readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { fail, ok } from "./needs.js";
+export function shellQuote(s) {
+    if (/[\x00-\x1f\x7f%]/.test(s))
+        throw new Error('INVALID_PROXY_PATH');
+    return "'" + s.replaceAll("'", "'\\''") + "'";
+}
+export function proxyCommand(binary, runtimeDir) {
+    if (!binary.startsWith('/') || !runtimeDir.startsWith('/'))
+        throw new Error('ABSOLUTE_PROXY_PATH_REQUIRED');
+    return `${shellQuote(binary)} ssh-proxy --runtime-dir ${shellQuote(runtimeDir)} %h %p`;
+}
+export function sshArgs(t) {
+    return ['-F', '/dev/null', '-T', '-o', 'IdentityAgent=none', '-o', 'PubkeyAuthentication=no', '-o', 'PasswordAuthentication=no', '-o', 'KbdInteractiveAuthentication=no', '-o', 'PreferredAuthentications=none', '-o', 'UpdateHostKeys=no', '-o', 'CanonicalizeHostname=no', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'GlobalKnownHostsFile=/dev/null', '-o', 'UserKnownHostsFile=' + JSON.stringify(t.knownHostsFile.replaceAll('%', '%%')), '-o', 'ProxyCommand=' + t.proxyCommand, '-p', String(t.port), '-l', t.username, t.host];
+}
+export async function runRemote(runner, t, command, signal, input) {
+    const nonce = randomUUID(), source = await readFile(new URL('../helper/remote-command.cjs', import.meta.url), 'utf8');
+    const remote = 'node -e ' + "'" + source.replaceAll("'", "'\\''") + "'";
+    const raw = await runner.run('ssh', [...sshArgs(t), remote], signal, JSON.stringify({ protocolVersion: 1, nonce, command, ...input === undefined ? {} : { input } }));
+    if (signal.aborted || raw.exitCode !== 0 || raw.stderr !== '')
+        throw Error('REMOTE_RESULT_INVALID');
+    const lines = raw.stdout.split('\n');
+    if (lines.pop() !== '')
+        throw Error('REMOTE_RESULT_INVALID');
+    let started = false, ended = false, exitCode = null;
+    const out = [], err = [];
+    for (const line of lines) {
+        const v = JSON.parse(line);
+        if (!v || typeof v !== 'object' || v.protocolVersion !== 1 || v.nonce !== nonce || ended)
+            throw Error('REMOTE_RESULT_INVALID');
+        const keys = Object.keys(v).sort().join(',');
+        if (v.type === 'start' && !started && keys === 'nonce,protocolVersion,type') {
+            started = true;
+            continue;
+        }
+        if (!started)
+            throw Error('REMOTE_RESULT_INVALID');
+        if ((v.type === 'stdout' || v.type === 'stderr') && keys === 'data,nonce,protocolVersion,type' && typeof v.data === 'string') {
+            const bytes = Buffer.from(v.data, 'base64');
+            if (bytes.toString('base64') !== v.data)
+                throw Error('REMOTE_RESULT_INVALID');
+            (v.type === 'stdout' ? out : err).push(bytes);
+            continue;
+        }
+        if (v.type === 'end' && keys === 'exitCode,nonce,protocolVersion,signal,type' && Number.isInteger(v.exitCode) && v.exitCode >= 0 && v.exitCode <= 255 && v.signal === null) {
+            ended = true;
+            exitCode = v.exitCode;
+            continue;
+        }
+        throw Error('REMOTE_RESULT_INVALID');
+    }
+    if (!ended || exitCode === null)
+        throw Error('REMOTE_RESULT_INVALID');
+    return { exitCode, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') };
+}
+export function createSsh(runner, maxOutputBytes) {
+    return {
+        verify: async (t, signal) => { try {
+            const r = await runRemote(runner, t, 'id -un', signal);
+            return r.exitCode === 0 && r.stdout.trim() === t.username ? ok(undefined) : fail('SSH_FAILED');
+        }
+        catch {
+            return fail('SSH_FAILED');
+        } },
+        status: async (t, p, signal) => {
+            try {
+                if (!['codex', 'claude'].includes(p) || !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1)
+                    return fail('AUTH_STATUS_INVALID');
+                const source = await readFile(new URL('../helper/auth-status.cjs', import.meta.url), 'utf8');
+                return ok(await runRemote(runner, t, 'node -e ' + "'" + source.replaceAll("'", "'\\''") + "' -- " + p + ' ' + maxOutputBytes, signal));
+            }
+            catch {
+                return fail('AUTH_STATUS_INVALID');
+            }
+        },
+    };
+}

package/lib/startup.d.ts

@@ -0,0 +1,18 @@
+import type { ConnectApi, ConnectionState, LoginPromptState, LoginPromptResult, Provider, NeedCode, Result } from './api.ts';
+export type StartupState = LoginPromptState;
+export declare function employeeMessage(code?: NeedCode): string;
+type Operations = Pick<ConnectApi, 'connect' | 'checkLogin' | 'login' | 'getState'>;
+export declare function createStartup(api: Operations, providers: Provider[], emit?: (s: LoginPromptState) => void, result?: (r: LoginPromptResult) => void, instanceId?: string): {
+    getState: () => LoginPromptState;
+    check: () => Promise<void>;
+    subscribe(listener: (s: LoginPromptState) => void): () => void;
+    request(provider: Provider, intent: "automatic" | "user"): Promise<Result<LoginPromptState>>;
+    respond: (requestId: string, action: "authorize" | "defer") => Promise<Result<LoginPromptState>>;
+    defer(provider: Provider): void;
+    authorize(provider: Provider): Promise<void>;
+    connectionChanged(next: ConnectionState): void;
+    stop(): void;
+    dispose(): Promise<void>;
+};
+export type Startup = ReturnType<typeof createStartup>;
+export {};