dsh-foreman-node 0.1.0 → 0.2.0

package/src/index.ts

@@ -5,54 +5,123 @@
  * It imports no domain core, opens no database, and reads no policy, because a device holds no ledger — the hub is
  * the only place work is recorded, and this side's job is to do it and say what happened.
  */
-import type { Context } from '@deepseek-ai/cordis'
+import type { Context, Volatile } from '@deepseek-ai/cordis'
 import s from '@deepseek-ai/schemastery'
 import type {} from '@deepseek-ai/dsh-api-session-controller'
 import type {} from '@deepseek-ai/dsh-session-persistence'
 import type {} from '@deepseek-ai/dsh-workspace'
 import type {} from '@deepseek-ai/dsh-permission-presets'
 import type {} from '@deepseek-ai/dsh-tools'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { NodeClient } from './client.ts'
+import { configured, SSH_DEFAULTS, type NodeConfig, type NodeRoot, type SshConfig } from './config.ts'
+import { registerNodeRoutes, type RouteHost } from './routes.ts'
+import { Tunnel } from './tunnel.ts'
 import { JobSessions } from './session.ts'
 import type { Frame } from './protocol.ts'
 
 /** Version reported in the hello, so the hub can tell which device build is talking. */
-export const VERSION = '0.1.0'
-
-/** One project this device can work on: the hub's logical name and this machine's own absolute path. */
-export interface NodeRoot { project: string; path: string }
-
-/** What the `dsh-foreman-node` entry in a profile's patch configures. */
-export interface NodeConfig {
-  /** The hub's stable address; the device dials out to it. */
-  url: string
-  /** This device's id, as registered on the hub with `Devices.add`. */
-  deviceId: string
-  /** This device's token; sent in the hello and nowhere else. */
-  token: string
-  /** The projects this device can work on. */
-  roots: NodeRoot[]
-  /** How often to tell the hub this device is alive, in milliseconds. */
-  heartbeatMs: number
-  /** Delay before the first reconnect attempt, in milliseconds. */
-  reconnectMs: number
-}
+export const VERSION = '0.2.0'
 
 /**
  * Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
  *
+ * Everything is optional on purpose. A bundle patch inserts this row the moment the package is added to a profile,
+ * so `apply` runs before anyone has filled the values in — and a schema that demanded them would turn the whole
+ * profile red with "invalid config" on a fresh install. `apply` treats a blank address as "not configured yet":
+ * it says what is missing and stops, instead of dialling nowhere or refusing to activate.
+ *
  * The annotation names the schema type through the global `Schemastery` namespace rather than letting it be inferred:
  * an inferred type here names a `cosmokit` symbol the emitted declaration cannot reference portably.
  */
