@ai-workbench/connect 0.0.0-stage → 0.7.6

package/lib/network.js

@@ -0,0 +1,226 @@
+import { request } from 'node:http';
+import { lstat, writeFile, rename, rm } from 'node:fs/promises';
+import { join, dirname, isAbsolute } from 'node:path';
+import { hostname } from 'node:os';
+import { StringDecoder } from 'node:string_decoder';
+import { randomUUID } from 'node:crypto';
+import { need, dependency, ok, fail, NeedError } from "./needs.js";
+import { privateDirectory } from "./private-files.js";
+import { proxyCommand } from "./ssh.js";
+function valid(s) { return [s.executable, s.runtimeDir, s.stateDir].every(p => typeof p === 'string' && isAbsolute(p) && !/[\x00-\x1f\x7f]/.test(p)) && typeof s.proxyListen === 'string' && /^127\.0\.0\.1:(?:0|[1-9][0-9]*)$/.test(s.proxyListen) && Number(s.proxyListen.split(':')[1]) <= 65535 && s.logUpload === false && [s.statusRefreshIntervalSeconds, s.dialTimeoutSeconds, s.headerTimeoutSeconds, s.enrollmentObservationSeconds].every(n => typeof n === 'number' && Number.isFinite(n) && n >= 1e-9 && n <= 9223372036) && [s.statusRefreshIntervalSeconds, s.headerTimeoutSeconds].every(n => Number.isInteger(n * 1000) && n * 1000 >= 1 && n * 1000 <= 2147483647) && [s.httpMaxHeaderBytes, s.httpMaxResponseHeaderBytes].every(n => Number.isSafeInteger(n) && n > 0) && Number.isSafeInteger(s.controlMaxBytes) && s.controlMaxBytes > 0 && s.controlMaxBytes <= 2147483647; }
+function mapped(code) { return { NEED_ENROLLMENT: 'ENROLLMENT_REQUIRED', ENROLLMENT_REJECTED: 'NETWORK_KEY_INVALID', ENROLLMENT_RESULT_UNKNOWN: 'ENROLLMENT_INVALID', LOCAL_STATE_INVALID: 'ENROLLMENT_INVALID', HOST_OFFLINE: 'HOST_OFFLINE', HOST_NOT_VISIBLE: 'DEPENDENCY_REQUIRED', CONFIG_INVALID: 'SETTINGS_REQUIRED', CAPABILITY_NOT_IMPLEMENTED: 'DEPENDENCY_REQUIRED', NEED_HOST_CONTRACT: 'DEPENDENCY_REQUIRED', NETWORK_INTERRUPTED: 'CONNECTION_LOST', CONTROL_UNAVAILABLE: 'DEPENDENCY_REQUIRED' }[String(code)] ?? 'DEPENDENCY_REQUIRED'; }
+export async function writeNetworkConfig(file, e, s) {
+    if (!valid(s) || !isAbsolute(file))
+        return fail('SETTINGS_REQUIRED');
+    let temp;
+    try {
+        await privateDirectory(dirname(file));
+        const config = { apiVersion: 1, stateDir: s.stateDir, runtimeDir: s.runtimeDir, nodeName: `aw-${e.username}-${hostname()}-${process.getuid()}`, ...(e.authKeyFile ? { authKeyFile: e.authKeyFile } : {}), host: { name: e.host, sshPort: e.port, employee: e.username, knownHostsFile: e.knownHostsFile }, proxyListen: s.proxyListen, statusRefreshIntervalSeconds: s.statusRefreshIntervalSeconds, dialTimeoutSeconds: s.dialTimeoutSeconds, headerTimeoutSeconds: s.headerTimeoutSeconds, enrollmentObservationSeconds: s.enrollmentObservationSeconds, logUpload: s.logUpload, httpMaxHeaderBytes: s.httpMaxHeaderBytes, httpMaxResponseHeaderBytes: s.httpMaxResponseHeaderBytes };
+        temp = join(dirname(file), '.network-' + randomUUID());
+        await writeFile(temp, JSON.stringify(config), { flag: 'wx', mode: 0o600 });
+        await rename(temp, file);
+        temp = undefined;
+        return ok(undefined);
+    }
+    catch {
+        return dependency('可写的私有 N 配置目录');
+    }
+    finally {
+        if (temp)
+            await rm(temp, { force: true });
+    }
+}
+export function createNetworkClient(s) {
+    const listeners = new Set();
+    let timer, previous, refreshing = false, disposed = false;
+    const pending = new Set();
+    let expected;
+    const bad = (code) => { throw new NeedError(need(code)); };
+    async function socket() {
+        if (!valid(s))
+            bad('SETTINGS_REQUIRED');
+        const dir = await lstat(s.runtimeDir), sock = await lstat(join(s.runtimeDir, 'control.sock'));
+        if (!dir.isDirectory() || dir.isSymbolicLink() || dir.uid !== process.getuid() || (dir.mode & 0o077) || !sock.isSocket() || sock.isSymbolicLink() || sock.uid !== process.getuid() || (sock.mode & 0o177))
+            bad('DEPENDENCY_REQUIRED');
+    }
+    async function send(method, path, signal) {
+        try {
+            await socket();
+        }
+        catch (e) {
+            if (e instanceof NeedError)
+                throw e;
+            bad('DEPENDENCY_REQUIRED');
+        }
+        if (disposed || signal.aborted)
+            bad('CONNECTION_LOST');
+        return new Promise((resolve, reject) => { const req = request({ socketPath: join(s.runtimeDir, 'control.sock'), path, method, signal, agent: false }, response => { clearTimeout(deadline); resolve(response); }); const deadline = setTimeout(() => req.destroy(new Error('CONTROL_HEADER_TIMEOUT')), s.headerTimeoutSeconds * 1000); req.on('error', () => { clearTimeout(deadline); reject(new NeedError(need('DEPENDENCY_REQUIRED'))); }); req.end(); });
+    }
+    async function json(res) { let size = 0; const chunks = []; try {
+        for await (const chunk of res) {
+            size += chunk.length;
+            if (size > s.controlMaxBytes)
+                bad('DEPENDENCY_REQUIRED');
+            chunks.push(chunk);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        res.destroy();
+        bad('DEPENDENCY_REQUIRED');
+    } }
+    async function status(signal) {
+        try {
+            const res = await send('GET', '/v1/status', signal), v = await json(res);
+            if (v?.apiVersion !== 1)
+                return dependency('N v1 状态协议');
+            if (res.statusCode !== 200 || v.error) {
+                const result = fail(mapped(v.error?.code));
+                if (!result.ok && result.error.code === 'HOST_OFFLINE' && v.host?.name === expected?.host && typeof v.host.lastSeenAt === 'string' && !Number.isNaN(Date.parse(v.host.lastSeenAt)))
+                    result.error.lastSeen = v.host.lastSeenAt;
+                return result;
+            }
+            if (v.enrollment !== 'online')
+                return fail(v.enrollment === 'needs_enrollment' ? 'ENROLLMENT_REQUIRED' : v.enrollment === 'rejected' ? 'NETWORK_KEY_INVALID' : 'CONNECTION_LOST');
+            if (v.host?.name !== expected?.host)
+                return dependency('与开通主机匹配的 N 状态');
+            if (v.host.online === false) {
+                const result = fail('HOST_OFFLINE');
+                if (!result.ok && typeof v.host.lastSeenAt === 'string' && !Number.isNaN(Date.parse(v.host.lastSeenAt)))
+                    result.error.lastSeen = v.host.lastSeenAt;
+                return result;
+            }
+            if (v.host.online !== true)
+                return dependency('N 已核实的主机在线状态');
+            return ok(undefined);
+        }
+        catch (e) {
+            return e instanceof NeedError ? { ok: false, error: e.need } : dependency('N 私有控制 socket；未使用直连网络');
+        }
+    }
+    async function refresh() { if (refreshing || !expected || disposed)
+        return; refreshing = true; const c = new AbortController(); pending.add(c); try {
+        const r = await status(c.signal), online = r.ok;
+        if (previous !== undefined && previous !== online)
+            for (const listener of listeners)
+                listener({ kind: online ? 'restored' : 'lost' });
+        previous = online;
+    }
+    finally {
+        pending.delete(c);
+        refreshing = false;
+    } }
+    return {
+        async connect(e, signal) {
+            expected = e;
+            const result = await status(signal);
+            previous = result.ok;
+            if (!result.ok)
+                return result;
+            try {
+                const exe = await lstat(s.executable);
+                if (!exe.isFile() || exe.isSymbolicLink() || !(exe.mode & 0o111))
+                    return dependency('N 真实 helper 可执行程序');
+                return ok({ proxyCommand: proxyCommand(s.executable, s.runtimeDir) });
+            }
+            catch {
+                return dependency('N 真实 helper 可执行程序');
+            }
+        },
+        onState(listener) { listeners.add(listener); if (valid(s) && !timer) {
+            timer = setInterval(() => { void refresh(); }, s.statusRefreshIntervalSeconds * 1000);
+            timer.unref();
+        } return () => { listeners.delete(listener); if (!listeners.size && timer) {
+            clearInterval(timer);
+            timer = undefined;
+            for (const c of pending)
+                c.abort();
+        } }; },
+        async acquireProxy(signal) {
+            const res = await send('POST', '/v1/login-proxy', signal);
+            if (res.statusCode !== 201) {
+                const v = await json(res);
+                if (v?.apiVersion !== 1)
+                    bad('DEPENDENCY_REQUIRED');
+                bad(mapped(v.error?.code));
+            }
+            if (!String(res.headers['content-type']).startsWith('application/x-ndjson')) {
+                res.destroy();
+                bad('DEPENDENCY_REQUIRED');
+            }
+            let resolveLine = () => { }, rejectLine = () => { }, rejectClosed = () => { }, resolveClosed = () => { };
+            let text = '', size = 0, received = false, released = false;
+            const decoder = new StringDecoder('utf8');
+            const first = new Promise((yes, no) => { resolveLine = yes; rejectLine = no; });
+            const closed = new Promise((yes, no) => { resolveClosed = yes; rejectClosed = no; });
+            void closed.catch(() => { });
+            const lost = () => { if (!released) {
+                const e = new NeedError(need('CONNECTION_LOST'));
+                rejectLine(e);
+                rejectClosed(e);
+            } };
+            res.on('error', lost);
+            res.on('end', lost);
+            res.on('close', lost);
+            res.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > s.controlMaxBytes) {
+                    lost();
+                    res.destroy();
+                    return;
+                }
+                if (received) {
+                    if (chunk.toString().trim()) {
+                        lost();
+                        res.destroy();
+                    }
+                    return;
+                }
+                text += decoder.write(chunk);
+                const end = text.indexOf('\n');
+                if (end < 0)
+                    return;
+                received = true;
+                try {
+                    const v = JSON.parse(text.slice(0, end)), url = new URL(v.url);
+                    if (v.apiVersion !== 1 || typeof v.id !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(v.id) || url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password || url.pathname !== '/' || url.search || url.hash || !['username', 'password'].every(k => typeof v[k] === 'string' && v[k].length && !/[\x00-\x1f\x7f]/.test(v[k])) || text.slice(end + 1).trim())
+                        throw Error();
+                    resolveLine(v);
+                }
+                catch {
+                    rejectLine(new NeedError(need('DEPENDENCY_REQUIRED')));
+                    res.destroy();
+                }
+                finally {
+                    text = '';
+                }
+            });
+            let v;
+            try {
+                v = await first;
+            }
+            catch (e) {
+                res.destroy();
+                throw e;
+            }
+            let release;
+            const lease = { url: v.url, username: v.username, password: v.password, closed, release: () => release ??= (async () => { released = true; res.destroy(); try {
+                    const c = new AbortController();
+                    const response = await send('DELETE', '/v1/login-proxy/' + encodeURIComponent(v.id), c.signal);
+                    response.resume();
+                    if (![204, 404].includes(response.statusCode))
+                        bad('DEPENDENCY_REQUIRED');
+                }
+                finally {
+                    lease.username = '';
+                    lease.password = '';
+                    v = null;
+                    resolveClosed();
+                } })() };
+            return lease;
+        },
+        dispose() { disposed = true; if (timer)
+            clearInterval(timer); for (const c of pending)
+            c.abort(); listeners.clear(); },
+    };
+}

