@ai-workbench/connect 0.0.0-stage → 0.7.5

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

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;