@stacksjs/defaults 0.74.34 → 0.74.36

package/ai/skills/stacks-dashboard/SKILL.md

@@ -112,6 +112,36 @@ Derivatives are written back to the same disk under `.variants/<path>/`. The
 leading dot keeps them out of the listing, which skips hidden components - a
 folder of thirty derivatives beside every photo makes the browser useless.
 
+### Remote commands (stacksjs/stacks#960)
+
+Running a configured operation on a configured host over SSH. Deliberately NOT
+a terminal: the request names a host KEY and a command KEY, both from
+`config/remote.ts`, so there is nothing to escape and no shell to reach. An
+interactive session is tracked separately - `Bun.spawn` has no PTY, and
+`ssh -tt` gives a remote one but cannot propagate a window resize.
+
+Four things make it safe to expose, and each is a rule to keep:
+
+- **Host keys are verified.** `StrictHostKeyChecking=yes` against the host's
+  declared `knownHosts`. Do NOT reuse `sshExec` from `@stacksjs/ts-cloud` for
+  anything long-lived: it disables host key checking on purpose, for boxes a
+  minute old whose keys cannot be known.
+- **Hosts and commands come from config, never the request.** A `RemoteCommand`
+  carries an `argv` ARRAY that is never interpolated.
+- **The routes do NOT use `guard()`.** That helper drops auth entirely under
+  `APP_ENV=local|development|test`, which here would be an unauthenticated
+  command runner on any dev machine on the network. They use
+  `authenticatedGuard`, and `remote-routes.test.ts` asserts it.
+- **Authorization fails CLOSED.** The `run-remote-command` gate receives the
+  host and command keys; with no gate defined, every run is refused. This is the
+  opposite of the websocket authenticator in `@stacksjs/realtime`, which
+  proceeds when none is installed.
+
+Runs are recorded before AND after - a run recorded only on completion loses the
+command that hung and the one whose process died with the box. The audit sink
+writes to the application log rather than the dashboard's own database, which is
+the thing an operator with dashboard access could edit.
+
 **There is no ffmpeg.** #2578 asked whether video was in scope given the
 external binary, its licensing and its provisioning; `@stacksjs/video` is built
 on `ts-videos`, which encodes itself, so that question was already answered.

package/app/Actions/Dashboard/Remote/RemoteCommandIndexAction.ts

@@ -0,0 +1,29 @@
+import { Action } from '@stacksjs/actions'
+import { commands, hosts } from '~/config/remote'
+import { response } from '@stacksjs/router'
+
+export default new Action({
+  name: 'RemoteCommandIndexAction',
+  description: 'Lists the hosts and operations the dashboard is configured to run.',
+  method: 'GET',
+  async handle() {
+    // The registry, not the credentials. `identityFile` and `knownHosts` are
+    // deliberately not returned: a listing endpoint should not disclose which
+    // key file a server uses or the fingerprint an attacker would need to
+    // impersonate.
+    return response.json({
+      hosts: hosts.map(host => ({
+        key: host.key,
+        host: host.host,
+        user: host.user,
+        port: host.port ?? 22,
+      })),
+      commands: commands.map(command => ({
+        key: command.key,
+        description: command.description,
+        argv: command.argv,
+        hosts: command.hosts ?? null,
+      })),
+    })
+  },
+})

package/app/Actions/Dashboard/Remote/RemoteCommandRunAction.ts