package/lib/physical-fs.d.ts

@@ -0,0 +1,3 @@
+import * as nodeFs from 'node:fs';
+export declare const createWriteStream: typeof nodeFs.createWriteStream;
+export declare const open: typeof nodeFs.promises.open, lstat: typeof nodeFs.promises.lstat, readFile: typeof nodeFs.promises.readFile, writeFile: typeof nodeFs.promises.writeFile, readdir: typeof nodeFs.promises.readdir, readlink: typeof nodeFs.promises.readlink, realpath: typeof nodeFs.promises.realpath, rename: typeof nodeFs.promises.rename, rm: typeof nodeFs.promises.rm, mkdir: typeof nodeFs.promises.mkdir, symlink: typeof nodeFs.promises.symlink;

package/lib/physical-fs.js

@@ -0,0 +1,7 @@
+import * as nodeFs from 'node:fs';
+import { createRequire } from 'node:module';
+// 组件归档内的.asar是待校验的物理文件，不能消费Electron的虚拟目录视图。
+// 仅缓存/解压边界使用；不设置全局process.noAsar，不影响宿主模块加载。
+const physical = process.versions.electron ? createRequire(import.meta.url)('original-fs') : nodeFs;
+export const { createWriteStream } = physical;
+export const { open, lstat, readFile, writeFile, readdir, readlink, realpath, rename, rm, mkdir, symlink } = physical.promises;

