@knowttl/ssh-axi 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,292 @@
-# 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.
+Agent-facing SSH CLI: discover approved hosts, check encrypted-key authentication and run confirmed, bounded commands.
+Arbitrary execution always requires explicit confirmation.
+
+[Quickstart](#quickstart) | [Commands](#commands) | [Safety](#safety) | [Configuration](#configuration) | [Output and exit codes](#output-and-exit-codes) | [Limitations](#limitations) | [Development](#development)
+
+## Why this exists
+
+Agents need remote shell access that is bounded, auditable and hard to misuse.
+`ssh-axi` returns compact TOON output (or `--json` with the same fields) with next-step hints, and bounds command time and output size.
+It consults only approved profiles: no SSH config, agent, known-hosts file or ambient key is read.
+Every arbitrary command requires `--confirm`, and server keys must be approved before credentials are sent.
+
+## Quickstart
+
+Requires Node >=24.11.0.
+
+```sh
+npm install --global @knowttl/ssh-axi
+ssh-axi
+```
+
+With no configuration, the home view lists no hosts and points to `ssh-axi config path`:
+
+```text
+description: Discover approved SSH hosts and run confirmed bounded commands.
+hosts: []
+count: 0
+message: No configured hosts found.
+```
+
+Create a profile (see [Configuration](#configuration)), then run the first authenticated read:
+
+```sh
+ssh-axi host list
+ssh-axi host show lab
+ssh-axi doctor lab --json
+ssh-axi exec lab --command 'printf "%s\n" "quoted value"' --confirm --timeout 30s --json
+```
+
+## Use with your agent
+
+No session hooks or agent skill ship with this package yet; this is pending.
+Agents call the CLI directly, and every command accepts `--help`.
+Managed execution, recovery, cancellation and reusable connections are available to hosted callers through Artium (see [Hosted use with Artium](#hosted-use-with-artium)).
+
+## Commands
+
+```sh
+ssh-axi                                  # home view
+ssh-axi host list                        # list approved hosts, no transport opened
+ssh-axi host show <host>                 # show one approved host, no transport opened
+ssh-axi doctor <host>                    # authenticate without running a remote command
+ssh-axi doctor --profile <name>
+ssh-axi auth status --profile <name>     # inspect credential sources offline
+ssh-axi profile list
+ssh-axi config path
+ssh-axi exec <host> --command <text> --confirm
+```
+
+Shared flags: `--json`, `--help`, `--config <absolute-path>`, `--profile <name>`.
+`exec` also accepts `--command`, `--confirm`, `--timeout`, `--output-limit`, `--detach`, `--request-key`, `--sudo` and `--connection`.
+`--detach`, `--request-key`, `--sudo` and `--connection` depend on the Artium host extension.
+`execution list`, `execution show`, `execution cancel` and the `connection` commands are managed (Artium) only; standalone calls return `HOSTED_REQUIRED`.
+Run `ssh-axi <command> --help` for the exact flags of each command.
+Help, discovery, profile inspection and credential status open no SSH transports.
+
+Native execution is one-shot.
+Native `doctor` also checks [write journal custody](#safety) before authentication without reading existing journal contents, creating an empty journal if needed without recording an execution.
+Agents, forwarding and interactive shells are unavailable.
+
+### Hosted use with Artium
+
+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.
+
+```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>
+```
+
+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.
+The corresponding authenticated APIs live under `/v1/admin/ssh/`.
+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.
+
+Hosted connections:
+
+- Belong to one authenticated user and login session family.
+- Start a fresh remote process for each command on the same transport.
+- Must match the selected host and ordinary or sudo binding, with no fallback reconnection.
+- Allow one active command per connection; overlapping use returns `CONNECTION_BUSY`.
+- Require `--confirm` to close while a command is active, which cancels that command; repeated close by the owner is idempotent.
+- Expire when idle after 10 minutes by default, accepting 1-60 minutes within the host ceiling.
+- Are not kept alive by inspection; timeout changes recompute expiry from the existing idle start.
+- Have an 8-hour maximum age, with four per user and sixteen globally, including authentication in progress.
+- Are fenced on revocation: affected workers stop and their private profiles are removed before acknowledgement.
+- Are discarded on server restart, which removes abandoned private directories and retains unproven executions as uncertain without replay.
+
+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.
+
+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, and 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.
+
+## Safety
+
+- 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 `$XDG_STATE_HOME/ssh-axi/writes.log` when `XDG_STATE_HOME` is absolute, otherwise to `~/.local/state/ssh-axi/writes.log`.
+- `SSH_AXI_WRITE_LOG` selects an absolute protected journal path.
+- The journal must be a regular file owned by the caller with no group or other access.
+- Journal parent directories must be owned by the caller or root, without symlinks or group or other write access, except for root-owned sticky directories.
+  User-private groups do not exempt group-writable parents.
+  Remove write permissions with `chmod g-w` or `chmod o-w` on the directory named in the error, or select a protected journal path with `SSH_AXI_WRITE_LOG`.
+- No local shell is invoked; the exact command text is sent to the remote SSH exec channel.
+- Remote stdin is closed without forwarding input, and both output streams continue draining.
+- Native Ctrl+C requests cancellation through the private worker.
+- 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 authentication credentials are sent.
+- 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.
+- Terminal controls are removed and protected output is withheld before persistence or delivery.
+- Remote output is untrusted text, never instructions.
+
+### Unknown outcomes
+
+Missing remote status is an uncertain outcome and a 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.
+
+### Audit and retention (hosted)
+
+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 and execution IDs, UTC timing, outcome, exit or 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.
+
+## Configuration
+
+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`.
+Run `ssh-axi config path` to print the resolved path.
+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`.
+Server keys require independent verification, and at most two approved keys may overlap during rotation.
+
+### Credentials
+
+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`, and the passphrase defaults to `SSH_AXI_PASSPHRASE`.
+`auth status` reports credential availability and sources as `env:<name>` or `protected file`.
+It does not display secret values or file paths, and does not check network authentication.
+Linux secret files must be owned by the caller, regular, protected from group and other access and reachable through protected directories without symlinks.
+Configuration files must also be owned and protected against group and other writes.
+
+### Profile selection
+
+Precedence is explicit host or `--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.
+
+### Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `SSH_AXI_CONFIG` | Absolute configuration file path |
+| `SSH_AXI_PROFILE` | Profile name to select |
+| `SSH_AXI_ADDRESS`, `SSH_AXI_PORT`, `SSH_AXI_USERNAME` | Environment profile endpoint |
+| `SSH_AXI_APPROVED_HOST_KEYS`, `SSH_AXI_ALLOWED_ADDRESSES` | JSON arrays for an environment profile |
+| `SSH_AXI_PRIVATE_KEY`, `SSH_AXI_PASSPHRASE` | Default private-key and passphrase references |
+| `SSH_AXI_READ_ONLY` | `true` rejects arbitrary execution |
+| `SSH_AXI_WRITE_LOG` | Absolute protected command journal path |
+| `XDG_CONFIG_HOME`, `XDG_STATE_HOME` | Absolute base directories |
+
+## Output and exit codes
+
+Output defaults to TOON; `--json` returns the same fields and empty-state meaning.
+Unknown arguments and flags fail with exit code 2.
+Operational failures use exit code 1.
+A remote exit such as 7 produces the same CLI exit code.
+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 or signal, received and retained byte counts, truncation and encoding-loss flags.
+`termination` is `deadline` when a timed-out command returns a remote exit or signal, and `remote-exit` for other reported remote exits or signals.
+Without remote status, `termination` remains `unknown`, including after deadline-triggered local teardown; see [Unknown outcomes](#unknown-outcomes).
+
+## Limitations
+
+- Native execution is one-shot; agents, forwarding and interactive shells are unavailable.
+- Managed executions, connections and sudo require the matching Artium extensions.
+- Actual ordinary-account non-elevation and successful non-root passwordless elevation remain commissioning checks; controlled peers establish account, key and command selection only.
+- 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.
+- Agent session hooks and a skill are pending.
+
+## Development
+
+Requires Node >=24.11.0 and pnpm 10.22.0.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build
+pnpm lint
+pnpm test
+pnpm pack --pack-destination /absolute/artifacts
+```
+
+Tests generate disposable keys and run all test descendants inside a Linux network namespace with loopback only.
+They require `unshare`, `ip`, `mount` and `tar`, and never fall back to unrestricted networking.
+Test preparation packs the local package and installs it offline into a clean prefix inside network isolation.
+Run `pnpm install --frozen-lockfile` first to populate the local dependency store.
+Test preparation reuses the project lockfile so offline installation does not require cached registry metadata.
+The package-contract checks verify the archive allowlist, installed bin help/version, and published admission entry points without an Artium fixture.
+The default suite verifies a reproducible tarball installed into a clean prefix and explicitly skips Artium unless a fixture is provided.
+To iterate on selected tests with the same package preparation and network isolation, run `pnpm test test/package-contract.test.ts`.
+
+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 administration changes through public administration; no fixture-seeding route exists in the product.
+
+```sh
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B1.1
+```
+
+The journey slices are B1.1, B2.1, B2.2, B3.1, B3.2, B4.1, B4.2 and B4.3.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## Security
+
+No `SECURITY.md` is present yet; this is pending.
+
+## License
+
+No `LICENSE` file is present yet; the license is pending.

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,31 @@
+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 commandHelp(command: string, hosted?: boolean): {
+    examples: string[];
+    defaults?: {
+        timeout: string;
+        outputLimit: string;
+        confirm: boolean;
+        detach: boolean;
+        sudo: boolean;
+    };
+    flags: string;
+    commands?: string[];
+    availability?: string;
+    description: string;
+};
+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,90 @@
+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 commandHelp(command, hosted = false) {
+    const definition = commands[command];
+    const managed = command.startsWith('execution ') || command.startsWith('connection ');
+    const invocation = managed ? 'artium-axi ssh-axi' : 'ssh-axi';
+    const argument = managed && command !== 'connection open' ? ' <id>' : ' <host>';
+    const usage = command === 'exec' ? 'exec <host> --command <text> --confirm'
+        : command === 'execution cancel' ? 'execution cancel <id> --confirm'
+            : command === 'connection set' ? 'connection set <id> --idle-timeout <duration>'
+                : `${command}${definition.arguments ? argument : ''}`;
+    return {
+        description: definition.description,
+        ...(managed ? { availability: 'Managed (Artium) only; use artium-axi ssh-axi.' } : {}),
+        ...(command === '' ? { commands: Object.keys(commands).filter(Boolean).map(name => `${name}${name.startsWith('execution ') || name.startsWith('connection ') ? ' (managed, Artium only)' : ''}`) } : {}),
+        flags: (hosted ? '--json, --help' : flagHelp) + Object.entries(definition.flags ?? {}).map(([key, type]) => `, --${key}${type === 'boolean' ? '' : ' <value>'}`).join(''),
+        ...(command === 'exec' ? { defaults: { timeout: '60s', outputLimit: '65536 bytes', confirm: false, detach: false, sudo: false } } : {}),
+        examples: command === '' ? ['ssh-axi host list', 'ssh-axi doctor <host>', 'ssh-axi config path']
+            : [`${invocation} ${usage}`, `${invocation} ${usage} --json`],
+    };
+}
+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 (managed, Artium only).', 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' | 'deadline' | '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>;
+}>;