# @gzl10/nexus-plugin-remote

> SSH remote execution with credential management and script library.

## Entities

- **remote_settings** (single): Global defaults — default_user, default_port, default_timeout, private_key (encrypted), public_key.
- **remote_credentials** (collection): SSH credentials. Fields: name, type (key_pair|password), private_key, passphrase, password (all encrypted via `ctx.core.crypto`).
- **remote_hosts** (collection, realtime): Host inventory. Fields: name, hostname, port, username, auth_method (default_key|credential|agent), credential_id, status, last_seen, fingerprint.
- **remote_scripts** (collection): Saved shell scripts. Fields: name, content, interpreter (bash|sh|python|node|custom), timeout.
- **remote_executions** (collection, immutable, 30-day retention): Execution log. Fields: host_id, host_name, command, stdout, stderr, exit_code, status, triggered_by (user|schedule), duration_ms.

## Service API

Register name: `remote`

```typescript
const remote = ctx.services.get<RemoteService>('remote')

const result = await remote.execute(hostId, command, options?)
// result: { stdout, stderr, exitCode, durationMs }

const result = await remote.runScript(hostId, scriptId, options?)
const { success } = await remote.testConnection(hostId)
const { publicKey, privateKey } = await remote.generateKeypair()
```

## Actions

- **test-connection** (row on hosts): Test SSH connectivity, update status and fingerprint. CASL: execute.
- **execute** (row on hosts): Ad-hoc command execution with confirmation. CASL: execute.
- **run-script** (row on hosts): Run saved script on host. CASL: execute.
- **generate-keypair** (module): Generate new Ed25519 key pair. CASL: manage.

## CASL

- RemoteSettings: ADMIN read/update.
- RemoteCredential: ADMIN manage.
- RemoteHost: ADMIN manage, SERVICE read/execute, SUPPORT read.
- RemoteScript: ADMIN manage, SERVICE read/execute, SUPPORT read.
- RemoteExecution: ADMIN/SERVICE/SUPPORT read.

## Notes

- TOFU (Trust On First Use) host key verification via SHA256 fingerprints.
- Credentials encrypted at rest via `ctx.core.crypto`.
- Script execution via base64 encoding (prevents shell injection).
- Output limits: 1 MB per stream, 10,000 chars for commands.
- Connection timeout: configurable, max 5 minutes.
- Auth methods: default_key (server), credential (stored), agent (SSH_AUTH_SOCK).
- Optional integration with schedules plugin: registers `remote:execute` and `remote:run-script` functions.