package/lib/ports.d.ts

@@ -0,0 +1,43 @@
+import type { Provider, Result, SshTarget, SessionTarget, HostContext, Project, ProjectList } from './api.ts';
+export interface Enrollment {
+    authKeyFile?: string;
+    hostContext?: HostContext;
+    host: string;
+    username: string;
+    port: number;
+    projectRoot: string;
+    knownHostsFile: string;
+    session: SessionTarget;
+}
+export interface CommandResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type NetworkEvent = {
+    kind: 'lost';
+} | {
+    kind: 'restored';
+};
+export interface Ports {
+    enrollment?: {
+        read(signal: AbortSignal): Promise<Result<Enrollment>>;
+    };
+    network?: {
+        connect(enrollment: Enrollment, signal: AbortSignal): Promise<Result<{
+            proxyCommand: string;
+        }>>;
+        onState(listener: (event: NetworkEvent) => void): () => void;
+    };
+    ssh?: {
+        verify(target: SshTarget, signal: AbortSignal): Promise<Result<void>>;
+        status(target: SshTarget, provider: Provider, signal: AbortSignal): Promise<Result<CommandResult>>;
+    };
+    projects?: {
+        list(t: SshTarget, s: AbortSignal): Promise<Result<ProjectList>>;
+        create(t: SshTarget, name: string, s: AbortSignal): Promise<Result<Project>>;
+    };
+    login?: {
+        run(target: SshTarget, provider: Provider, signal: AbortSignal): Promise<Result<void>>;
+    };
+}