@@ -0,0 +1,57 @@
+import type { UserModel } from '@stacksjs/orm'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { Gate } from '@stacksjs/auth'
+import { commands, hosts } from '~/config/remote'
+import { response } from '@stacksjs/router'
+import { RemoteCommandError, resolveCommand, resolveHost, runRemoteCommand } from './remote-commands'
+import { createSshRunner, loggingAuditSink } from './ssh-runner'
+
+/**
+ * Run one configured operation on one configured host (stacksjs/stacks#960).
+ *
+ * Routed WITHOUT the dashboard's `guard()` helper. That helper drops auth
+ * entirely when `APP_ENV` is local, development or test, which for this surface
+ * would be an unauthenticated command runner on every developer machine
+ * reachable on the network. See `routes/dashboard-api.ts`.
+ */
+export default new Action({
+  name: 'RemoteCommandRunAction',
+  description: 'Runs a configured operation on a configured host over SSH.',
+  method: 'POST',
+  async handle(request: RequestInstance) {
+    try {
+      // `request.user()` answers `AuthenticatedUser | undefined`; the gate and
+      // the audit identity both want the model or an explicit null.
+      const user = (await request.user() ?? null) as UserModel | null
+      const hostKey = request.get('host')
+      const commandKey = request.get('command')
+
+      // Resolved before authorization so the gate is asked about real keys
+      // rather than whatever the request said.
+      const host = resolveHost(hosts, hostKey)
+      const command = resolveCommand(commands, commandKey, host)
+
+      const result = await runRemoteCommand({ hostKey, commandKey }, {
+        user,
+        hosts,
+        commands,
+        // The gate receives both keys, so an application can scope by host, by
+        // command, or by both. Undefined when the app has not defined it, and
+        // `authorize` refuses in that case rather than proceeding.
+        authorizer: Gate.has('run-remote-command')
+          ? (candidate, forHost, forCommand) => Gate.allows('run-remote-command', candidate, forHost, forCommand)
+          : undefined,
+        run: createSshRunner(host, command),
+        audit: loggingAuditSink,
+      })
+
+      return response.json(result)
+    }
+    catch (error) {
+      if (error instanceof RemoteCommandError)
+        return response.json({ message: error.message }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Remote/remote-commands.test.ts

@@ -0,0 +1,272 @@
+// Running a known operation on a configured host (stacksjs/stacks#960).
+//
+// What is tested here is the security model, not SSH. The transport is
+// injected, so every rule below is asserted without a network: which hosts can
+// be reached, who may reach them, what is recorded, and what happens when any
+// of that is not configured.
+//
+// The properties worth stating up front, because each is a way this surface
+// becomes remote code execution if it is wrong:
+//
+//   - a request cannot name a host, only a key in the registry
+//   - a request cannot name a command, only a key in the registry
+//   - a host without a pinned key is refused rather than trusted
+//   - authorization fails CLOSED when no gate is configured
+//   - a run is recorded before it starts, not only when it finishes
+
+import type { UserModel } from '@stacksjs/orm'
+import type { RemoteAuditSink, RemoteCommand, RemoteHost } from './remote-commands'
+import { beforeEach, describe, expect, it } from 'bun:test'
+import {
+  authorize,
+  clampOutput,
+  normalizeTimeout,
+  RemoteCommandError,
+  resolveCommand,
+  resolveHost,
+  runRemoteCommand,
+  sshArgv,
+} from './remote-commands'
+
+const host: RemoteHost = {
+  key: 'app',
+  host: 'app.example.com',
+  user: 'deploy',
+  knownHosts: 'app.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIexample',
+}
+
+const hosts: RemoteHost[] = [
+  host,
+  { key: 'db', host: 'db.example.com', user: 'deploy', port: 2222, identityFile: '/keys/db', knownHosts: 'db.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIdb' },
+  { key: 'unpinned', host: 'new.example.com', user: 'deploy', knownHosts: '' },
+]
+
+const commands: RemoteCommand[] = [
+  { key: 'disk', description: 'Free space', argv: ['df', '-h'] },
+  { key: 'restart-api', description: 'Restart the API', argv: ['systemctl', 'restart', 'api'], hosts: ['app'] },
+]
+
+const user = { id: 1, email: 'ops@example.com' } as unknown as UserModel
+
+let recorded: string[] = []
+const audit: RemoteAuditSink = {
+  async started(entry) {
+    recorded.push(`started:${entry.user}:${entry.hostKey}:${entry.commandKey}`)
+  },
+  async finished(entry) {
+    recorded.push(`finished:${entry.hostKey}:${entry.commandKey}:${entry.exitCode}:${entry.timedOut}`)
+  },
+}
+
+beforeEach(() => {
+  recorded = []
+})
+
+const ok = async (): Promise<{ exitCode: number, stdout: string, stderr: string, timedOut: boolean }> =>
+  ({ exitCode: 0, stdout: 'out', stderr: '', timedOut: false })
+
+describe('resolveHost', () => {
+  it('resolves a declared host by key', () => {
+    expect(resolveHost(hosts, 'app')).toBe(host)
+  })
+
+  it('404s a key nobody declared', () => {
+    // The property that matters: a request names a KEY, and a key that is not
+    // in config reaches nothing. There is no path from the request to a
+    // hostname.
+    expect(() => resolveHost(hosts, 'evil.example.com')).toThrow(/No configured host/)
+    try {
+      resolveHost(hosts, 'nope')
+    }
+    catch (error) {
+      expect((error as RemoteCommandError).status).toBe(404)
+    }
+  })
+
+  it('refuses a host with no pinned key rather than trusting one on first contact', () => {
+    // Accepting a key on first contact is what makes a session into a
+    // long-lived box MITM-open. `sshExec` in ts-cloud does exactly that, on
+    // purpose, for boxes a minute old - which is why this does not reuse it.
+    expect(() => resolveHost(hosts, 'unpinned')).toThrow(/no pinned host key/)
+  })
+
+  it('rejects a non-string key', () => {
+    for (const key of [undefined, null, 42, {}, ''])
+      expect(() => resolveHost(hosts, key)).toThrow(RemoteCommandError)
+  })
+})
+
+describe('resolveCommand', () => {
+  it('resolves a declared command', () => {
+    expect(resolveCommand(commands, 'disk', host).argv).toEqual(['df', '-h'])
+  })
+
+  it('404s a command nobody declared', () => {
+    // No request carries a command, so there is nothing to escape and no shell
+    // to reach.
+    expect(() => resolveCommand(commands, 'rm -rf /', host)).toThrow(/No configured command/)
+  })
+
+  it('403s a command that is scoped away from this host', () => {
+    // 403 rather than 404: the command exists, this host is not one of its
+    // targets. Scoping `restart-api` to the app box is a deliberate
+    // restriction, and reporting it as "not found" would read as a typo.
+    const db = resolveHost(hosts, 'db')
+    expect(() => resolveCommand(commands, 'restart-api', db)).toThrow(/not permitted on host/)
+    try {
+      resolveCommand(commands, 'restart-api', db)
+    }
+    catch (error) {
+      expect((error as RemoteCommandError).status).toBe(403)
+    }
+  })
+
+  it('lets an unscoped command run anywhere', () => {
+    expect(resolveCommand(commands, 'disk', resolveHost(hosts, 'db')).key).toBe('disk')
+  })
+})
+
+describe('sshArgv', () => {
+  it('verifies the host key against the pinned file', () => {
+    const argv = sshArgv(host, commands[0]!, '/tmp/known_hosts')
+    expect(argv).toContain('StrictHostKeyChecking=yes')
+    expect(argv).toContain('UserKnownHostsFile=/tmp/known_hosts')
+  })
+
+  it('fails rather than prompting for a password', () => {
+    // A prompt on a server has nobody to answer it, so the request would hang
+    // until it timed out with no useful message.
+    expect(sshArgv(host, commands[0]!, '/tmp/kh')).toContain('BatchMode=yes')
+  })
+
+  it('passes the remote argv after `--`, as separate arguments', () => {
+    // Never joined into a string. A joined command is a shell command, and a
+    // shell command is where an injection would live if one could reach it.
+    const argv = sshArgv(host, commands[1]!, '/tmp/kh')
+    expect(argv.slice(argv.indexOf('--'))).toEqual(['--', 'systemctl', 'restart', 'api'])
+  })
+
+  it('carries the port and identity when the host declares them', () => {
+    const argv = sshArgv(hosts[1]!, commands[0]!, '/tmp/kh')
+    expect(argv).toContain('-p')
+    expect(argv[argv.indexOf('-p') + 1]).toBe('2222')
+    expect(argv[argv.indexOf('-i') + 1]).toBe('/keys/db')
+    // Without this ssh may offer an agent key instead of the configured one.
+    expect(argv).toContain('IdentitiesOnly=yes')
+  })
+
+  it('addresses the host as user@host', () => {
+    expect(sshArgv(host, commands[0]!, '/tmp/kh')).toContain('deploy@app.example.com')
+  })
+})
+
+describe('authorize', () => {
+  it('401s without a user', async () => {
+    expect(authorize(() => true, null, host, commands[0]!)).rejects.toThrow(/Authentication is required/)
+  })
+
+  it('fails CLOSED when no authorizer is configured', async () => {
+    // The opposite of the websocket authenticator next door, which proceeds
+    // when none is installed. For a surface that runs commands on a server, an
+    // app that has not defined the gate must get a refusal rather than a shell.
+    expect(authorize(undefined, user, host, commands[0]!)).rejects.toThrow(/not authorized on this application/)
+  })
+
+  it('403s when the gate says no', async () => {
+    expect(authorize(() => false, user, host, commands[0]!)).rejects.toThrow(/not permitted to run/)
+  })
+
+  it('passes both keys to the gate, so an app can scope by either', async () => {
+    const seen: string[] = []
+    await authorize((_user, hostKey, commandKey) => {
+      seen.push(hostKey, commandKey)
+      return true
+    }, user, host, commands[1]!)
+
+    expect(seen).toEqual(['app', 'restart-api'])
+  })
+})
+
+describe('runRemoteCommand', () => {
+  const context = {
+    user,
+    hosts,
+    commands,
+    authorizer: () => true,
+    run: ok,
+    audit,
+  }
+
+  it('records the run before it starts and again when it ends', async () => {
+    // A run recorded only on completion loses the two worth having: the command
+    // that hung, and the one whose process died with the box.
+    await runRemoteCommand({ hostKey: 'app', commandKey: 'disk' }, context)
+
+    expect(recorded).toEqual([
+      'started:ops@example.com:app:disk',
+      'finished:app:disk:0:false',
+    ])
+  })
+
+  it('records nothing for a run that was refused', async () => {
+    // Authorization happens before the audit entry, so a refusal is not an
+    // audit record saying somebody ran something they did not.
+    expect(runRemoteCommand({ hostKey: 'app', commandKey: 'disk' }, { ...context, authorizer: () => false }))
+      .rejects.toThrow(/not permitted/)
+
+    await Bun.sleep(0)
+    expect(recorded).toEqual([])
+  })
+
+  it('records nothing for a host that does not exist', async () => {
+    expect(runRemoteCommand({ hostKey: 'ghost', commandKey: 'disk' }, context)).rejects.toThrow(/No configured host/)
+    await Bun.sleep(0)
+    expect(recorded).toEqual([])
+  })
+
+  it('reports the outcome, including a timeout', async () => {
+    const result = await runRemoteCommand({ hostKey: 'app', commandKey: 'disk' }, {
+      ...context,
+      run: async () => ({ exitCode: 143, stdout: 'partial', stderr: 'killed', timedOut: true }),
+    })
+
+    expect(result.timedOut).toBeTrue()
+    expect(result.exitCode).toBe(143)
+    expect(recorded.at(-1)).toBe('finished:app:disk:143:true')
+  })
+
+  it('reports a non-zero exit as a result rather than an error', async () => {
+    // `systemctl restart` failing is information the operator wants, not an
+    // exception - the run happened and the audit record says what it did.
+    const result = await runRemoteCommand({ hostKey: 'app', commandKey: 'disk' }, {
+      ...context,
+      run: async () => ({ exitCode: 1, stdout: '', stderr: 'no such unit', timedOut: false }),
+    })
+
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).toBe('no such unit')
+  })
+})
+
+describe('output and timeout bounds', () => {
+  it('truncates with a marker rather than cutting silently', () => {
+    const clamped = clampOutput('x'.repeat(100), 10)
+    expect(clamped).toStartWith('xxxxxxxxxx')
+    expect(clamped).toContain('truncated at 10 characters')
+  })
+
+  it('leaves output within the limit alone', () => {
+    expect(clampOutput('short', 10)).toBe('short')
+  })
+
+  it('caps a timeout rather than honouring an unbounded one', () => {
+    expect(normalizeTimeout(undefined)).toBe(30_000)
+    expect(normalizeTimeout(5_000)).toBe(5_000)
+    expect(normalizeTimeout(10_000_000)).toBe(300_000)
+  })
+
+  it('rejects a timeout that is not a positive number', () => {
+    for (const value of [0, -1, Number.NaN, Number.POSITIVE_INFINITY])
+      expect(() => normalizeTimeout(value)).toThrow(RemoteCommandError)
+  })
+})

package/app/Actions/Dashboard/Remote/remote-commands.ts

@@ -0,0 +1,297 @@
+import type { UserModel } from '@stacksjs/orm'
+import type { ResponseStatus } from '@stacksjs/bun-router'
+
+/**
+ * Running a known operation on a configured host, from the dashboard
+ * (stacksjs/stacks#960).
+ *
+ * ## Why this is not a terminal
+ *
+ * The request asked for SSH in the dashboard, and named Termius. A browser
+ * terminal into a production box is remote code execution as a feature - the
+ * highest-privilege surface a dashboard can have - so what ships first is the
+ * part that carries most of the value and cannot become an arbitrary shell:
+ * run *this named operation* on *that host* and show me the output. Restart a
+ * service, tail a log, check disk.
+ *
+ * The command is chosen from a registry the config declares. The request names
+ * a KEY; it never carries a command, so there is no argument to escape and no
+ * shell to reach. An interactive session is a strictly larger problem and is
+ * tracked separately - `Bun.spawn` has no PTY, and `ssh -tt` gives a remote one
+ * but cannot propagate a window resize without a local TTY.
+ *
+ * ## What makes it safe to expose at all
+ *
+ * Four things, none of which the existing infrastructure gave for free:
+ *
+ * 1. **Host keys are verified.** `sshExec` in `@stacksjs/ts-cloud` disables host
+ *    key checking on purpose - it targets boxes created a minute ago whose keys
+ *    cannot be known. For a long-lived production host that is MITM-open, so
+ *    this does not reuse it. `StrictHostKeyChecking=yes` against a configured
+ *    known-hosts file, and a host with no pinned key is refused rather than
+ *    trusted on first contact.
+ * 2. **Hosts come from config, never the request.** The request names a key in
+ *    the registry. An unknown key is a 404, so no request can reach a host the
+ *    operator did not declare.
+ * 3. **Authorization is per host, and has no local bypass.** The dashboard's
+ *    `guard()` helper drops auth entirely when `APP_ENV` is local or test,
+ *    which for this surface would be an unauthenticated shell on every
+ *    developer machine reachable on the network. This checks a gate instead.
+ * 4. **Every run is recorded** - who, which host, which command, when, exit
+ *    code - before it starts and again when it ends.
+ */
+
+/** A host the dashboard may reach, as `config/cloud.ts` declares it. */
+export interface RemoteHost {
+  /** Stable key the request names. Never a hostname. */
+  key: string
+  /** Hostname or IP. */
+  host: string
+  /** SSH user. */
+  user: string
+  /** SSH port. Omit for 22. */
+  port?: number
+  /** Private key passed as `ssh -i`. Omit to use the ambient agent. */
+  identityFile?: string
+  /**
+   * Pinned host keys for this host, in `known_hosts` format.
+   *
+   * Required. A host without one cannot be reached: accepting a key on first
+   * contact is what makes an interactive session into a production box
+   * MITM-open, and there is no reason to do it here - the operator declaring
+   * the host can declare its fingerprint at the same time.
+   */
+  knownHosts: string
+}
+
+/** An operation that may be run, as config declares it. */
+export interface RemoteCommand {
+  /** Stable key the request names. */
+  key: string
+  /** What it does, shown in the dashboard. */
+  description: string
+  /**
+   * The argv to run on the host.
+   *
+   * An ARRAY, and never interpolated. A string would be a shell command, and a
+   * shell command with any caller-supplied part in it is an injection - which
+   * is the whole reason the request cannot carry one.
+   */
+  argv: readonly string[]
+  /** Host keys this command may run on. Omit for every host. */
+  hosts?: readonly string[]
+}
+
+export class RemoteCommandError extends Error {
+  readonly status: ResponseStatus
+
+  constructor(message: string, status: ResponseStatus = 422) {
+    super(message)
+    this.name = 'RemoteCommandError'
+    this.status = status
+  }
+}
+
+/** What a completed run produced. */
+export interface RemoteCommandResult {
+  host: string
+  command: string
+  exitCode: number
+  stdout: string
+  stderr: string
+  /** Milliseconds from spawn to exit. */
+  durationMs: number
+  /** Whether the run was cut short by {@link RemoteRunOptions.timeoutMs}. */
+  timedOut: boolean
+}
+
+/** How a run reaches the host. Injected so the rules can be tested without a network. */
+export type RemoteRunner = (
+  argv: readonly string[],
+  options: { timeoutMs: number },
+) => Promise<{ exitCode: number, stdout: string, stderr: string, timedOut: boolean }>
+
+/** Where a run is recorded. Injected for the same reason. */
+export interface RemoteAuditSink {
+  started: (entry: { user: string, hostKey: string, commandKey: string, at: string }) => Promise<void>
+  finished: (entry: { user: string, hostKey: string, commandKey: string, at: string, exitCode: number, durationMs: number, timedOut: boolean }) => Promise<void>
+}
+
+export interface RemoteRunOptions {
+  /** Give up after this long and report `timedOut`. */
+  timeoutMs?: number
+  /** Trim output beyond this many characters, so one run cannot fill a response. */
+  maxOutputChars?: number
+}
+
+/** A run that has not finished in this long is not going to be useful in a dashboard. */
+const DEFAULT_TIMEOUT_MS = 30_000
+const MAX_TIMEOUT_MS = 300_000
+const DEFAULT_MAX_OUTPUT = 64 * 1024
+
+/**
+ * The `ssh` argv for a command on a host.
+ *
+ * Every option here is load bearing:
+ *
+ * - `StrictHostKeyChecking=yes` and a per-host `UserKnownHostsFile` are what
+ *   distinguish this from `sshExec`. Without them a changed host key is
+ *   accepted silently, which is the entire attack.
+ * - `BatchMode=yes` means a host that wants a password fails instead of hanging
+ *   on a prompt no one can answer.
+ * - `--` separates the ssh options from the remote argv, and the remote argv is
+ *   passed as separate arguments rather than joined, so nothing in it is
+ *   interpreted by a local shell.
+ */
+export function sshArgv(host: RemoteHost, command: RemoteCommand, knownHostsPath: string): string[] {
+  const argv = [
+    'ssh',
+    '-o', 'StrictHostKeyChecking=yes',
+    '-o', `UserKnownHostsFile=${knownHostsPath}`,
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=10',
+  ]
+
+  if (host.port !== undefined)
+    argv.push('-p', String(host.port))
+  if (host.identityFile)
+    argv.push('-i', host.identityFile, '-o', 'IdentitiesOnly=yes')
+
+  argv.push(`${host.user}@${host.host}`, '--', ...command.argv)
+  return argv
+}
+
+/** The host with this key, or a 404. Hosts never come from the request itself. */
+export function resolveHost(hosts: readonly RemoteHost[], key: unknown): RemoteHost {
+  if (typeof key !== 'string' || !key.trim())
+    throw new RemoteCommandError('A host key is required.', 422)
+
+  const host = hosts.find(entry => entry.key === key)
+  if (!host)
+    throw new RemoteCommandError(`No configured host named "${key}".`, 404)
+
+  // Refused rather than trusted on first contact. A host declared without its
+  // fingerprint is a configuration mistake, and the failure mode of guessing is
+  // silent.
+  if (!host.knownHosts.trim())
+    throw new RemoteCommandError(`Host "${key}" has no pinned host key; add one to its \`knownHosts\` before it can be reached.`, 422)
+
+  return host
+}
+
+/** The command with this key, if it may run on this host. */
+export function resolveCommand(commands: readonly RemoteCommand[], key: unknown, host: RemoteHost): RemoteCommand {
+  if (typeof key !== 'string' || !key.trim())
+    throw new RemoteCommandError('A command key is required.', 422)
+
+  const command = commands.find(entry => entry.key === key)
+  if (!command)
+    throw new RemoteCommandError(`No configured command named "${key}".`, 404)
+
+  // A command scoped to some hosts is a deliberate restriction - `deploy` on
+  // the app box and not on the database box - so an unscoped run of it is a 403
+  // rather than a 404: the command exists, this host is not one of its targets.
+  if (command.hosts && !command.hosts.includes(host.key))
+    throw new RemoteCommandError(`Command "${command.key}" is not permitted on host "${host.key}".`, 403)
+
+  return command
+}
+
+/**
+ * Whether `user` may run `command` on `host`.
+ *
+ * A gate rather than a role, because the request was for "certain users" and
+ * `role:admin` is one bit. The gate receives both keys, so an application can
+ * scope by host, by command, or by both without this file knowing how.
+ */
+export type RemoteAuthorizer = (user: UserModel | null, hostKey: string, commandKey: string) => Promise<boolean> | boolean
+
+/** Refuses when no authorizer is configured. */
+export async function authorize(
+  authorizer: RemoteAuthorizer | undefined,
+  user: UserModel | null,
+  host: RemoteHost,
+  command: RemoteCommand,
+): Promise<void> {
+  if (!user)
+    throw new RemoteCommandError('Authentication is required.', 401)
+
+  // Fails CLOSED. An app that has not defined the gate gets a refusal, not a
+  // shell - the opposite of the websocket authenticator next door, which
+  // proceeds when none is installed for backwards-compatibility.
+  if (!authorizer)
+    throw new RemoteCommandError('Remote commands are not authorized on this application.', 403)
+
+  if (!await authorizer(user, host.key, command.key))
+    throw new RemoteCommandError(`You are not permitted to run "${command.key}" on "${host.key}".`, 403)
+}
+
+/** Output beyond `limit`, with a marker rather than a silent cut. */
+export function clampOutput(value: string, limit: number = DEFAULT_MAX_OUTPUT): string {
+  if (value.length <= limit)
+    return value
+  return `${value.slice(0, limit)}\n… output truncated at ${limit} characters`
+}
+
+/** A timeout inside the bounds a dashboard request can wait for. */
+export function normalizeTimeout(value: number | undefined): number {
+  if (value === undefined)
+    return DEFAULT_TIMEOUT_MS
+  if (!Number.isFinite(value) || value <= 0)
+    throw new RemoteCommandError('The timeout must be a positive number of milliseconds.', 422)
+  return Math.min(value, MAX_TIMEOUT_MS)
+}
+
+/**
+ * Resolve, authorize, record, run, record.
+ *
+ * The audit entry is written BEFORE the command runs and again after. A run
+ * recorded only on completion loses exactly the ones worth having: the command
+ * that hung, and the one whose process died with the box.
+ */
+export async function runRemoteCommand(
+  input: { hostKey: unknown, commandKey: unknown },
+  context: {
+    user: UserModel | null
+    hosts: readonly RemoteHost[]
+    commands: readonly RemoteCommand[]
+    authorizer?: RemoteAuthorizer
+    run: RemoteRunner
+    audit: RemoteAuditSink
+  },
+  options: RemoteRunOptions = {},
+): Promise<RemoteCommandResult> {
+  const host = resolveHost(context.hosts, input.hostKey)
+  const command = resolveCommand(context.commands, input.commandKey, host)
+  await authorize(context.authorizer, context.user, host, command)
+
+  const timeoutMs = normalizeTimeout(options.timeoutMs)
+  const identity = String(context.user?.email ?? context.user?.id ?? 'unknown')
+  const startedAt = new Date().toISOString()
+
+  await context.audit.started({ user: identity, hostKey: host.key, commandKey: command.key, at: startedAt })
+
+  const began = Date.now()
+  const outcome = await context.run(command.argv, { timeoutMs })
+  const durationMs = Date.now() - began
+
+  await context.audit.finished({
+    user: identity,
+    hostKey: host.key,
+    commandKey: command.key,
+    at: new Date().toISOString(),
+    exitCode: outcome.exitCode,
+    durationMs,
+    timedOut: outcome.timedOut,
+  })
+
+  return {
+    host: host.key,
+    command: command.key,
+    exitCode: outcome.exitCode,
+    stdout: clampOutput(outcome.stdout, options.maxOutputChars),
+    stderr: clampOutput(outcome.stderr, options.maxOutputChars),
+    durationMs,
+    timedOut: outcome.timedOut,
+  }
+}

package/app/Actions/Dashboard/Remote/remote-routes.test.ts

@@ -0,0 +1,58 @@
+// The remote-command routes must not inherit the dashboard's local-env bypass
+// (stacksjs/stacks#960).
+//
+// `guard()` in `routes/dashboard-api.ts` reads:
+//
+//   if (!IS_LOCAL_ENV)
+//     r.middleware('auth').middleware('role:admin')
+//
+// and `IS_LOCAL_ENV` covers local, development, dev, test, testing and empty.
+// That is a reasonable trade for operational telemetry on a developer machine.
+// For an endpoint that runs commands on a server it is an unauthenticated
+// command runner on every developer machine reachable on the network.
+//
+// Asserted against the route file as text, because that is where the mistake
+// would be made - somebody adding a route next to the others and reaching for
+// the helper they see used around it.
+
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const routes = readFileSync(join(import.meta.dir, '../../../../routes/dashboard-api.ts'), 'utf8')
+
+/** The route lines for this feature, whatever helper they are wrapped in. */
+const remoteRoutes = routes
+  .split('\n')
+  .filter(line => line.includes('Actions/Dashboard/Remote/'))
+
+describe('remote-command routes', () => {
+  it('registers both endpoints', () => {
+    expect(remoteRoutes).toHaveLength(2)
+    expect(remoteRoutes.join('\n')).toContain('RemoteCommandIndexAction')
+    expect(remoteRoutes.join('\n')).toContain('RemoteCommandRunAction')
+  })
+
+  it('never uses the guard that drops auth in local environments', () => {
+    // The whole point. `guard(` would mean no authentication at all under
+    // APP_ENV=local, on a route that runs commands over SSH.
+    for (const line of remoteRoutes)
+      expect(line).not.toContain('guard(route')
+  })
+
+  it('uses the guard that keeps auth in every environment', () => {
+    for (const line of remoteRoutes)
+      expect(line).toContain('authenticatedGuard(route')
+  })
+
+  it('the two guards really do differ, so this is not vacuous', () => {
+    // If `guard` and `authenticatedGuard` were the same, everything above would
+    // pass for a route with no protection at all. They differ in exactly one
+    // way: whether `auth` survives a local environment.
+    const guardBody = routes.slice(routes.indexOf('function guard('), routes.indexOf('function authenticatedGuard('))
+    const authenticatedBody = routes.slice(routes.indexOf('function authenticatedGuard('))
+
+    expect(guardBody).toContain('if (!IS_LOCAL_ENV)\n    r.middleware(\'auth\')')
+    expect(authenticatedBody.slice(0, 400)).toContain('r.middleware(\'auth\')\n  if (!IS_LOCAL_ENV)')
+  })
+})

package/app/Actions/Dashboard/Remote/ssh-runner.ts

@@ -0,0 +1,94 @@
+import type { RemoteAuditSink, RemoteCommand, RemoteHost, RemoteRunner } from './remote-commands'
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { log } from '@stacksjs/logging'
+import { sshArgv } from './remote-commands'
+
+/**
+ * The SSH transport and audit sink behind `runRemoteCommand`
+ * (stacksjs/stacks#960).
+ *
+ * Split from `remote-commands.ts` so the resolution, authorization and audit
+ * ordering can be tested without a network or a database - the same split
+ * `file-manager.ts` makes with its `Manager` parameter.
+ */
+
+/**
+ * A runner for one host, with that host's pinned keys written to a file only
+ * this process can read.
+ *
+ * The known-hosts file is created per run and removed afterwards rather than
+ * kept in `~/.ssh`: the app server may reach several hosts with different
+ * operators, and a shared file is one where a stale entry for a decommissioned
+ * box silently authorizes whoever picked up its address.
+ */
+export function createSshRunner(host: RemoteHost, command: RemoteCommand): RemoteRunner {
+  return async (_argv, options) => {
+    const dir = mkdtempSync(join(tmpdir(), 'stacks-remote-'))
+    const knownHostsPath = join(dir, 'known_hosts')
+
+    try {
+      writeFileSync(knownHostsPath, host.knownHosts.endsWith('\n') ? host.knownHosts : `${host.knownHosts}\n`)
+      // ssh refuses a known-hosts file others can write.
+      chmodSync(knownHostsPath, 0o600)
+
+      const proc = Bun.spawn(sshArgv(host, command, knownHostsPath), {
+        stdin: 'ignore',
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+
+      // A run that has not finished is killed rather than left. Without this a
+      // hung ssh holds a process and a request until the server restarts.
+      let timedOut = false
+      const timer = setTimeout(() => {
+        timedOut = true
+        proc.kill()
+      }, options.timeoutMs)
+
+      try {
+        const [stdout, stderr, exitCode] = await Promise.all([
+          new Response(proc.stdout).text(),
+          new Response(proc.stderr).text(),
+          proc.exited,
+        ])
+
+        return { exitCode, stdout, stderr, timedOut }
+      }
+      finally {
+        clearTimeout(timer)
+      }
+    }
+    finally {
+      // Always, including on the failure path: a pinned-key file left in the
+      // temp directory on every run is both a leak and a growing surface.
+      rmSync(dir, { force: true, recursive: true })
+    }
+  }
+}
+
+/**
+ * The audit sink that writes to the application log.
+ *
+ * The log rather than a table, deliberately. A remote-command record is
+ * append-only evidence about who did what, and the dashboard's own database is
+ * the thing an operator with dashboard access could edit. Shipping to whatever
+ * the app's logging is already configured to ship to keeps it outside the blast
+ * radius of the surface it audits.
+ *
+ * An application that wants these queryable can pass its own sink; the
+ * interface is two functions.
+ */
+export const loggingAuditSink: RemoteAuditSink = {
+  async started(entry) {
+    // Not `log.debug`: this is the record, and a level nobody ships in
+    // production is the same as not recording it.
+    await log.info(`[remote] ${entry.user} started ${entry.commandKey} on ${entry.hostKey} at ${entry.at}`)
+  },
+
+  async finished(entry) {
+    const outcome = entry.timedOut ? 'timed out' : `exited ${entry.exitCode}`
+    await log.info(`[remote] ${entry.user} finished ${entry.commandKey} on ${entry.hostKey}: ${outcome} in ${entry.durationMs}ms`)
+  },
+}

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.74.34",
+  "version": "0.74.36",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.34",
+  "version": "0.74.36",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.74.34",
+    "@stacksjs/mobile": "^0.74.36",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/routes/dashboard-api.ts

@@ -260,6 +260,21 @@ route.group({ prefix: '/api/dashboard', apiResponse: true }, () => {
   guard(route.post('/files/duplicates', 'Actions/Dashboard/Content/FileDuplicateAction'))
   guard(route.delete('/files', 'Actions/Dashboard/Content/FileDestroyAction'))
 
+  /*
+   * Remote commands (stacksjs/stacks#960).
+   *
+   * Deliberately NOT behind `guard()`. That helper drops auth entirely when
+   * `APP_ENV` is local, development or test - which is a reasonable trade for
+   * operational telemetry on a developer machine, and an unauthenticated
+   * command runner for this. `authenticatedGuard` keeps `auth` in every
+   * environment, the same treatment billing gets and for the same reason.
+   *
+   * Authorization proper is the `run-remote-command` gate, checked per host and
+   * per command inside the action. Being authenticated is not being allowed.
+   */
+  authenticatedGuard(route.get('/remote/commands', 'Actions/Dashboard/Remote/RemoteCommandIndexAction'))
+  authenticatedGuard(route.post('/remote/run', 'Actions/Dashboard/Remote/RemoteCommandRunAction'))
+
   guard(route.get('/ci/status', 'Actions/Dashboard/Ci/StatusAction'))
   // CI drilldown (stacksjs/stacks#1848): per-repo run history + per-run
   // job detail. On-demand reads so the polled snapshot stays cheap.