-export const Config: Schemastery<NodeConfig> = s.object({
-  url: s.string().required().description('The hub\'s address, such as wss://foreman.example.com. The device dials out to it.'),
-  deviceId: s.string().required().description('This device\'s id, as registered on the hub with `Devices.add`.'),
-  token: s.string().required().role('secret').description('This device\'s token; it is sent in the hello frame and nowhere else.'),
-  roots: s.array(s.object({ project: s.string().required(), path: s.string().required() })).default([])
+const ConfigSchema = s.object({
+  url: s.string().default('').volatile().description('The hub\'s address, such as wss://foreman.example.com. The device dials out to it.'),
+  deviceId: s.string().default('').volatile().description('This device\'s id, as registered on the hub with `Devices.add`.'),
+  token: s.string().default('').role('secret').volatile().description('This device\'s token; it is sent in the hello frame and nowhere else.'),
+  roots: s.array(s.object({ project: s.string().required(), path: s.string().required() })).default([]).volatile()
     .description('Projects this device can work on: a logical name and this machine\'s own absolute path, kept verbatim.'),
-  heartbeatMs: s.natural().default(15_000).description('How often to tell the hub this device is alive, in milliseconds.'),
-  reconnectMs: s.natural().default(1_000).description('Delay before the first reconnect attempt, in milliseconds.'),
+  heartbeatMs: s.natural().default(15_000).volatile().description('How often to tell the hub this device is alive, in milliseconds.'),
+  reconnectMs: s.natural().default(1_000).volatile().description('Delay before the first reconnect attempt, in milliseconds.'),
+  // Every field carries a default, and the object itself does too: a `cordis.patch.yml` written before this block
+  // existed has no `ssh` key, and a schema that demanded one would report the whole profile invalid on upgrade.
+  // Every field here is volatile for the same reason as the top level: `isVolatilePath` walks into this object, so a
+  // non-volatile child makes the whole section unwritable and the page reports "could not save". Marked per field
+  // rather than on the object, which would replace this block's default with `{}`.
+  ssh: s.object({
+    enabled: s.boolean().default(false).volatile().description('Reach the hub through an SSH tunnel this device starts itself.'),
+    host: s.string().default('').volatile().description('The hub machine, such as 203.0.113.10 or its ~/.ssh/config alias.'),
+    // min(1), not just natural(): an empty port box becomes 0, and 0 is a port the tunnel would happily dial.
+    port: s.natural().min(1).max(65535).default(22).volatile().description('The hub machine\'s SSH port.'),
+    user: s.string().default('').volatile().description('The SSH user on the hub machine.'),
+    keyPath: s.string().default('').volatile().description('The private key this device authenticates with; the page lists these from ~/.ssh.'),
+    remotePort: s.natural().min(1).max(65535).default(8790).volatile().description('The port the hub listens on, on the hub machine.'),
+    localPort: s.natural().min(1).max(65535).default(8790).volatile().description('The local port the tunnel listens on; the device dials this.'),
+  }).default({ enabled: false, host: '', port: 22, user: '', keyPath: '', remotePort: 8790, localPort: 8790 })
+    .description('How to reach the hub when it is not directly reachable: a tunnel this device opens and keeps open.'),
 })
+/**
+ * Why every field is volatile.
+ *
+ * Not for hot reload: it is the switch that makes the entry visible to DSH's settings system at all. `dsh-settings`
+ * skips every plugin entry whose `volatileForm(schema)` is undefined, and that only finds fields reachable through a
+ * volatile ancestor. Without it the configuration page has no form to render and sits on "reading configuration"
+ * forever — no fields, no test button, no save.
+ *
+ * A volatile field arrives wrapped, so its value is read with `.get()`; `configured()` is what unwraps a whole
+ * `NodeConfig` for the code that would rather not know. Marking the object instead of each field is not an option:
+ * `.volatile()` on the object replaces every default with `{}`, so `Config({})` loses all of them.
+ */
+
+/**
+ * What `apply` actually receives: every field wrapped, since each one is volatile.
+ *
+ * Declared as an alias rather than inferred so the plugin's public signature does not name a `schemastery` symbol the
+ * emitted declaration cannot reference portably.
+ */
+export type ConfigInput = { [K in keyof NodeConfig]: NodeConfig[K] | Volatile<NodeConfig[K]> }
+
+/**
+ * The schema, asserted rather than annotated.
+ *
+ * An annotation makes the declaration portable but cannot express what a volatile field does to a field's type, so the
+ * mismatch moves into the annotation. The assertion keeps the published `.d.ts` free of `schemastery` internals and
+ * puts the shape in one place; `configured()` is what re-establishes the real types at every read.
+ */
+const Typed = ConfigSchema as unknown as Schemastery<NodeConfig>
+export { Typed as Config }
+
+/**
+ * What this configuration still needs before the device can dial its hub, or undefined when it is complete.
+ *
+ * A missing value is reported by name so an operator can fill it in without reading the source; a value that is only
+ * whitespace counts as missing, because a device that dials a blank address retries forever and looks merely offline.
+ */
+/**
+ * The address this device dials.
+ *
+ * With the tunnel on, that is the local end of it: `url` names the hub at its own address, which the tunnel exists to
+ * make reachable, so dialling `url` would bypass the tunnel entirely and look like an offline device. Keeping the two
+ * cases in one function is what stops `apply` from picking the wrong one.
+ */
+export function hubUrlOf(config: NodeConfig): string {
+  return config.ssh.enabled ? `ws://127.0.0.1:${config.ssh.localPort}` : config.url
+}
+
+export function missingConfiguration(config: NodeConfig): string | undefined {
+  const missing: string[] = []
+  // The address is only required when there is no tunnel: with one, the device dials its local end and `url` is unused.
+  if (config.ssh.enabled) {
+    if (config.ssh.host.trim() === '') missing.push('ssh.host')
+    if (config.ssh.user.trim() === '') missing.push('ssh.user')
+    if (config.ssh.keyPath.trim() === '') missing.push('ssh.keyPath')
+  } else if (config.url.trim() === '') missing.push('url')
+  if (config.deviceId.trim() === '') missing.push('deviceId')
+  if (config.token.trim() === '') missing.push('token')
+  if (missing.length === 0) return undefined
+  return `dsh-foreman-node is not configured yet: ${missing.join(', ')} ` +
+    `missing. Set them on the dsh-foreman-node row in the profile patch (the hub prints the token when you register the device).`
+}
 
 export const name = 'dsh-foreman-node'
 /** DSH services a job needs; all are the host's own, and none is a foreman one. */
@@ -61,13 +130,33 @@ export const inject = ['sessionController', 'sessionPersistence', 'workspaceRegi
 /**
  * Start the device.
  *
+ * A package that has just been installed has its row in the profile patch with no values in it yet. Activating
+ * cleanly and saying what is still missing keeps the whole profile healthy; throwing here is what made a fresh
+ * install report the profile as broken.
+ *
  * The plugin returns once the connection is attempted, not once it succeeds: a device must boot and stay usable
  * while its hub is unreachable, and the client keeps retrying in the background.
  */
-export async function apply(ctx: Context, config: NodeConfig): Promise<void> {
+export async function apply(ctx: Context, raw: ConfigInput): Promise<void> {
+  // Every field is volatile, so `raw` holds wrappers; everything below wants plain values.
+  const config = configured(raw)
+  // The configuration page has to work on a device that is not configured yet — that is precisely when someone opens
+  // it — so the routes go up before the check below, not after it. `webServer` is injected optionally rather than
+  // listed in `inject`: a headless or CLI DSH has no web server and must still take work, losing only the page.
+  ctx.inject(['webServer'], child => {
+    // The service shape is declared locally rather than imported from `@deepseek-ai/dsh-host-webserver`: the device
+    // package stays thin, and this plugin needs two members of that service, not its whole surface.
+    const host = (child as unknown as { webServer: RouteHost }).webServer
+    child.effect(() => registerNodeRoutes(host, sshDirectory()))
+  })
+  const missing = missingConfiguration(config)
+  if (missing !== undefined) {
+    ctx.logger.info('%s', missing)
+    return
+  }
   const jobs = new JobSessions(ctx)
   const client = new NodeClient({
-    url: config.url,
+    url: hubUrlOf(config),
     deviceId: config.deviceId,
     token: config.token,
     version: VERSION,
@@ -78,9 +167,24 @@ export async function apply(ctx: Context, config: NodeConfig): Promise<void> {
     log: text => ctx.logger.warn('%s', text),
     onFrame: frame => { void receive(ctx, jobs, client, frame) },
   })
-  client.start()
-  ctx.effect(() => () => { client.stop() })
-  ctx.logger.info('dsh-foreman-node %s is dialling %s as %s', VERSION, config.url, config.deviceId)
+  // With a tunnel, the client waits for the local port to answer before dialling it: a client that starts early spends
+  // its first attempts on a port nothing is listening on, which reads in the log like the hub being down.
+  const tunnel = config.ssh.enabled
+    ? new Tunnel({ ssh: config.ssh, log: text => ctx.logger.warn('%s', text),
+      onState: (state, failure) => {
+        ctx.logger.info('dsh-foreman-node tunnel: %s', failure === undefined ? state : `${state} (${failure})`)
+        if (state === 'connected') client.start()
+      } })
+    : undefined
+  if (tunnel === undefined) client.start()
+  else tunnel.start()
+  ctx.effect(() => () => { tunnel?.stop(); client.stop() })
+  ctx.logger.info('dsh-foreman-node %s is dialling %s as %s', VERSION, hubUrlOf(config), config.deviceId)
+}
+
+/** The directory the key list reads; `~/.ssh` on a machine where the current user is the one configuring it. */
+export function sshDirectory(): string {
+  return join(homedir(), '.ssh')
 }
 
 /**
@@ -123,7 +227,11 @@ async function receive(ctx: Context, jobs: JobSessions, client: NodeClient, fram
   }
 }
 
+export { configured, SSH_DEFAULTS, type NodeConfig, type NodeRoot, type SshConfig } from './config.ts'
 export { NodeClient } from './client.ts'
+export { Tunnel, tunnelArgs } from './tunnel.ts'
+export { listKeys } from './keys.ts'
+export { registerNodeRoutes, testArgs } from './routes.ts'
 export { JobSessions } from './session.ts'
 export { foremanReportTool, REPORT_STATES } from './report-tool.ts'
 export type { Frame, Root, FrameAttachment } from './protocol.ts'

package/src/keys.ts

@@ -0,0 +1,49 @@
+/**
+ * The SSH keys this machine already has, named so a person can pick one.
+ *
+ * A browser cannot list `~/.ssh`: the page runs in the DSH web UI, which has no filesystem. The device process does,
+ * so the listing happens here and the page renders it. Nothing on this path reads a private key: the answer is a
+ * filename, a path, and the comment from the public half, which is enough to tell one key from another and is all a
+ * page needs.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+/** One key a person may choose: never its contents, only what tells it apart from the others. */
+export interface SshKey {
+  /** The filename, such as `id_ed25519`. */
+  name: string
+  /** Its absolute path, which is what the configuration stores. */
+  path: string
+  /** The trailing comment of the public half, usually `user@machine`; empty when it has none. */
+  comment: string
+}
+
+/** The `.pub` file that sits beside a private key. */
+const publicOf = (path: string): string => `${path}.pub`
+
+/**
+ * Lists the usable private keys in a directory.
+ *
+ * A key counts as usable only when its public half is beside it: that is how `ssh-keygen` writes them, and a private
+ * key without one is either half-deleted or was never finished, so offering it would only fail later at the tunnel.
+ * Anything unreadable is skipped rather than thrown, because a permissions problem on one file must not empty the list.
+ */
+export function listKeys(directory: string): SshKey[] {
+  let names: string[]
+  try { names = readdirSync(directory) } catch { return [] /* No ~/.ssh on this machine is a normal answer, not a failure. */ }
+  const keys: SshKey[] = []
+  for (const name of names.sort()) {
+    if (!name.startsWith('id_') || name.endsWith('.pub')) continue
+    const path = join(directory, name)
+    if (!existsSync(publicOf(path))) continue
+    let comment = ''
+    try {
+      // `ssh-ed25519 AAAAC3... user@host`: the comment is the third field, and it may be absent.
+      const fields = readFileSync(publicOf(path), 'utf8').trim().split(/\s+/)
+      comment = fields.slice(2).join(' ')
+    } catch { comment = '' /* An unreadable comment costs a label, not the key. */ }
+    keys.push({ name: basename(name), path, comment })
+  }
+  return keys
+}

package/src/routes.ts

@@ -0,0 +1,157 @@
+/**
+ * The device's two loopback routes: what keys exist, and whether a given one reaches a given host.
+ *
+ * These exist because the configuration page is a web page: it cannot read `~/.ssh` and cannot start ssh. The device
+ * process can, so it answers both and the page renders the answers. Nothing here writes configuration — the page
+ * saves through DSH's own configuration form — and nothing here reads a private key or keeps a session open.
+ *
+ * They are registered by the caller through `ctx.inject(['webServer'], …)` rather than listed in `inject`, and that is
+ * deliberate: a device with no web UI (a headless or CLI DSH) must still take work. It simply has no configuration
+ * page, which is a missing convenience, not a broken device.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { spawn } from 'node:child_process'
+import { listKeys, type SshKey } from './keys.ts'
+
+/** What one authentication test found. `ok` false is a normal answer, not an error. */
+export interface TestResult { ok: boolean; output: string }
+
+/** Runs one command and reports its exit status with its output; injectable so a test never starts ssh. */
+export type RunCommand = (argv: readonly string[]) => Promise<{ code: number | null; output: string }>
+
+/** The connection the page is testing, exactly the four fields it collects. */
+export interface TestInput { host: string; port: number; user: string; keyPath: string }
+
+/** How long one authentication test may take before it is reported as a timeout. */
+const TEST_TIMEOUT_MS = 15_000
+/** How much of ssh's output to keep: the reason is at the end, and a page shows a few lines. */
+const OUTPUT_KEEP = 2_048
+
+/**
+ * The argv of an authentication test.
+ *
+ * It asks for a command that does nothing (`true`) rather than opening a forward, because the question is only
+ * "does this key authenticate", and `BatchMode=yes` keeps it from stopping to ask for a passphrase nobody can type.
+ */
+export function testArgs({ host, port, user, keyPath }: TestInput): string[] {
+  return ['ssh', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=8', '-o', 'StrictHostKeyChecking=accept-new',
+    '-p', String(port), '-i', keyPath, `${user}@${host}`, 'true']
+}
+
+/** The default runner: a real ssh, resolving to its exit status either way. */
+const realRun: RunCommand = argv => new Promise(resolve => {
+  const child = spawn(argv[0]!, argv.slice(1), { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+  let output = ''
+  const collect = (chunk: Buffer) => { output = (output + chunk.toString('utf8')).slice(-OUTPUT_KEEP) }
+  child.stdout.on('data', collect)
+  child.stderr.on('data', collect)
+  const timer = setTimeout(() => { output = `${output}\n(timed out after ${TEST_TIMEOUT_MS / 1000}s)`.trim(); child.kill('SIGKILL') }, TEST_TIMEOUT_MS)
+  child.on('error', error => { clearTimeout(timer); resolve({ code: -1, output: `could not start ssh: ${error.message}` }) })
+  child.on('exit', code => { clearTimeout(timer); resolve({ code, output: output.trim() }) })
+})
+
+/** Writes one JSON answer. */
+function json(res: ServerResponse, status: number, value: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff' })
+  res.end(JSON.stringify(value))
+}
+
+/** Reads a JSON body, refusing anything larger than a form would send. */
+async function body(req: IncomingMessage, maxBytes = 16 * 1024): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const bytes = Buffer.from(chunk)
+    size += bytes.length
+    if (size > maxBytes) throw new Error(`request exceeds ${maxBytes} bytes`)
+    chunks.push(bytes)
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown }
+  catch { throw new Error('the request body is not JSON') }
+}
+
+/**
+ * The same-origin guard the hub uses, for the same reason.
+ *
+ * The marker header alone proves nothing: any local process can send it. What the browser will not let another origin
+ * do is send it *with* its own `Origin` intact, so an `Origin` that is present must be this page's. A request with no
+ * `Origin` at all (a local tool, a test) is allowed and the marker still has to be there.
+ */
+/** The loopback names a host header may carry; DSH's desktop build normalizes`::1` and `localhost` to each other. */
+const LOOPBACK = ['127.0.0.1', 'localhost', '::1', '[::1]']
+
+export function sameOrigin(req: Pick<IncomingMessage, 'headers'>, port: number, protocol = 'http:'): boolean {
+  const host = req.headers.host
+  if (host === undefined) return false
+  // `host:port` for IPv4 and names, `[::1]:port` for a bracketed IPv6 literal.
+  const match = /^(\[[^\]]+\]|[^:]+):(\d+)$/.exec(host)
+  if (match === null) return false
+  const [, name, seen] = match
+  // A request addressed to another host is a DNS-rebinding attempt, whatever its Origin says.
+  if (!LOOPBACK.includes(name!) || Number(seen) !== port) return false
+  // The scheme comes from the service: a TLS-terminated DSH sends `https://` and would otherwise be refused here.
+  return req.headers['x-orchestrator-request'] === '1'
+    && (req.headers.origin === undefined || req.headers.origin === `${protocol}//${host}`)
+}
+
+/** The prefix both routes live under; it never collides with the hub's `/orchestrator`. */
+export const NODE_PREFIX = '/foreman-node'
+
+export interface RouteHost {
+  /** The web server service: the only thing this module needs from the host. */
+  register(route: { kind: 'prefix'; path: string
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> }): () => void
+  /** The port the web server listens on, used by the same-origin check. */
+  port: number
+  /** The scheme the web server serves, so a TLS-terminated host's `https://` origin is accepted. */
+  protocol?: string
+}
+
+/**
+ * Registers the routes and returns their disposer.
+ *
+ * `listKeys` and `run` are injectable so tests can answer without a filesystem or a child process; production passes
+ * a directory and the real runner.
+ */
+export function registerNodeRoutes(host: RouteHost, directory: string, run: RunCommand = realRun): () => void {
+  return host.register({ kind: 'prefix', path: NODE_PREFIX, handler: async (req, res) => {
+    // The guard runs before routing: an unauthenticated caller learns nothing about what exists here.
+    if (!sameOrigin(req, host.port, host.protocol)) { json(res, 403, { error: 'Same-origin request required' }); return }
+    const url = new URL(req.url ?? '/', 'http://localhost')
+    const method = req.method ?? 'GET'
+    try {
+      if (url.pathname === `${NODE_PREFIX}/api/keys` && method === 'GET') {
+        const keys: SshKey[] = listKeys(directory)
+        json(res, 200, { keys, directory })
+        return
+      }
+      if (url.pathname === `${NODE_PREFIX}/api/test` && method === 'POST') {
+        const input = (await body(req)) as Partial<TestInput>
+        if (typeof input.host !== 'string' || input.host.trim() === '' || typeof input.user !== 'string' || input.user.trim() === ''
+          || typeof input.keyPath !== 'string' || input.keyPath.trim() === '') {
+          json(res, 400, { error: 'host, user and keyPath are required' })
+          return
+        }
+        const port = typeof input.port === 'number' && Number.isInteger(input.port) && input.port > 0 && input.port <= 65535 ? input.port : 22
+        // Only a key this machine already offers may be tested. The page can only pick from that list, so anything
+        // else is either a stale form or a caller asking this process to run ssh against a path of its choosing;
+        // neither is a reason to start a process.
+        const keyPath = input.keyPath.trim()
+        const known = listKeys(directory).find(key => key.path === keyPath)
+        if (known === undefined) {
+          json(res, 400, { error: `no key at ${keyPath}; the page lists the ones this machine has` })
+          return
+        }
+        const result = await run(testArgs({ host: input.host.trim(), port, user: input.user.trim(), keyPath }))
+        // A refused key is an answer the page shows, not a server error: 200 with `ok: false` and ssh's own words.
+        json(res, 200, { ok: result.code === 0, output: result.output })
+        return
+      }
+      json(res, 404, { error: 'Unknown operation' })
+    } catch (error) {
+      json(res, 400, { error: error instanceof Error ? error.message : String(error) })
+    }
+  } })
+}