package/lib/ports.js

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

package/lib/private-files.d.ts

@@ -0,0 +1,3 @@
+export declare function privateDirectory(path: string): Promise<void>;
+export declare function privateFile(path: string): Promise<void>;
+export declare function readPrivate(path: string, maxBytes?: number): Promise<string>;

package/lib/private-files.js

@@ -0,0 +1,41 @@
+import { lstat, mkdir, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+export async function privateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const s = await lstat(path);
+    if (!s.isDirectory() || s.isSymbolicLink() || s.uid !== process.getuid() || (s.mode & 0o077) !== 0)
+        throw new Error('PRIVATE_DIRECTORY_REQUIRED');
+}
+export async function privateFile(path) {
+    const s = await lstat(path);
+    if (!s.isFile() || s.isSymbolicLink() || s.uid !== process.getuid() || (s.mode & 0o177) !== 0)
+        throw new Error('PRIVATE_FILE_REQUIRED');
+}
+export async function readPrivate(path, maxBytes) {
+    const h = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const s = await h.stat();
+        if (!s.isFile() || s.uid !== process.getuid() || (s.mode & 0o177) !== 0)
+            throw new Error('PRIVATE_FILE_REQUIRED');
+        if (maxBytes === undefined)
+            return await h.readFile('utf8');
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 2147483647 || s.size > maxBytes)
+            throw new Error('PRIVATE_FILE_LIMIT');
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const buffer = Buffer.alloc(Math.min(65536, maxBytes + 1 - size));
+            const { bytesRead } = await h.read(buffer, 0, buffer.length, null);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+            if (size > maxBytes)
+                throw new Error('PRIVATE_FILE_LIMIT');
+            chunks.push(buffer.subarray(0, bytesRead));
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    finally {
+        await h.close();
+    }
+}

