@knowttl/ssh-axi 0.0.0-stage → 0.1.0

package/dist/authenticate.js

@@ -0,0 +1,209 @@
+import { lookup } from 'node:dns/promises';
+import { BlockList, isIP, connect } from 'node:net';
+import ssh2 from 'ssh2';
+import { SshError } from './errors.js';
+import { resolveSecret } from './profile.js';
+import { checkCommand, Output, secretPatterns } from './output.js';
+export const AUTHENTICATION_DEADLINE_MS = 15_000;
+export async function authenticate(profile) {
+    const connection = await openTransport(profile);
+    await connection.close();
+    return { authenticated: true, address: connection.address };
+}
+export async function execute(profile, settings, signal) {
+    validateSettings(settings);
+    checkCommand(settings.command, [resolveSecret(profile.privateKey, 'SSH_AXI_PRIVATE_KEY', true), resolveSecret(profile.passphrase, 'SSH_AXI_PASSPHRASE', false) ?? '']);
+    const started = performance.now();
+    const connection = await openTransport(profile, signal);
+    try {
+        return { ...await connection.execute(settings, signal), durationMs: Math.round(performance.now() - started) };
+    }
+    finally {
+        await connection.close();
+    }
+}
+function validateSettings(settings) {
+    if (!Number.isInteger(settings.timeout) || settings.timeout < 1 || settings.timeout > 600
+        || !Number.isInteger(settings.outputLimit) || settings.outputLimit < 0 || settings.outputLimit > 1024 * 1024) {
+        throw new SshError('USAGE', 'Timeout must be 1-600 seconds and output limit 0-1048576 bytes.', 2);
+    }
+}
+// Each command starts a fresh channel. The private worker retains only the
+// authenticated transport and its lifetime secret protection between commands.
+export async function openTransport(profile, signal) {
+    const passphrase = resolveSecret(profile.passphrase, 'SSH_AXI_PASSPHRASE', false);
+    const privateKey = Buffer.from(resolveSecret(profile.privateKey, 'SSH_AXI_PRIVATE_KEY', true));
+    const secrets = [privateKey.toString(), passphrase ?? ''];
+    const patterns = secretPatterns(secrets);
+    const client = new ssh2.Client();
+    let socket;
+    let closed = false;
+    let trusted = false;
+    let address = '';
+    let active;
+    let closedResolve;
+    const disconnected = new Promise(resolve => { closedResolve = resolve; });
+    client.on('close', () => { closed = true; active?.(); closedResolve(); });
+    client.on('error', () => { closed = true; active?.(); });
+    const close = async () => {
+        closed = true;
+        client.destroy();
+        socket?.destroy();
+        active?.();
+        await disconnected;
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            let finished = false;
+            const finish = (error) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(deadline);
+                signal?.removeEventListener('abort', abort);
+                client.off('error', failure);
+                client.off('close', failure);
+                if (error) {
+                    closed = true;
+                    client.destroy();
+                    socket?.destroy();
+                    reject(error);
+                }
+                else
+                    resolve();
+            };
+            const failure = () => finish(new SshError(trusted ? 'AUTH_FAILED' : 'TRUST_FAILED', trusted ? 'SSH key authentication failed; check the selected key and passphrase.' : 'SSH host trust could not be established.'));
+            const abort = () => finish(new SshError('COMMAND_CANCELLED', 'Connection cancelled before dispatch.'));
+            const deadline = setTimeout(() => finish(new SshError('AUTH_TIMEOUT', 'SSH authentication exceeded 15 seconds.')), AUTHENTICATION_DEADLINE_MS);
+            client.once('ready', () => finish());
+            client.once('error', failure);
+            client.once('close', failure);
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
+            void (async () => {
+                const addresses = isIP(profile.address) ? [{ address: profile.address, family: isIP(profile.address) }]
+                    : await lookup(profile.address, { all: true, verbatim: true });
+                if (finished)
+                    return;
+                const allowed = new BlockList();
+                for (const value of profile.allowedAddresses)
+                    allowed.addAddress(value, isIP(value) === 6 ? 'ipv6' : 'ipv4');
+                if (!addresses.length || addresses.some(value => !allowed.check(value.address, value.family === 6 ? 'ipv6' : 'ipv4'))) {
+                    finish(new SshError('ADDRESS_DENIED', 'The resolved endpoint is outside the approved address set.'));
+                    return;
+                }
+                address = addresses[0].address;
+                socket = connect({ host: address, port: profile.port, family: addresses[0].family });
+                socket.on('error', () => finish(new SshError('CONNECTION_FAILED', 'Cannot connect to the approved SSH endpoint.')));
+                client.connect({ sock: socket, username: profile.username, privateKey,
+                    ...(passphrase === undefined ? {} : { passphrase }), readyTimeout: AUTHENTICATION_DEADLINE_MS,
+                    authHandler: ['publickey'], hostVerifier: (key) => {
+                        trusted = profile.approvedHostKeys.some(value => Buffer.from(value.split(' ')[1], 'base64').equals(key));
+                        return trusted;
+                    } });
+            })().catch(() => finish(new SshError('AUTH_FAILED', 'Cannot authenticate with the selected endpoint and encrypted key.')));
+        });
+    }
+    finally {
+        privateKey.fill(0);
+    }
+    return { address, disconnected, close,
+        execute(settings, signal) {
+            if (closed)
+                throw new SshError('CONNECTION_CLOSED', 'The connection is closed. Open a new connection explicitly.');
+            if (active)
+                throw new SshError('CONNECTION_BUSY', 'A command is already active on this connection.');
+            validateSettings(settings);
+            checkCommand(settings.command, secrets);
+            if (signal?.aborted)
+                throw new SshError('COMMAND_CANCELLED', 'Execution cancelled before dispatch.');
+            return new Promise(resolve => {
+                let finished = false;
+                let channel;
+                let remoteExit = null;
+                let remoteSignal = null;
+                let outcome = 'unknown';
+                let diagnostic;
+                let grace;
+                const started = performance.now();
+                const stdout = new Output(patterns, settings.outputLimit);
+                const stderr = new Output(patterns, settings.outputLimit);
+                const finish = () => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    clearTimeout(deadline);
+                    clearTimeout(grace);
+                    signal?.removeEventListener('abort', abort);
+                    active = undefined;
+                    const streams = { stdout: stdout.finish(), stderr: stderr.finish() };
+                    if (streams.stdout.withheld || streams.stderr.withheld) {
+                        for (const stream of Object.values(streams)) {
+                            stream.text = '';
+                            stream.retainedBytes = 0;
+                            stream.withheld = true;
+                        }
+                        diagnostic = 'Protected output withheld.';
+                        if (outcome === 'completed')
+                            outcome = 'failed';
+                    }
+                    resolve({ address, outcome, remoteExit, remoteSignal,
+                        termination: remoteExit !== null || remoteSignal !== null ? 'remote-exit' : 'unknown',
+                        ...streams, durationMs: Math.round(performance.now() - started), ...(diagnostic ? { diagnostic } : {}) });
+                };
+                const terminate = () => {
+                    if (!channel)
+                        return;
+                    // ssh2's public signal() refuses after stdin EOF; SSH still permits
+                    // channel requests until close. The pinned transport keeps stdin closed.
+                    const transport = channel;
+                    if (['open', 'eof'].includes(transport.outgoing.state))
+                        transport._client._protocol.signal(transport.outgoing.id, 'TERM');
+                };
+                const cancel = (reason, message) => {
+                    if (finished || grace)
+                        return;
+                    outcome = reason;
+                    diagnostic = message;
+                    terminate();
+                    grace = setTimeout(() => { channel?.close(); void close(); finish(); }, 200);
+                };
+                const abort = () => cancel('cancelled');
+                const deadline = setTimeout(() => cancel('timed_out'), settings.timeout * 1000);
+                active = finish;
+                signal?.addEventListener('abort', abort, { once: true });
+                client.exec(settings.command, { pty: false }, (error, stream) => {
+                    if (finished) {
+                        stream?.destroy();
+                        return;
+                    }
+                    if (error) {
+                        outcome = 'failed';
+                        finish();
+                        return;
+                    }
+                    channel = stream;
+                    if (grace)
+                        terminate();
+                    const receive = (output, bytes) => {
+                        output.push(bytes);
+                        if (stdout.receivedBytes + stderr.receivedBytes > 16 * 1024 * 1024)
+                            cancel('unknown', 'Output flood limit exceeded; inspect remote state before retrying.');
+                    };
+                    stream.on('data', (bytes) => receive(stdout, bytes));
+                    stream.stderr.on('data', (bytes) => receive(stderr, bytes));
+                    stream.on('exit', (code, name) => { remoteExit = typeof code === 'number' ? code : null; remoteSignal = name ?? null; });
+                    stream.on('error', () => { void close(); finish(); });
+                    stream.on('close', () => {
+                        if (!grace)
+                            outcome = remoteExit === 0 ? 'completed' : remoteExit !== null || remoteSignal ? 'failed' : 'unknown';
+                        finish();
+                    });
+                    stream.end();
+                });
+            });
+        } };
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(args: readonly string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,74 @@
+import { encode } from '@toon-format/toon';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { configPath, loadConfiguration, selectProfile, resolveSecret } from './profile.js';
+import { doctor } from './doctor.js';
+import { SshError } from './errors.js';
+import { executeNative } from './native-execution.js';
+import { commands, flagHelp, parseArguments } from './arguments.js';
+function projection(name, profile) {
+    return { id: name, address: profile.address, port: profile.port, username: profile.username };
+}
+export async function main(args) {
+    const json = args.includes('--json');
+    const output = (value) => console.log(json ? JSON.stringify(value) : encode(value));
+    try {
+        const parsed = parseArguments(args);
+        if (parsed.help) {
+            const usage = parsed.command === 'exec' ? 'exec <host> --command <text> --confirm'
+                : parsed.command === 'execution cancel' ? 'execution cancel <id> --confirm'
+                    : parsed.command === 'execution show' ? 'execution show <id>'
+                        : parsed.command === 'connection set' ? 'connection set <id> --idle-timeout 5m'
+                            : ['connection show', 'connection close'].includes(parsed.command) ? `${parsed.command} <id>`
+                                : `${parsed.command}${commands[parsed.command].arguments ? ' <host>' : ''}`;
+            output({ description: commands[parsed.command].description, flags: flagHelp + Object.keys(commands[parsed.command].flags ?? {}).map(key => `, --${key}`).join(''),
+                ...(parsed.command === 'exec' ? { defaults: { timeout: '60s', outputLimit: '65536 bytes' } } : {}),
+                examples: parsed.command === '' ? ['ssh-axi host list', 'ssh-axi doctor <host>', 'ssh-axi config path']
+                    : [`ssh-axi ${usage}`, `ssh-axi ${usage} --json`] });
+            return;
+        }
+        const path = configPath(parsed.config);
+        if (parsed.command === 'config path') {
+            output({ path });
+            return;
+        }
+        if (parsed.command.startsWith('execution ') || parsed.command.startsWith('connection '))
+            throw new SshError('HOSTED_REQUIRED', 'Use artium-axi ssh-axi for managed connections and executions.');
+        const config = loadConfiguration(path);
+        if (['', 'host list', 'profile list'].includes(parsed.command)) {
+            const hosts = Object.entries(config.profiles).map(([name, profile]) => projection(name, profile));
+            output({ ...(parsed.command === '' ? { bin: resolve(fileURLToPath(new URL('./main.js', import.meta.url))).replace(homedir(), '~'),
+                    description: 'Discover approved SSH hosts and run confirmed bounded commands.' } : {}),
+                hosts, count: hosts.length, ...(hosts.length ? {} : { message: 'No configured hosts found.' }),
+                help: hosts.length ? ['ssh-axi host show <host>', 'ssh-axi doctor <host>'] : ['ssh-axi config path', 'ssh-axi profile list --help'] });
+            return;
+        }
+        const selected = selectProfile(config, parsed.profile);
+        if (parsed.command === 'exec') {
+            const result = await executeNative(selected.name, selected.profile, parsed);
+            output(result);
+            process.exitCode = result.outcome === 'completed' ? 0 : result.remoteExit && result.remoteExit > 0 && result.remoteExit <= 255 ? result.remoteExit : 1;
+            return;
+        }
+        if (parsed.command === 'host show') {
+            output({ host: projection(selected.name, selected.profile) });
+            return;
+        }
+        if (parsed.command === 'auth status') {
+            const key = resolveSecret(selected.profile.privateKey, 'SSH_AXI_PRIVATE_KEY', true);
+            const passphrase = resolveSecret(selected.profile.passphrase, 'SSH_AXI_PASSPHRASE', false);
+            const source = (reference, fallback) => reference && 'file' in reference ? 'protected file' : `env:${reference?.env ?? fallback}`;
+            output({ profile: selected.name, privateKey: key ? 'available' : 'missing', passphrase: passphrase ? 'available' : 'absent',
+                privateKeySource: source(selected.profile.privateKey, 'SSH_AXI_PRIVATE_KEY'),
+                passphraseSource: source(selected.profile.passphrase, 'SSH_AXI_PASSPHRASE'), network: 'not checked' });
+            return;
+        }
+        output({ host: selected.name, ...await doctor(selected.profile), commandsExecuted: 0 });
+    }
+    catch (error) {
+        const safe = error instanceof SshError ? error : new SshError('INTERNAL_ERROR', 'The SSH operation failed.');
+        output({ error: { code: safe.code, message: safe.message }, help: ['ssh-axi --help'] });
+        process.exitCode = safe.exitCode;
+    }
+}

package/dist/connection-worker.d.ts

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

package/dist/connection-worker.js

@@ -0,0 +1,73 @@
+import { openTransport } from './authenticate.js';
+import { configPath, loadConfiguration, selectProfile } from './profile.js';
+import { SshError } from './errors.js';
+// Only the host can opt in through inherited IPC. It owns profile custody.
+if (!process.send || process.argv.length !== 2)
+    process.exit(2);
+let connection;
+let opening = false;
+let fenced = false;
+let active;
+const authentication = new AbortController();
+const send = (value) => { if (process.connected)
+    process.send(value); };
+process.on('disconnect', () => process.exit(1));
+process.on('message', async (value) => {
+    let id;
+    try {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new SshError('IPC_INVALID', 'Invalid connection request.');
+        const request = value;
+        if (request.revision !== 2 || typeof request.id !== 'string'
+            || !['open', 'exec', 'cancel', 'close'].includes(String(request.operation))
+            || Object.keys(request).some(key => !['revision', 'id', 'operation', 'settings'].includes(key)))
+            throw new SshError('IPC_INVALID', 'Incompatible connection protocol.');
+        id = request.id;
+        if (request.operation === 'close') {
+            fenced = true;
+            authentication.abort();
+            active?.abort();
+            await connection?.close();
+            send({ id, ok: true, result: { closed: true } });
+            if (process.connected)
+                process.disconnect();
+            return;
+        }
+        if (fenced)
+            throw new SshError('CONNECTION_CLOSED', 'Connection is fenced.');
+        if (request.operation === 'cancel') {
+            active?.abort();
+            send({ id, ok: true, result: { cancelled: true } });
+            return;
+        }
+        if (request.operation === 'open') {
+            if (opening)
+                throw new SshError('IPC_INVALID', 'Connection already initialized.');
+            opening = true;
+            connection = await openTransport(selectProfile(loadConfiguration(configPath()), 'artium').profile, authentication.signal);
+            if (fenced) {
+                await connection.close();
+                return;
+            }
+            void connection.disconnected.then(() => { if (!fenced && process.connected)
+                process.disconnect(); });
+            send({ id, ok: true, result: { authenticated: true, address: connection.address } });
+            return;
+        }
+        if (!connection)
+            throw new SshError('CONNECTION_CLOSED', 'Connection is not authenticated.');
+        if (active)
+            throw new SshError('CONNECTION_BUSY', 'A command is already active on this connection.');
+        active = new AbortController();
+        try {
+            send({ id, ok: true, result: await connection.execute(request.settings, active.signal) });
+        }
+        finally {
+            active = undefined;
+        }
+    }
+    catch (error) {
+        const safe = error instanceof SshError ? error : new SshError('WORKER_FAILED', 'Private connection operation failed.');
+        send({ id, ok: false, error: { code: safe.code, message: safe.message } });
+    }
+});

package/dist/doctor.d.ts

@@ -0,0 +1,7 @@
+import { type Profile } from './profile.js';
+import type { ExecutionResult, ExecutionSettings } from './authenticate.js';
+export declare function doctor(profile: Profile): Promise<{
+    authenticated: true;
+    address: string;
+}>;
+export declare function executeCommand(profile: Profile, settings: ExecutionSettings, signal?: AbortSignal): Promise<ExecutionResult>;

package/dist/doctor.js

@@ -0,0 +1,63 @@
+import { fork } from 'node:child_process';
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SshError } from './errors.js';
+import { resolveSecret } from './profile.js';
+import { checkCommand, containsSecret, secretPatterns } from './output.js';
+// Both native and hosted callers use this one-shot supervisor. Artium supplies
+// only the selected binding's profile; no public caller can supply worker state.
+export async function doctor(profile) {
+    return supervise(profile);
+}
+export async function executeCommand(profile, settings, signal) {
+    return supervise(profile, settings, signal);
+}
+async function supervise(profile, settings, signal) {
+    const privateKey = resolveSecret(profile.privateKey, 'SSH_AXI_PRIVATE_KEY', true);
+    const passphrase = resolveSecret(profile.passphrase, 'SSH_AXI_PASSPHRASE', false);
+    if (settings)
+        checkCommand(settings.command, [privateKey, passphrase ?? '']);
+    const directory = await mkdtemp(join(tmpdir(), 'ssh-axi-'));
+    try {
+        for (const name of ['config', 'state', 'tmp'])
+            await mkdir(join(directory, name), { mode: 0o700 });
+        const environment = { HOME: directory, USERPROFILE: directory,
+            XDG_CONFIG_HOME: join(directory, 'config'), XDG_STATE_HOME: join(directory, 'state'),
+            APPDATA: join(directory, 'config'), LOCALAPPDATA: join(directory, 'state'),
+            TMPDIR: join(directory, 'tmp'), TMP: join(directory, 'tmp'), TEMP: join(directory, 'tmp'),
+            ARTIUM_SECRET_0: privateKey, ...(passphrase === undefined ? {} : { ARTIUM_SECRET_1: passphrase }) };
+        return await new Promise((resolve, reject) => {
+            const child = fork(new URL('./worker.js', import.meta.url), [], { env: environment,
+                execArgv: [], detached: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+            let response;
+            const deadline = setTimeout(() => child.kill('SIGKILL'), 17_000 + (settings?.timeout ?? 0) * 1000);
+            const cancel = () => { if (child.connected)
+                child.send({ cancel: true }); };
+            signal?.addEventListener('abort', cancel, { once: true });
+            child.once('error', () => reject(new SshError('WORKER_FAILED', 'Cannot start the private SSH probe.')));
+            child.once('message', value => { response = value; });
+            child.once('exit', () => {
+                clearTimeout(deadline);
+                signal?.removeEventListener('abort', cancel);
+                const value = response;
+                if (value?.ok && value.result) {
+                    if (containsSecret(JSON.stringify(value.result), secretPatterns([privateKey, passphrase ?? '']))) {
+                        reject(new SshError('SECRET_IN_OUTPUT', 'Protected worker output withheld.'));
+                    }
+                    else
+                        resolve(value.result);
+                }
+                else
+                    reject(value?.error ? new SshError(value.error.code, value.error.message) : new SshError('WORKER_FAILED', 'The private SSH probe stopped without a result.'));
+            });
+            child.send({ revision: 1, operation: settings ? 'exec' : 'doctor', ...(settings ? { settings } : {}), profile: { ...profile, privateKey: { env: 'ARTIUM_SECRET_0' },
+                    ...(passphrase === undefined ? {} : { passphrase: { env: 'ARTIUM_SECRET_1' } }) } });
+            if (signal?.aborted)
+                cancel();
+        });
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class SshError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(code: string, message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+export class SshError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = 1) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}

package/dist/hosted.d.ts

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

package/dist/hosted.js

@@ -0,0 +1,75 @@
+import { encode } from '@toon-format/toon';
+import { parseArguments } from './arguments.js';
+import { configPath, loadConfiguration, selectProfile } from './profile.js';
+import { doctor, executeCommand } from './doctor.js';
+import { SshError } from './errors.js';
+import { VERSION } from './version.js';
+if (!process.send)
+    process.exit(2);
+process.once('message', async (message) => {
+    const output = (value) => console.log(process.argv.includes('--json') ? JSON.stringify(value) : encode(value));
+    try {
+        if (process.argv.length === 3 && ['--version', '-v', '-V'].includes(process.argv[2])) {
+            console.log(VERSION);
+            return;
+        }
+        const parsed = parseArguments(process.argv.slice(2));
+        if (parsed.config || process.argv.includes('--profile'))
+            throw new SshError('USAGE', 'Hosted profile overrides are refused.', 2);
+        const context = message;
+        if (context.revision !== 1 || !Array.isArray(context.hosts))
+            throw new SshError('IPC_INVALID', 'Incompatible host context.');
+        if (context.execution) {
+            if (context.hosts.length !== 1)
+                throw new SshError('IPC_INVALID', 'A single selected execution host is required.');
+            const cancellation = new AbortController();
+            const cancel = () => cancellation.abort();
+            process.on('message', (value) => {
+                if (value && typeof value === 'object' && 'cancel' in value && value.cancel === true)
+                    cancel();
+            });
+            process.once('SIGTERM', cancel);
+            process.once('SIGINT', cancel);
+            try {
+                const selected = selectProfile(loadConfiguration(configPath()), 'artium');
+                const result = await executeCommand(selected.profile, context.execution, cancellation.signal);
+                output(result);
+                process.exitCode = result.outcome === 'completed' ? 0 : 1;
+            }
+            finally {
+                process.off('SIGTERM', cancel);
+                process.off('SIGINT', cancel);
+            }
+            return;
+        }
+        if (parsed.help) {
+            output({ description: 'Discover granted hosts and run confirmed bounded commands.', commands: ['host list', 'host show <host>', 'doctor <host>', 'exec <host> --command <text> --confirm', 'execution list', 'execution show <id>', 'execution cancel <id> --confirm'], flags: '--help, --json' });
+        }
+        else if (parsed.command === '' || parsed.command === 'host list') {
+            output({ hosts: context.hosts, count: context.hosts.length,
+                ...(context.hosts.length ? {} : { message: 'No granted hosts found.' }), help: ['ssh-axi host show <host>', 'ssh-axi doctor <host>'] });
+        }
+        else {
+            const host = context.hosts.find(host => host.id === parsed.profile);
+            if (!host)
+                throw new SshError('NOT_FOUND', 'Host not found.');
+            if (parsed.command === 'host show')
+                output({ host });
+            else if (parsed.command === 'doctor') {
+                const selected = selectProfile(loadConfiguration(configPath()), 'artium');
+                output({ host: host.id, ...await doctor(selected.profile), commandsExecuted: 0 });
+            }
+            else
+                throw new SshError('USAGE', 'Use host list, host show <host> or doctor <host>.', 2);
+        }
+    }
+    catch (error) {
+        const safe = error instanceof SshError ? error : new SshError('HOSTED_FAILED', 'The hosted SSH check failed.');
+        output({ error: { code: safe.code, message: safe.message } });
+        process.exitCode = safe.exitCode;
+    }
+    finally {
+        if (process.connected)
+            process.disconnect();
+    }
+});

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { VERSION } from './version.js';
+import { tryFastPath } from 'axi-sdk-js/fast-path';
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+    const { main } = await import('./cli.js');
+    await main(process.argv.slice(2));
+}

package/dist/native-execution.d.ts

@@ -0,0 +1,21 @@
+import { type Profile } from './profile.js';
+import type { parseArguments } from './arguments.js';
+export declare function executeNative(host: string, profile: Profile, parsed: ReturnType<typeof parseArguments>): Promise<{
+    finishedAt: string;
+    help: string[];
+    address: string;
+    outcome: "completed" | "failed" | "cancelled" | "timed_out" | "unknown";
+    remoteExit: number | null;
+    remoteSignal: string | null;
+    termination: "remote-exit" | "unknown";
+    stdout: ReturnType<import("./output.js").Output["finish"]>;
+    stderr: ReturnType<import("./output.js").Output["finish"]>;
+    durationMs: number;
+    diagnostic?: string;
+    id: string;
+    host: string;
+    account: string;
+    sudo: boolean;
+    connectionId: null;
+    startedAt: string;
+}>;

package/dist/native-execution.js

@@ -0,0 +1,53 @@
+import { constants, openSync, closeSync, fsyncSync, writeFileSync, fstatSync, mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { executeCommand } from './doctor.js';
+import { checkCommand } from './output.js';
+import { readPrivateFile, resolveSecret } from './profile.js';
+import { SshError } from './errors.js';
+export async function executeNative(host, profile, parsed) {
+    if (parsed.values.confirm !== true)
+        throw new SshError('CONFIRM_REQUIRED', 'Every arbitrary command requires --confirm.', 2);
+    if (process.env.SSH_AXI_READ_ONLY && process.env.SSH_AXI_READ_ONLY !== 'false' && process.env.SSH_AXI_READ_ONLY !== '0')
+        throw new SshError('READ_ONLY', 'Arbitrary execution is disabled by read-only policy.');
+    if (parsed.values.sudo || parsed.values.detach || parsed.values['request-key'] || parsed.values.connection)
+        throw new SshError('HOSTED_REQUIRED', 'This option requires a managed execution and matching host grants.');
+    if (typeof parsed.values.command !== 'string')
+        throw new SshError('USAGE', 'Use --command <text> --confirm.', 2);
+    const command = parsed.values.command;
+    checkCommand(command, [resolveSecret(profile.privateKey, 'SSH_AXI_PRIVATE_KEY', true), resolveSecret(profile.passphrase, 'SSH_AXI_PASSPHRASE', false) ?? '']);
+    const state = process.platform === 'win32' ? process.env.LOCALAPPDATA : process.env.XDG_STATE_HOME && isAbsolute(process.env.XDG_STATE_HOME)
+        ? process.env.XDG_STATE_HOME : join(homedir(), '.local', 'state');
+    if (!state || process.platform === 'win32')
+        throw new SshError('PLATFORM_PENDING', 'Native Windows custody validation is pending.');
+    const file = process.env.SSH_AXI_WRITE_LOG ?? join(state, 'ssh-axi', 'writes.log');
+    if (!isAbsolute(file))
+        throw new SshError('CONFIG_INSECURE', 'Write journal path must be absolute.');
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    // Reuse the private-file ownership/parent checks before appending.
+    const descriptor = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    const id = `exec_${randomUUID()}`;
+    const startedAt = new Date().toISOString();
+    try {
+        readPrivateFile(file, true);
+        if (!fstatSync(descriptor).isFile())
+            throw new SshError('CONFIG_INSECURE', 'Journal must be a private regular file.');
+        writeFileSync(descriptor, JSON.stringify({ id, host, command, confirmed: true, startedAt, outcome: 'unknown' }) + '\n');
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    const cancellation = new AbortController();
+    const cancel = () => cancellation.abort();
+    process.once('SIGINT', cancel);
+    try {
+        return { id, host, account: profile.username, sudo: false, connectionId: null, startedAt,
+            ...await executeCommand(profile, { command, timeout: parsed.timeout, outputLimit: parsed.outputLimit }, cancellation.signal),
+            finishedAt: new Date().toISOString(), help: ['Inspect remote state before retrying an uncertain execution. No automatic replay.'] };
+    }
+    finally {
+        process.off('SIGINT', cancel);
+    }
+}

package/dist/output.d.ts

@@ -0,0 +1,29 @@
+export declare function secretPatterns(secrets: readonly string[]): string[];
+export declare function containsSecret(value: string, patterns: readonly string[]): boolean;
+export declare function checkCommand(command: string, secrets: readonly string[]): void;
+export declare class Output {
+    private readonly patterns;
+    private readonly limit;
+    private readonly decoder;
+    private tail;
+    private text;
+    private terminal;
+    private readonly window;
+    receivedBytes: number;
+    retainedBytes: number;
+    truncated: boolean;
+    encodingLoss: boolean;
+    withheld: boolean;
+    constructor(patterns: readonly string[], limit: number);
+    push(bytes: Buffer): void;
+    private consume;
+    finish(): {
+        text: string;
+        receivedBytes: number;
+        retainedBytes: number;
+        truncated: boolean;
+        encodingLoss: boolean;
+        withheld: boolean;
+        unit: "bytes";
+    };
+}