@knowttl/ssh-axi 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# ssh-axi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Discover approved SSH hosts, check encrypted-key authentication, and execute confirmed bounded commands.
+Requires Node >=24.11.0 and pnpm 10.22.0.
+The npm package is `@knowttl/ssh-axi`; its executable is `ssh-axi`.
+
+```sh
+ssh-axi
+ssh-axi host list
+ssh-axi host show lab
+ssh-axi doctor lab --json
+ssh-axi doctor --profile lab
+ssh-axi auth status --profile lab
+ssh-axi profile list
+ssh-axi config path
+ssh-axi exec lab --command 'printf "%s\n" "quoted value"' --confirm --timeout 30s --json
+```
+
+Output defaults to TOON; `--json` returns the same fields and empty-state meaning.
+Each command accepts `--help`.
+Unknown arguments and flags fail with exit code 2; operational failures use exit code 1.
+Help, discovery, profile inspection and credential status open no SSH transports.
+Native execution is one-shot.
+Managed execution records, recovery and cancellation use the matching Artium host extension.
+Reusable connections require the matching Artium connection-lifetime extension.
+Managed sudo requires a distinct approved account and SSH credential with a current sudo grant.
+Agents, forwarding and interactive shells remain unavailable.
+
+Configuration lives at `~/.config/ssh-axi/config.json` on Linux, or beneath an absolute `XDG_CONFIG_HOME`.
+Select a file with `--config` or `SSH_AXI_CONFIG`.
+Profiles use the following template; replace the address, allowed IP and independently verified host key before use.
+
+```json
+{
+  "version": 1,
+  "defaultProfile": "lab",
+  "profiles": {
+    "lab": {
+      "address": "127.0.0.1",
+      "port": 2222,
+      "username": "ordinary",
+      "allowedAddresses": ["127.0.0.1"],
+      "approvedHostKeys": ["ssh-ed25519 <independently-verified-base64-key>"],
+      "privateKey": {"file": "/absolute/private/key.pem"},
+      "passphrase": {"env": "LAB_KEY_PASSPHRASE"}
+    }
+  }
+}
+```
+
+The strict profile contract is shipped as `axi-credential.schema.json`.
+Keys and passphrases accept environment or protected-file SecretRefs only.
+Secret values and inline private keys are refused in JSON and arguments.
+An omitted private-key reference defaults to `SSH_AXI_PRIVATE_KEY`; the passphrase defaults to `SSH_AXI_PASSPHRASE`.
+`auth status` reports credential availability and sources as `env:<name>` or `protected file`, without displaying secret values or file paths or checking network authentication.
+Linux secret files must be owned by the caller, regular, protected from group/other access and reachable through protected directories without symlinks.
+Configuration files must also be owned and protected against group/other writes.
+
+Profile precedence is explicit host/`--profile`, `SSH_AXI_PROFILE`, a complete environment profile, the default profile, then the only profile.
+An explicitly selected file profile ignores competing endpoint environment fields.
+Environment profiles use `SSH_AXI_ADDRESS`, `SSH_AXI_PORT`, `SSH_AXI_USERNAME`, JSON arrays in `SSH_AXI_APPROVED_HOST_KEYS` and `SSH_AXI_ALLOWED_ADDRESSES`, and the secret environment fields above.
+Partial environment profiles fail.
+No SSH config, agent, known-hosts file or ambient key is consulted.
+
+Every new transport, including doctor probes and reusable connections, validates every resolved IP against the configured address set and dials the exact validated IP.
+An exact approved server public key is required before sending authentication credentials.
+The authentication deadline is 15 seconds, including resolution and connection setup.
+Doctor requests no SSH channel and closes its socket, probe worker and private directories before returning.
+Private-key buffers are released where supported; JavaScript strings and process termination do not provide a secure-erasure guarantee.
+
+Artium supplies authenticated host grants, separate ordinary and sudo account bindings, encrypted SSH credentials, private IPC and one isolated `artium` profile through its shared writer.
+Hosted callers may list and show their granted hosts, run doctor and submit confirmed commands when the host write policy permits.
+They cannot supply configuration, account, trust, secret, identity or worker overrides.
+The matching Artium admission change must be installed alongside this artifact; stock Artium does not admit it.
+The matching host extension provides `/admin/ssh` for confirmed, revision-checked host, trust, binding and grant changes.
+Server keys require independent verification and at most two approved keys may overlap during rotation.
+Host and credential administration have separate delegated permissions; only credential administrators can replace or delete encrypted SSH secrets, which are never displayed.
+SSH credential identifiers cannot resolve credentials for other tools.
+Changes fence affected connections before acknowledgement.
+The corresponding authenticated APIs live under `/v1/admin/ssh/`.
+
+Every arbitrary command requires `--confirm`, including inspection-looking commands.
+`SSH_AXI_READ_ONLY=true` rejects arbitrary execution before opening a transport or writing a command journal.
+Commands must contain 1-16384 UTF-8 bytes and no NUL.
+Known managed secrets and encoded variants are rejected before command journaling.
+Native command intents are written durably to `~/.local/state/ssh-axi/writes.log`, or the absolute `XDG_STATE_HOME` override.
+`SSH_AXI_WRITE_LOG` selects an absolute protected journal path.
+No local shell is invoked; the exact command text is sent to the remote SSH exec channel.
+Remote stdin is closed without forwarding input; both output streams continue draining.
+Native Ctrl+C requests cancellation through the private worker.
+
+```sh
+artium-axi ssh-axi exec lab --command 'systemctl --failed' --confirm --detach
+artium-axi ssh-axi execution list --json
+artium-axi ssh-axi execution show <id> --full
+artium-axi ssh-axi execution show --request-key <key>
+artium-axi ssh-axi execution show
+artium-axi ssh-axi execution cancel <id> --confirm
+artium-axi ssh-axi connection open lab --idle-timeout 10m
+artium-axi ssh-axi connection list
+artium-axi ssh-axi connection show <connection-id>
+artium-axi ssh-axi connection set <connection-id> --idle-timeout 5m
+artium-axi ssh-axi exec lab --connection <connection-id> --command 'pwd' --confirm
+artium-axi ssh-axi exec lab --sudo --command 'printf "%s\n" "value" | cat' --confirm
+artium-axi ssh-axi connection close <connection-id>
+```
+
+Hosted connections belong to one authenticated user and login session family.
+Each command starts a fresh remote process on the same transport.
+An explicit connection must match the selected host and ordinary or sudo binding, with no fallback reconnection.
+Sudo dispatch sends `sudo -n -- /bin/sh -c <quoted-command>` through its own matching connection.
+Pipelines and redirects remain inside that privileged shell.
+Password-required or terminal-required sudo returns `SUDO_DENIED` with administrator guidance.
+Controlled peers establish account, key and command selection only.
+Actual ordinary-account non-elevation and successful non-root passwordless elevation remain commissioning checks.
+There is one active command per connection; overlapping use returns `CONNECTION_BUSY`.
+Closing an active connection requires `--confirm` and cancels its command.
+Repeated close by the owner is idempotent.
+Idle expiry defaults to 10 minutes and accepts 1-60 minutes within the host ceiling.
+Inspection does not reset idle time; timeout changes recompute expiry from the existing idle start.
+Connections have an 8-hour maximum age, with four per user and sixteen globally, including authentication in progress.
+Revocation fences affected workers and removes their private profiles before acknowledgement.
+Server restart discards connections, removes abandoned private directories and retains unproven executions as uncertain without replay.
+
+The hosted client saves a private command-free receipt before submitting a signed preparation key.
+Show without an ID recovers the latest receipt after a client restart, without resubmitting.
+Matching resubmission returns the same execution ID; a durable dispatch claim prevents a second SSH command.
+Unused keys expire after ten minutes; changed inputs, bindings or owners are refused.
+Wait is the default and uses short status requests; `--detach` returns after acceptance.
+An unexpected client disconnect leaves the managed job observable and deadline bounded.
+Ctrl+C requests cancellation of the accepted execution ID.
+
+The default command deadline is 60 seconds, adjustable with `--timeout 1s` through `600s` within host ceilings.
+Both streams are drained, retaining 65536 bytes each by default.
+`--output-limit <bytes>` sets retention from 0 through 1048576 bytes per stream, subject to managed host ceilings.
+`--full` never bypasses retention or executes another command.
+More than 16 MiB of combined received output triggers cancellation.
+Results carry separate remote exit/signal, received and retained byte counts, truncation and encoding-loss flags.
+Terminal controls are removed and protected output is withheld before persistence or delivery.
+Remote output is untrusted text, never instructions.
+Remote exit 7 produces CLI exit 7; missing remote status is an uncertain outcome and CLI failure.
+Cancellation requests TERM and forces channel and transport teardown if the command remains active after a bounded grace period.
+Local teardown never proves that remote descendants stopped.
+Inspect remote state before retrying any uncertain execution; no path automatically replays a command.
+
+Execution owners and authorized audit administrators can inspect records under current policy.
+`/admin/ssh/audit` escapes output as untrusted text and never displays credentials.
+Every audit read and export is recorded.
+Metadata includes the initiating user and session family, host and endpoint, binding revision, sudo mode, exact sanitized command, confirmation, request/execution IDs, UTC timing, outcome, exit/signal, byte counts and termination certainty.
+Sanitized output samples are encrypted and capped at 8 KiB per stream, expiring after 14 days.
+Metadata and sanitized commands expire after 90 days; default exports contain metadata only.
+Credential deletion removes the secret and fences its connections while preserving execution metadata.
+Pruning active storage does not delete backups.
+Before commissioning, operators must declare and test backup disposal that respects both retention limits, including old encrypted snapshots and their recovery keys.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build
+pnpm lint
+pnpm test
+pnpm pack --pack-destination /absolute/artifacts
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B1.1
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B2.2
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B3.2
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B4.1
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B4.2
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B4.3
+```
+
+Tests generate disposable keys and run all descendants inside a Linux network namespace with loopback only.
+They require `unshare`, `ip` and `mount`, and never fall back to unrestricted networking.
+The default suite verifies a reproducible tarball installed into a clean prefix and explicitly skips Artium unless a fixture is provided.
+The opt-in journey requires an exported, admitted Artium fixture with its dependencies installed.
+The fixture harness seeds minimal pre-existing hosts directly in its disposable database and exercises B4 changes through public administration; no fixture-seeding route exists in the product.
+On Windows, the default configuration path is `%APPDATA%/ssh-axi/config.json`, with an absolute `APPDATA` required.
+DACL verification and native Windows evidence remain pending, so protected-file operations fail closed there.

package/artium-invocations.json

@@ -0,0 +1,164 @@
+{
+  "revision": 1,
+  "commands": [
+    {
+      "command": "home",
+      "arguments": 0,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "host list",
+      "arguments": 0,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "host show",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "doctor",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "auth status",
+      "arguments": 0,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "profile list",
+      "arguments": 0,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "config path",
+      "arguments": 0,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "exec",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean",
+        "command": "string",
+        "confirm": "boolean",
+        "timeout": "string",
+        "output-limit": "string",
+        "detach": "boolean",
+        "request-key": "string",
+        "sudo": "boolean",
+        "connection": "string"
+      },
+      "effect": "write"
+    },
+    {
+      "command": "connection open",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean",
+        "idle-timeout": "string",
+        "sudo": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "connection list",
+      "arguments": 0,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "connection show",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "connection set",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean",
+        "idle-timeout": "string"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "connection close",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean",
+        "confirm": "boolean"
+      },
+      "effect": "write"
+    },
+    {
+      "command": "execution list",
+      "arguments": 0,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "execution show",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean",
+        "request-key": "string",
+        "full": "boolean"
+      },
+      "effect": "read"
+    },
+    {
+      "command": "execution cancel",
+      "arguments": 1,
+      "flags": {
+        "help": "boolean",
+        "json": "boolean",
+        "confirm": "boolean"
+      },
+      "effect": "write"
+    }
+  ]
+}

package/axi-credential.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SSH profile",
+  "x-protocol-revision": 1,
+  "x-connection-protocol-revision": 2,
+  "x-commands": {
+    "": { "arguments": 0, "description": "Discover configured SSH hosts" },
+    "host list": { "arguments": 0, "description": "List approved hosts without opening a transport" },
+    "host show": { "arguments": 1, "description": "Show one approved host without opening a transport" },
+    "doctor": { "arguments": 1, "description": "Authenticate to one host without executing a remote command" },
+    "auth status": { "arguments": 0, "description": "Inspect selected credential sources offline" },
+    "profile list": { "arguments": 0, "description": "List configured profiles offline" },
+    "config path": { "arguments": 0, "description": "Show the configuration path offline" },
+    "exec": { "arguments": 1, "description": "Execute one confirmed arbitrary command", "flags": { "command": "string", "confirm": "boolean", "timeout": "string", "output-limit": "string", "detach": "boolean", "request-key": "string", "sudo": "boolean", "connection": "string" } },
+    "connection open": { "arguments": 1, "description": "Open a private hosted connection", "flags": { "idle-timeout": "string", "sudo": "boolean" } },
+    "connection list": { "arguments": 0, "description": "List caller-owned hosted connections" },
+    "connection show": { "arguments": 1, "description": "Show a caller-owned hosted connection" },
+    "connection set": { "arguments": 1, "description": "Change a hosted connection idle timeout", "flags": { "idle-timeout": "string" } },
+    "connection close": { "arguments": 1, "description": "Close a caller-owned hosted connection", "flags": { "confirm": "boolean" } },
+    "execution list": { "arguments": 0, "description": "List caller-owned executions" },
+    "execution show": { "arguments": 1, "description": "Recover an execution without replay", "flags": { "request-key": "string", "full": "boolean" } },
+    "execution cancel": { "arguments": 1, "description": "Cancel one caller-owned execution", "flags": { "confirm": "boolean" } }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["address", "port", "username", "approvedHostKeys", "allowedAddresses"],
+  "properties": {
+    "address": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[A-Za-z0-9.:_-]+$", "description": "Approved SSH hostname or IP address; every resolved address must be allowed." },
+    "port": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Approved SSH TCP port." },
+    "username": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_.-]+$", "description": "Ordinary SSH account selected by the host binding." },
+    "approvedHostKeys": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "description": "Independently verified server public keys, each as algorithm plus base64 key; at most two overlap during rotation.", "items": { "type": "string", "pattern": "^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)) [A-Za-z0-9+/]+={0,2}$" } },
+    "allowedAddresses": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Approved literal IPv4 or IPv6 addresses; DNS cannot expand this set.", "items": { "type": "string", "minLength": 2 } },
+    "privateKey": { "$ref": "#/definitions/secretRef", "x-secret": true },
+    "passphrase": { "$ref": "#/definitions/secretRef", "x-secret": true }
+  },
+  "definitions": {
+    "secretRef": {
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["env"], "properties": { "env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
+        { "type": "object", "additionalProperties": false, "required": ["file"], "properties": { "file": { "type": "string", "minLength": 1 } } }
+      ]
+    }
+  }
+}

package/dist/arguments.d.ts

@@ -0,0 +1,17 @@
+export declare const commands: Record<string, {
+    arguments: number;
+    description: string;
+    flags?: Record<string, string>;
+}>;
+export declare const flagHelp = "--json, --help, --config <absolute-path>, --profile <name>";
+export declare function parseArguments(args: readonly string[]): {
+    command: string;
+    json: boolean;
+    help: boolean;
+    config: string | undefined;
+    profile: string | undefined;
+    values: Record<string, string | boolean>;
+    timeout: number;
+    outputLimit: number;
+    id: string | undefined;
+};

package/dist/arguments.js

@@ -0,0 +1,71 @@
+import schema from '../axi-credential.schema.json' with { type: 'json' };
+import { SshError } from './errors.js';
+export const commands = schema['x-commands'];
+export const flagHelp = '--json, --help, --config <absolute-path>, --profile <name>';
+export function parseArguments(args) {
+    let prefix = 0;
+    while (['--json', '--help', '--config', '--profile'].includes(args[prefix]))
+        prefix += ['--config', '--profile'].includes(args[prefix]) ? 2 : 1;
+    const commandName = args[prefix] === 'exec' || args[prefix] === 'doctor' ? args[prefix] : args.slice(prefix, prefix + 2).join(' ');
+    const extraFlags = commands[commandName]?.flags ?? {};
+    const values = {};
+    const positional = [];
+    let json = false;
+    let help = false;
+    let config;
+    let profile;
+    const seen = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (!arg.startsWith('-')) {
+            positional.push(arg);
+            continue;
+        }
+        if (!['--json', '--help', '--config', '--profile', ...Object.keys(extraFlags).map(key => `--${key}`)].includes(arg)) {
+            throw new SshError('USAGE', `Unknown flag. Valid flags: ${flagHelp}${Object.keys(extraFlags).map(key => `, --${key}`).join('')}.`, 2);
+        }
+        if (seen.has(arg))
+            throw new SshError('USAGE', 'Flags may only appear once.', 2);
+        seen.add(arg);
+        if (arg === '--json')
+            json = true;
+        else if (arg === '--help')
+            help = true;
+        else if (extraFlags[arg.slice(2)] === 'boolean')
+            values[arg.slice(2)] = true;
+        else {
+            const value = args[++index];
+            if (value === undefined || (arg !== '--command' && (!value || value.startsWith('-'))))
+                throw new SshError('USAGE', `A flag value is required. Valid flags: ${flagHelp}.`, 2);
+            if (arg === '--config')
+                config = value;
+            else if (arg === '--profile')
+                profile = value;
+            else
+                values[arg.slice(2)] = value;
+        }
+    }
+    const command = ['doctor', 'exec'].includes(positional[0]) ? positional[0] : positional.slice(0, 2).join(' ');
+    const definition = commands[command];
+    const count = command === '' ? 0 : ['doctor', 'exec'].includes(command) ? 1 : 2;
+    const selectedDoctor = command === 'doctor' && positional.length === count;
+    const receiptLookup = command === 'execution show' && positional.length === count;
+    if (!definition || positional.length !== count + definition.arguments && !selectedDoctor && !receiptLookup && !(help && positional.length === count)) {
+        throw new SshError('USAGE', 'Use ssh-axi host list, host show <host>, doctor <host>, exec <host> --command <text> --confirm, or execution list/show/cancel.', 2);
+    }
+    if (['doctor', 'host show', 'exec'].includes(command) && positional[count] !== undefined) {
+        if (profile !== undefined)
+            throw new SshError('USAGE', 'Use the host argument to select the profile for this command.', 2);
+        profile = positional[count];
+    }
+    if (command === 'execution show' && positional[count] && values['request-key'])
+        throw new SshError('USAGE', 'Use an execution ID or --request-key, not both.', 2);
+    const timeoutValue = values.timeout ?? '60s';
+    const timeout = typeof timeoutValue === 'string' && /^\d+s?$/.test(timeoutValue) ? Number(timeoutValue.replace(/s$/, '')) : NaN;
+    const outputValue = values['output-limit'] ?? '65536';
+    const outputLimit = typeof outputValue === 'string' && /^\d+$/.test(outputValue) ? Number(outputValue) : NaN;
+    if (command === 'exec' && (!Number.isInteger(timeout) || timeout < 1 || timeout > 600 || !Number.isInteger(outputLimit) || outputLimit < 0 || outputLimit > 1024 * 1024)) {
+        throw new SshError('USAGE', 'Use --timeout 1s-600s and --output-limit 0-1048576 (bytes).', 2);
+    }
+    return { command, json, help, config, profile, values, timeout, outputLimit, id: positional[count] };
+}

package/dist/authenticate.d.ts

@@ -0,0 +1,30 @@
+import { type Profile } from './profile.js';
+import { Output } from './output.js';
+export declare const AUTHENTICATION_DEADLINE_MS = 15000;
+export interface ExecutionSettings {
+    command: string;
+    timeout: number;
+    outputLimit: number;
+}
+export interface ExecutionResult {
+    address: string;
+    outcome: 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'unknown';
+    remoteExit: number | null;
+    remoteSignal: string | null;
+    termination: 'remote-exit' | 'unknown';
+    stdout: ReturnType<Output['finish']>;
+    stderr: ReturnType<Output['finish']>;
+    durationMs: number;
+    diagnostic?: string;
+}
+export declare function authenticate(profile: Profile): Promise<{
+    authenticated: true;
+    address: string;
+}>;
+export declare function execute(profile: Profile, settings: ExecutionSettings, signal?: AbortSignal): Promise<ExecutionResult>;
+export declare function openTransport(profile: Profile, signal?: AbortSignal): Promise<{
+    address: string;
+    disconnected: Promise<void>;
+    close: () => Promise<void>;
+    execute(settings: ExecutionSettings, signal?: AbortSignal): Promise<ExecutionResult>;
+}>;