package/lib/processes.d.ts

@@ -0,0 +1,5 @@
+import type { Provider } from './api.ts';
+import type { Runner } from './ssh.ts';
+import type { RemoteLogin } from './login.ts';
+export declare function createRunner(maxBytes: number): Runner;
+export declare function createRemoteLogin(command: string, args: string[], provider: Provider, maxBytes: number, signal: AbortSignal, protocol?: 'remote-control'): Promise<RemoteLogin>;

package/lib/processes.js

@@ -0,0 +1,147 @@
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import { extractLoginUrl } from "./login.js";
+import { fail, ok } from "./needs.js";
+function limit(n) { if (!Number.isSafeInteger(n) || n < 1)
+    throw new Error('OUTPUT_SETTING_REQUIRED'); }
+function start(command, args, signal) {
+    if (signal.aborted)
+        throw new Error('CANCELLED');
+    return spawn(command, args, { shell: false, stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined } });
+}
+function reap(child, closed) {
+    if (child.exitCode === null && child.signalCode === null)
+        child.kill('SIGTERM');
+    return closed.then(() => { });
+}
+export function createRunner(maxBytes) {
+    limit(maxBytes);
+    return { run: async (command, args, signal, input) => {
+            const child = start(command, args, signal);
+            let stdout = '', stderr = '', size = 0, failed = false;
+            child.stdin.on('error', () => { failed = true; child.kill('SIGTERM'); });
+            child.stdin.end(input);
+            const finished = new Promise((resolve, reject) => {
+                child.once('error', () => { failed = true; });
+                for (const [stream, channel] of [[child.stdout, 'out'], [child.stderr, 'err']]) {
+                    const decoder = new StringDecoder('utf8');
+                    stream.on('data', (chunk) => { size += chunk.length; if (size > maxBytes) {
+                        failed = true;
+                        child.kill('SIGTERM');
+                        return;
+                    } if (channel === 'out')
+                        stdout += decoder.write(chunk);
+                    else
+                        stderr += decoder.write(chunk); });
+                }
+                child.once('close', code => failed || signal.aborted ? reject(new Error('COMMAND_FAILED')) : resolve({ exitCode: code, stdout, stderr }));
+            });
+            const abort = () => child.kill('SIGTERM');
+            signal.addEventListener('abort', abort, { once: true });
+            try {
+                if (signal.aborted)
+                    abort();
+                return await finished;
+            }
+            finally {
+                signal.removeEventListener('abort', abort);
+            }
+        } };
+}
+export async function createRemoteLogin(command, args, provider, maxBytes, signal, protocol) {
+    limit(maxBytes);
+    const child = start(command, args, signal);
+    let size = 0, invalid = false, urlSent = false, owned = false;
+    let terminal;
+    let ownResolve = () => { }, ownReject = () => { };
+    const ownership = new Promise((yes, no) => { ownResolve = yes; ownReject = () => no(new Error('REMOTE_LOGIN_NOT_STARTED')); });
+    void ownership.catch(() => { });
+    let found = () => { };
+    const url = new Promise(r => found = r);
+    const pending = new Map();
+    for (const stream of [child.stdout, child.stderr]) {
+        const record = { decoder: new StringDecoder('utf8'), line: '' };
+        pending.set(stream, record);
+        stream.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                invalid = true;
+                child.kill('SIGTERM');
+                return;
+            }
+            record.line += record.decoder.write(chunk);
+            const lines = record.line.split(/\r?\n/);
+            record.line = lines.pop();
+            for (const line of lines) {
+                if (protocol && line.startsWith('AW_LOGIN_PROCESS ')) {
+                    try {
+                        const v = JSON.parse(line.slice(17));
+                        if (stream === child.stdout && !owned && Number.isSafeInteger(v.pid) && v.pid > 0 && v.group === v.pid && v.provider === provider) {
+                            owned = true;
+                            ownResolve(v);
+                        }
+                        else
+                            throw Error();
+                    }
+                    catch {
+                        invalid = true;
+                        child.kill('SIGTERM');
+                    }
+                }
+                if (protocol && line.startsWith('AW_LOGIN_RESULT ')) {
+                    try {
+                        const v = JSON.parse(line.slice(16));
+                        if (stream !== child.stdout || terminal || !owned || v.protocolVersion !== 1 || v.provider !== provider || Object.keys(v).sort().join(',') !== 'exitCode,protocolVersion,provider,stopping' || !Number.isInteger(v.exitCode) || v.exitCode < 0 || v.exitCode > 255 || typeof v.stopping !== 'boolean')
+                            throw Error();
+                        terminal = v;
+                    }
+                    catch {
+                        invalid = true;
+                        child.kill('SIGTERM');
+                    }
+                }
+                const u = extractLoginUrl(provider, line);
+                if (u && !urlSent) {
+                    urlSent = true;
+                    found(ok(u));
+                }
+            }
+        });
+    }
+    child.once('error', () => { invalid = true; });
+    const completion = new Promise(resolve => child.once('close', code => {
+        for (const record of pending.values()) {
+            if (protocol && /^AW_LOGIN_(RESULT|PROCESS)/.test(record.line))
+                invalid = true;
+            const u = extractLoginUrl(provider, record.line + record.decoder.end());
+            if (u && !urlSent) {
+                urlSent = true;
+                found(ok(u));
+            }
+            record.line = '';
+        }
+        ownReject();
+        if (!urlSent)
+            found(fail('LOGIN_FAILED'));
+        signal.removeEventListener('abort', abort);
+        resolve(!invalid && !signal.aborted && code === 0 && (!protocol || (owned && terminal?.exitCode === 0 && !terminal.stopping)) ? ok(undefined) : fail('LOGIN_FAILED'));
+    }));
+    const abort = () => child.kill('SIGTERM');
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted)
+        abort();
+    child.stdin.on('error', () => { invalid = true; });
+    return { url, completion, ...(protocol ? { ownership } : {}),
+        writeCode: async (code) => {
+            if (signal.aborted || child.exitCode !== null || child.signalCode !== null || child.stdin.writableEnded || /[\x00-\x20\x7f]/.test(code) || !code)
+                throw new Error('LOGIN_CODE_REJECTED');
+            await new Promise((yes, no) => { const failed = () => no(new Error('LOGIN_STDIN_FAILED')); child.stdin.once('error', failed); const done = () => { child.stdin.removeListener('error', failed); yes(); }; if (protocol)
+                child.stdin.write(JSON.stringify({ type: 'code', value: code }) + '\n', done);
+            else
+                child.stdin.end(code + '\n', done); });
+        },
+        close: () => { if (protocol && child.exitCode === null && child.signalCode === null && !child.stdin.writableEnded) {
+            child.stdin.end(JSON.stringify({ type: 'close' }) + '\n');
+            return completion.then(() => { });
+        } return reap(child, completion); }, };
+}

