@knowttl/ssh-axi 0.0.0-stage → 0.1.1

package/dist/output.js

@@ -0,0 +1,98 @@
+import { SshError } from './errors.js';
+// Share the same vocabulary at command admission, worker output and the parent
+// boundary. Values never become diagnostics or persisted scanner state.
+export function secretPatterns(secrets) {
+    return [...new Set(secrets.filter(Boolean).flatMap(secret => {
+            const values = [secret, ...secret.split(/\r?\n/).filter(line => line.length >= 16)];
+            return values.flatMap(value => [value, JSON.stringify(value).slice(1, -1),
+                encodeURIComponent(value), Buffer.from(value).toString('base64'), Buffer.from(value).toString('base64url'),
+                Buffer.from(value).toString('hex'), Buffer.from(value).toString('hex').toUpperCase(),
+                [...value].map(character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`).join('')]);
+        }))];
+}
+export function containsSecret(value, patterns) {
+    return patterns.some(pattern => value.includes(pattern))
+        || /-----BEGIN [A-Z ]*PRIVATE KEY-----|(?:Bearer |gh[pousr]_|github_pat_)[A-Za-z0-9_./+=-]{16,}/i.test(value);
+}
+export function checkCommand(command, secrets) {
+    if (command.includes('\0') || Buffer.byteLength(command) > 16 * 1024 || !command.length) {
+        throw new SshError('COMMAND_INVALID', 'Commands must contain 1-16384 UTF-8 bytes and no NUL.', 2);
+    }
+    if (containsSecret(command, secretPatterns(secrets)))
+        throw new SshError('SECRET_IN_COMMAND', 'Command contains protected material; nothing was journaled or dispatched.');
+}
+export class Output {
+    patterns;
+    limit;
+    decoder = new TextDecoder('utf-8');
+    tail = '';
+    text = '';
+    terminal = 'text';
+    window;
+    receivedBytes = 0;
+    retainedBytes = 0;
+    truncated = false;
+    encodingLoss = false;
+    withheld = false;
+    constructor(patterns, limit) {
+        this.patterns = patterns;
+        this.limit = limit;
+        this.window = Math.max(256, ...patterns.map(pattern => pattern.length));
+    }
+    push(bytes) {
+        this.receivedBytes += bytes.length;
+        this.consume(this.decoder.decode(bytes, { stream: true }));
+    }
+    consume(value) {
+        this.encodingLoss ||= value.includes('\uFFFD');
+        const scan = this.tail + value;
+        this.withheld ||= containsSecret(scan, this.patterns);
+        this.tail = scan.slice(-this.window);
+        if (this.withheld) {
+            this.text = '';
+            this.retainedBytes = 0;
+            return;
+        }
+        // Escape sequences can span chunks. Keep only the parser state, never an
+        // unbounded pending OSC title or CSI parameter string.
+        let safe = '';
+        for (const character of value) {
+            if (this.terminal === 'osc' || this.terminal === 'oscEscape') {
+                if (character === '\x07' || character === '\x9c' || this.terminal === 'oscEscape' && character === '\\')
+                    this.terminal = 'text';
+                else
+                    this.terminal = character === '\x1b' ? 'oscEscape' : 'osc';
+            }
+            else if (this.terminal === 'csi') {
+                if (character >= '@' && character <= '~')
+                    this.terminal = 'text';
+            }
+            else if (this.terminal === 'escape') {
+                this.terminal = character === '[' ? 'csi' : character === ']' ? 'osc' : 'text';
+            }
+            else if (character === '\x1b')
+                this.terminal = 'escape';
+            else if (character === '\x9b')
+                this.terminal = 'csi';
+            else if (character === '\x9d')
+                this.terminal = 'osc';
+            else if (!/[\x00-\x08\x0b-\x1f\x7f-\x9f]/.test(character))
+                safe += character;
+        }
+        const bytes = Buffer.from(safe);
+        const remaining = this.limit - this.retainedBytes;
+        let retained = bytes.subarray(0, remaining).toString('utf8');
+        // Do not introduce a replacement character by splitting a retained codepoint.
+        if (bytes.length > remaining)
+            retained = retained.replace(/\uFFFD$/, '');
+        this.text += retained;
+        this.retainedBytes += Buffer.byteLength(retained);
+        this.truncated ||= bytes.length > remaining;
+    }
+    finish() {
+        this.consume(this.decoder.decode());
+        return { text: this.withheld ? '' : this.text, receivedBytes: this.receivedBytes,
+            retainedBytes: this.retainedBytes, truncated: this.truncated, encodingLoss: this.encodingLoss,
+            withheld: this.withheld, unit: 'bytes' };
+    }
+}

package/dist/profile.d.ts

@@ -0,0 +1,29 @@
+export type SecretRef = {
+    env: string;
+} | {
+    file: string;
+};
+export interface Profile {
+    address: string;
+    port: number;
+    username: string;
+    approvedHostKeys: string[];
+    allowedAddresses: string[];
+    privateKey?: SecretRef;
+    passphrase?: SecretRef;
+}
+export interface Configuration {
+    version: 1;
+    defaultProfile?: string;
+    profiles: Record<string, Profile>;
+}
+export declare function validateProfile(value: unknown): Profile;
+export declare function configPath(explicit?: string): string;
+export declare function openPrivateFile(file: string, secret: boolean): number;
+export declare function readPrivateFile(file: string, secret: boolean): string;
+export declare function loadConfiguration(file: string): Configuration;
+export declare function selectProfile(config: Configuration, explicit?: string): {
+    name: string;
+    profile: Profile;
+};
+export declare function resolveSecret(reference: SecretRef | undefined, fallback: string, required: boolean): string | undefined;

package/dist/profile.js

@@ -0,0 +1,133 @@
+import { readFileSync, lstatSync, openSync, fstatSync, closeSync, constants } from 'node:fs';
+import { dirname, isAbsolute, join, parse, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { isIP } from 'node:net';
+import { Ajv } from 'ajv';
+import schema from '../axi-credential.schema.json' with { type: 'json' };
+import { SshError } from './errors.js';
+const validate = new Ajv({ strict: false }).compile(schema);
+const profileName = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+export function validateProfile(value) {
+    if (!validate(value) || value.allowedAddresses.some(address => !isIP(address))) {
+        throw new SshError('CONFIG_INVALID', 'Invalid SSH profile; use the packaged credential schema. Secret fields require env or file references.');
+    }
+    return value;
+}
+export function configPath(explicit) {
+    if (explicit || process.env.SSH_AXI_CONFIG)
+        return resolve(explicit ?? process.env.SSH_AXI_CONFIG);
+    const base = process.platform === 'win32'
+        ? process.env.APPDATA
+        : process.env.XDG_CONFIG_HOME && isAbsolute(process.env.XDG_CONFIG_HOME) ? process.env.XDG_CONFIG_HOME : join(homedir(), '.config');
+    if (!base || !isAbsolute(base))
+        throw new SshError('CONFIG_INVALID', 'An absolute configuration directory is required.');
+    return join(base, 'ssh-axi', 'config.json');
+}
+export function openPrivateFile(file, secret) {
+    if (!isAbsolute(file))
+        throw new SshError('CONFIG_INSECURE', 'Private file paths must be absolute.');
+    // Until native DACL verification is available, Windows custody fails closed.
+    if (process.platform === 'win32')
+        throw new SshError('PLATFORM_PENDING', 'Native Windows file custody validation is pending.');
+    let parent = dirname(file);
+    while (parent !== parse(parent).root) {
+        const info = lstatSync(parent);
+        if (!info.isDirectory() || info.isSymbolicLink() || (info.uid !== process.getuid() && info.uid !== 0)
+            || ((info.mode & 0o022) !== 0 && !(info.uid === 0 && (info.mode & 0o1000) !== 0))) {
+            throw new SshError('CONFIG_INSECURE', `Private file parent ${JSON.stringify(parent)} must be an actual directory owned by this user or root and protected against replacement. Remove group write access with chmod g-w (and other write access with chmod o-w), or select a protected location.`);
+        }
+        parent = dirname(parent);
+    }
+    const descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const info = fstatSync(descriptor);
+        if (!info.isFile() || info.uid !== process.getuid() || (info.mode & (secret ? 0o077 : 0o022)) !== 0) {
+            throw new SshError('CONFIG_INSECURE', 'Private files must be regular, owned by this user and protected.');
+        }
+        return descriptor;
+    }
+    catch (error) {
+        closeSync(descriptor);
+        throw error;
+    }
+}
+export function readPrivateFile(file, secret) {
+    const descriptor = openPrivateFile(file, secret);
+    try {
+        return readFileSync(descriptor, 'utf8').replace(/^\uFEFF/, '').trimEnd();
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+export function loadConfiguration(file) {
+    let value;
+    try {
+        value = JSON.parse(readPrivateFile(file, false));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { version: 1, profiles: {} };
+        if (error instanceof SshError)
+            throw error;
+        throw new SshError('CONFIG_INVALID', 'Cannot read the protected SSH configuration.');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new SshError('CONFIG_INVALID', 'Invalid configuration object.');
+    const config = value;
+    if (Object.keys(config).some(key => !['version', 'defaultProfile', 'profiles'].includes(key)) || config.version !== 1
+        || !config.profiles || typeof config.profiles !== 'object' || Array.isArray(config.profiles)) {
+        throw new SshError('CONFIG_INVALID', 'Expected configuration version 1 with named profiles.');
+    }
+    for (const [name, profile] of Object.entries(config.profiles)) {
+        if (!profileName.test(name))
+            throw new SshError('CONFIG_INVALID', 'Invalid profile name.');
+        validateProfile(profile);
+    }
+    if (config.defaultProfile !== undefined && (typeof config.defaultProfile !== 'string'
+        || !Object.hasOwn(config.profiles, config.defaultProfile)))
+        throw new SshError('CONFIG_INVALID', 'Default profile does not exist.');
+    return config;
+}
+export function selectProfile(config, explicit) {
+    const name = explicit ?? process.env.SSH_AXI_PROFILE;
+    if (name) {
+        const profile = Object.hasOwn(config.profiles, name) ? config.profiles[name] : undefined;
+        if (!profile)
+            throw new SshError('NOT_FOUND', 'Host not found.');
+        return { name, profile };
+    }
+    const fields = ['ADDRESS', 'PORT', 'USERNAME', 'APPROVED_HOST_KEYS', 'ALLOWED_ADDRESSES', 'PRIVATE_KEY', 'PASSPHRASE'];
+    if (fields.some(field => process.env[`SSH_AXI_${field}`] !== undefined)) {
+        let value;
+        try {
+            value = { address: process.env.SSH_AXI_ADDRESS, port: Number(process.env.SSH_AXI_PORT), username: process.env.SSH_AXI_USERNAME,
+                approvedHostKeys: JSON.parse(process.env.SSH_AXI_APPROVED_HOST_KEYS ?? 'null'),
+                allowedAddresses: JSON.parse(process.env.SSH_AXI_ALLOWED_ADDRESSES ?? 'null'), privateKey: { env: 'SSH_AXI_PRIVATE_KEY' },
+                ...(process.env.SSH_AXI_PASSPHRASE === undefined ? {} : { passphrase: { env: 'SSH_AXI_PASSPHRASE' } }) };
+        }
+        catch {
+            throw new SshError('CONFIG_INVALID', 'A complete environment profile is required.');
+        }
+        return { name: 'env', profile: validateProfile(value) };
+    }
+    const selected = config.defaultProfile ?? (Object.keys(config.profiles).length === 1 ? Object.keys(config.profiles)[0] : undefined);
+    if (!selected)
+        throw new SshError('PROFILE_REQUIRED', 'Select a configured host with --profile <name>.');
+    return { name: selected, profile: config.profiles[selected] };
+}
+export function resolveSecret(reference, fallback, required) {
+    const selected = reference ?? { env: fallback };
+    let value;
+    try {
+        value = 'env' in selected ? process.env[selected.env] : readPrivateFile(selected.file, true);
+    }
+    catch (error) {
+        if (error instanceof SshError)
+            throw error;
+        throw new SshError('KEY_UNAVAILABLE', 'The selected protected secret file is unavailable.');
+    }
+    if (!value && required)
+        throw new SshError('KEY_UNAVAILABLE', 'The selected private key is unavailable.');
+    return value;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,2 @@
+import { readFileSync } from 'node:fs';
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/dist/worker.d.ts

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

package/dist/worker.js

@@ -0,0 +1,33 @@
+import { authenticate, execute } from './authenticate.js';
+import { validateProfile } from './profile.js';
+import { SshError } from './errors.js';
+// No listener or public argv mode exists. Only the supervising parent's inherited
+// IPC channel can deliver one bounded authentication or execution request.
+if (!process.send || process.argv.length !== 2)
+    process.exit(2);
+const cancellation = new AbortController();
+process.on('message', (value) => {
+    if (value && typeof value === 'object' && 'cancel' in value && value.cancel === true)
+        cancellation.abort();
+});
+process.once('message', async (value) => {
+    try {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new SshError('IPC_INVALID', 'Invalid worker request.');
+        const request = value;
+        if (request.revision !== 1 || !['doctor', 'exec'].includes(String(request.operation))
+            || Object.keys(request).some(key => !['revision', 'operation', 'profile', 'settings'].includes(key)))
+            throw new SshError('IPC_INVALID', 'Incompatible worker protocol.');
+        const profile = validateProfile(request.profile);
+        const result = request.operation === 'doctor' ? await authenticate(profile)
+            : await execute(profile, request.settings, cancellation.signal);
+        process.exitCode = 0;
+        process.send({ ok: true, result }, undefined, undefined, () => process.disconnect());
+    }
+    catch (error) {
+        const safe = error instanceof SshError ? error : new SshError('AUTH_FAILED', 'SSH authentication failed.');
+        process.send({ ok: false, error: { code: safe.code, message: safe.message } }, undefined, undefined, () => process.disconnect());
+        process.exitCode = 1;
+    }
+});
+process.on('disconnect', () => process.exit(process.exitCode ?? 1));

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@knowttl/ssh-axi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Discover approved SSH hosts and execute confirmed bounded commands",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowttl/ssh-axi.git"
+  },
+  "type": "module",
+  "bin": {
+    "ssh-axi": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "axi-credential.schema.json",
+    "artium-invocations.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "packageManager": "pnpm@10.22.0",
+  "scripts": {
+    "build": "tsc",
+    "inventory:write": "node scripts/inventory.ts --write",
+    "lint": "tsc -p tsconfig.check.json && node scripts/inventory.ts",
+    "test": "pnpm build && node scripts/test.ts",
+    "verify:journey": "pnpm build && node scripts/journey.ts",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@toon-format/toon": "2.3.1",
+    "ssh2": "1.17.0",
+    "ajv": "8.17.1",
+    "axi-sdk-js": "0.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "@types/ssh2": "1.15.5",
+    "typescript": "5.9.3"
+  }
+}