package/lib/profile-activation.d.ts

@@ -0,0 +1,32 @@
+import type { Enrollment } from './ports.ts';
+import type { Result } from './api.ts';
+import type { NetworkProvider } from './provider.ts';
+export interface AssemblySettings {
+    configFile?: string;
+    helperLogFile?: string;
+    stateDir?: string;
+    runtimeDir?: string;
+    nodeName?: string;
+    proxyListen?: string;
+    logUpload?: boolean;
+    statusRefreshIntervalSeconds?: number;
+    dialTimeoutSeconds?: number;
+    headerTimeoutSeconds?: number;
+    enrollmentObservationSeconds?: number;
+    httpMaxHeaderBytes?: number;
+    httpMaxResponseHeaderBytes?: number;
+    startupObservationSeconds?: number;
+    shutdownObservationSeconds?: number;
+    controlResponseMaxBytes?: number;
+    downloadMaxRedirects?: number;
+}
+interface Options {
+    profileDir: string;
+    metadataMaxBytes: number;
+    network?: NetworkProvider;
+    settings?: AssemblySettings;
+}
+export declare function createProfileActivation(options: Options): {
+    activate(e: Enrollment, signal: AbortSignal): Promise<Result<void>>;
+};
+export {};

package/lib/profile-activation.js

@@ -0,0 +1,118 @@
+import { open, rename, rm, realpath } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { hostname, homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { ok, fail } from "./needs.js";
+import { mapNetworkNeed } from "./provider.js";
+import { privateDirectory, readPrivate } from "./private-files.js";
+import { NETWORK_DEFAULTS } from "./defaults.js";
+// Own handoff configuration only. Never reads N's identity files, journal or key contents.
+export function createProfileActivation(options) {
+    const root = join(options.profileDir, 'ai-workbench-connect'), recordFile = join(root, 'network-activation.json');
+    let flight, flightTarget;
+    async function save(file, value) { const bytes = JSON.stringify(value) + '\n'; if (Buffer.byteLength(bytes) > options.metadataMaxBytes)
+        throw Error('ACTIVATION_METADATA_LIMIT'); const temp = file + '.' + randomUUID(); try {
+        const h = await open(temp, 'wx', 0o600);
+        try {
+            await h.writeFile(bytes);
+            await h.sync();
+        }
+        finally {
+            await h.close();
+        }
+        await rename(temp, file);
+        const d = await open(join(file, '..'), 'r');
+        try {
+            await d.sync();
+        }
+        finally {
+            await d.close();
+        }
+    }
+    finally {
+        await rm(temp, { force: true });
+    } }
+    const receiptValid = (s) => s?.phase === 'active' && s.receipt?.apiVersion === 1 && s.receipt.session === 'identity' && s.receipt.identity === 'resumable' && ((s.receipt.key === 'confirmed' && s.receipt.cleanup === 'complete') || (s.receipt.key === 'not-required' && s.receipt.cleanup === 'not-required'));
+    async function run(e, signal) {
+        const n = options.network;
+        if (!n?.activate || !n.getActivationState || !n.onActivationState)
+            return fail('DEPENDENCY_REQUIRED');
+        if (signal.aborted)
+            return fail('ACTIVATION_CANCELLED');
+        try {
+            if (!isAbsolute(options.profileDir) || await realpath(options.profileDir) !== options.profileDir)
+                return fail('ENROLLMENT_INVALID');
+            await privateDirectory(root);
+            const configDir = join(root, 'network-config'), logDir = join(root, 'network-logs');
+            await privateDirectory(configDir);
+            await privateDirectory(logDir);
+            for (const p of [root, configDir, logDir])
+                if (await realpath(p) !== p)
+                    return fail('ENROLLMENT_INVALID');
+            const s = { ...NETWORK_DEFAULTS, ...options.settings };
+            const settings = { configFile: s.configFile ?? join(configDir, 'config.json'), helperLogFile: s.helperLogFile ?? join(logDir, 'network.log'), startupObservationSeconds: s.startupObservationSeconds, shutdownObservationSeconds: s.shutdownObservationSeconds, controlResponseMaxBytes: s.controlResponseMaxBytes, downloadMaxRedirects: s.downloadMaxRedirects };
+            const target = { host: e.host, username: e.username, port: e.port, knownHostsFile: e.knownHostsFile };
+            const expected = { apiVersion: 1, stateDir: s.stateDir ?? join(homedir(), 'Library', 'Application Support', 'ai-workbench', 'network'), runtimeDir: s.runtimeDir ?? '/tmp/aw-net-' + process.getuid(), nodeName: s.nodeName ?? `aw-${e.username}-${hostname()}-${process.getuid()}`, host: { name: e.host, sshPort: e.port, employee: e.username, knownHostsFile: e.knownHostsFile }, proxyListen: s.proxyListen, logUpload: s.logUpload, statusRefreshIntervalSeconds: s.statusRefreshIntervalSeconds, dialTimeoutSeconds: s.dialTimeoutSeconds, headerTimeoutSeconds: s.headerTimeoutSeconds, enrollmentObservationSeconds: s.enrollmentObservationSeconds, httpMaxHeaderBytes: s.httpMaxHeaderBytes, httpMaxResponseHeaderBytes: s.httpMaxResponseHeaderBytes };
+            const canonical = (v) => JSON.stringify(v, (_, x) => x && typeof x === 'object' && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => a.localeCompare(b))) : x);
+            const registration = { schemaVersion: 1, settings, target };
+            let stored = false;
+            try {
+                const r = JSON.parse(await readPrivate(recordFile, options.metadataMaxBytes));
+                if (canonical(r) !== canonical(registration))
+                    return fail('ENROLLMENT_MISMATCH');
+                stored = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            try {
+                const config = JSON.parse(await readPrivate(settings.configFile, options.metadataMaxBytes));
+                const key = config.authKeyFile;
+                delete config.authKeyFile;
+                if (canonical(config) !== canonical(expected) || (key !== undefined && key !== e.authKeyFile))
+                    return fail('ENROLLMENT_MISMATCH');
+                if (!stored)
+                    return fail('LOCAL_STATE_INVALID');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                if (stored)
+                    return fail('LOCAL_STATE_INVALID');
+                if (!e.authKeyFile)
+                    return fail('ENROLLMENT_REQUIRED');
+                await save(settings.configFile, { ...expected, authKeyFile: e.authKeyFile });
+            }
+            if (!stored)
+                await save(recordFile, registration);
+            // Settings and target references are durable before activation; thereafter N owns config cleanup.
+            const before = n.getActivationState();
+            let latest = before;
+            const off = n.onActivationState(next => { if (next.instanceId === before.instanceId && next.revision >= latest.revision)
+                latest = next; });
+            try {
+                const result = await n.activate(settings, signal);
+                if (!result.ok)
+                    return { ok: false, error: mapNetworkNeed(result.error) };
+                const current = n.getActivationState();
+                if (result.value.instanceId !== before.instanceId || current.instanceId !== before.instanceId || result.value.revision < latest.revision || current.revision < result.value.revision)
+                    return fail('CONTROL_PROTOCOL_INVALID');
+                if (!receiptValid(result.value) || !receiptValid(current))
+                    return fail('ENROLLMENT_RECEIPT_REQUIRED');
+                return ok(undefined);
+            }
+            finally {
+                off();
+            }
+        }
+        catch {
+            return fail('ENROLLMENT_INVALID');
+        }
+    }
+    return { activate(e, signal) { const target = JSON.stringify([e.host, e.username, e.port, e.knownHostsFile, e.projectRoot]); if (flight)
+            return target === flightTarget ? flight : Promise.resolve(fail('ACTIVATION_CONFLICT')); flightTarget = target; const p = run(e, signal); flight = p; void p.finally(() => { if (flight === p) {
+            flight = undefined;
+            flightTarget = undefined;
+        } }).catch(() => { }); return p; } };
+}

package/lib/profile-enrollment.d.ts

@@ -0,0 +1,21 @@
+import type { EnrollmentState, ConnectNeed, Result } from './api.ts';
+import type { Enrollment } from './ports.ts';
+export interface ProfileEnrollmentOptions {
+    profileDir: string;
+    metadataMaxBytes: number;
+    pick: (signal: AbortSignal) => Promise<string | null>;
+    activate?: (enrollment: Enrollment, signal: AbortSignal) => Promise<Result<void>>;
+    active?: () => boolean;
+    blockedByNetwork?: () => Pick<ConnectNeed, 'code'> | undefined;
+    onState?: (state: EnrollmentState) => void;
+}
+export declare function createProfileEnrollment(options: ProfileEnrollmentOptions): {
+    getState: () => EnrollmentState;
+    onState(fn: (s: EnrollmentState) => void): () => void;
+    read(): Promise<Result<Enrollment>>;
+    importEnrollment(): Promise<Result<{
+        outcome: "imported" | "cancelled";
+        state: EnrollmentState;
+    }>>;
+    dispose(): Promise<void>;
+};