@astrofoundry/pi-astro 0.18.5 → 0.19.0

package/specialists/edge/run.ts

@@ -0,0 +1,224 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readConfig } from "../lib/config.ts";
+import { ServiceError, UsageError } from "../lib/errors.ts";
+import { main } from "../lib/main.ts";
+import { printJson, printRaw } from "../lib/output.ts";
+import { specialistsHome, workDir } from "../lib/paths.ts";
+import { run } from "../lib/proc.ts";
+import { REPO_HELP, ensureCheckout, repoCommand, repoStatus, safeRepoPath, type RepoSpec } from "../lib/repo.ts";
+import { secretPath } from "../lib/secrets.ts";
+import { sshFixed } from "../lib/ssh.ts";
+import { openTunnel } from "../lib/tunnel.ts";
+
+const SERVICE = "edge";
+
+interface EdgeConfig extends Record<string, string | number> {
+    gcloud: string;
+    /** Python 3.10+ interpreter for gcloud; the Homebrew cask installs none of its own. */
+    gcloudPython: string;
+    project: string;
+    zone: string;
+    instance: string;
+    serviceAccount: string;
+    /** Local port of the IAP tunnel to the instance's SSH port. */
+    iapLocalPort: number;
+    sshUser: string;
+    publicIp: string;
+    /** Public hostname whose OpenID discovery document `probe` fetches through the VPS address. */
+    probeHost: string;
+    homelabRemote: string;
+    homelabBranch: string;
+    /** Folder of the homelab repository this specialist may write. */
+    repoArea: string;
+    /** Tracked nginx configuration deployed by `deploy-nginx`. */
+    nginxConf: string;
+}
+
+const SHAPE = {
+    gcloud: "string",
+    gcloudPython: "string",
+    project: "string",
+    zone: "string",
+    instance: "string",
+    serviceAccount: "string",
+    iapLocalPort: "number",
+    sshUser: "string",
+    publicIp: "string",
+    probeHost: "string",
+    homelabRemote: "string",
+    homelabBranch: "string",
+    repoArea: "string",
+    nginxConf: "string",
+} as const;
+
+/** Fixed remote commands; the forced command on the VPS accepts exactly these names. */
+export const VPS_COMMANDS: Readonly<Record<string, { args: number; help: string; stdin?: true }>> = {
+    status: { args: 0, help: "unit states, WireGuard handshake age, pending reboot, kernel, uptime" },
+    "nginx-conf": { args: 0, help: "print the installed /etc/nginx/nginx.conf" },
+    "nginx-test": { args: 0, help: "nginx -t on the installed configuration" },
+    journal: { args: 2, help: "journal <unit> <since>, e.g. journal nginx '1 hour ago'" },
+    wg: { args: 0, help: "wg show wg0 (peers, endpoints, handshakes)" },
+    bouncer: { args: 0, help: "crowdsec-firewall-bouncer status and the nftables block set" },
+    updates: { args: 0, help: "upgradable packages and the packages that need a reboot" },
+    "deploy-nginx": { args: 0, help: "install the tracked nginx.conf from the pushed homelab checkout (nginx -t, install, reload)", stdin: true },
+    reboot: { args: 0, help: "systemctl reboot (needs --confirm)" },
+};
+
+export const VPS_UNITS = ["nginx", "wg-quick@wg0", "crowdsec-firewall-bouncer", "wazuh-agent", "rsyslog", "unattended-upgrades", "ssh"];
+const SINCE = /^[A-Za-z0-9 :\-+]{1,40}$/;
+
+const HELP = `edge specialist (Frontdoor VPS through an IAP tunnel)
+
+  probe                       GET the public OpenID discovery document through the VPS address
+  vps <command> [args]        fixed operations through the forced-command SSH key
+${Object.entries(VPS_COMMANDS)
+    .map(([name, c]) => `      ${name.padEnd(14)} ${c.help}`)
+    .join("\n")}
+  vps reboot --confirm        reboot; run probe first and after
+${REPO_HELP}
+      (homelab repository; writes are limited to the configured area)
+
+deploy-nginx refuses when the checkout is dirty or differs from origin: commit and push first.`;
+
+export function buildVpsRemote(args: string[]): { remote: string; stdin: boolean } {
+    const [name, ...rest] = args;
+    const spec = name === undefined ? undefined : VPS_COMMANDS[name];
+    if (!spec) throw new UsageError(`unknown vps command: ${name ?? "(none)"}`);
+    if (name === "reboot") {
+        if (rest.length !== 1 || rest[0] !== "--confirm") throw new UsageError("vps reboot --confirm (probe first; the public path goes down for about a minute)");
+        return { remote: "reboot", stdin: false };
+    }
+    if (rest.length !== spec.args) throw new UsageError(`vps ${name} takes ${spec.args} argument(s)`);
+    if (name === "journal") {
+        if (!VPS_UNITS.includes(rest[0])) throw new UsageError(`unit must be one of ${VPS_UNITS.join(", ")}`);
+        if (!SINCE.test(rest[1])) throw new UsageError("since: letters, digits, spaces, colon, plus, minus only");
+    }
+    return { remote: [name, ...rest].join(" "), stdin: spec.stdin === true };
+}
+
+function gcloudEnv(config: EdgeConfig): Record<string, string> {
+    return {
+        CLOUDSDK_CONFIG: workDir("gcloud"),
+        CLOUDSDK_PYTHON: config.gcloudPython,
+        CLOUDSDK_CORE_DISABLE_PROMPTS: "1",
+    };
+}
+
+async function activateServiceAccount(config: EdgeConfig): Promise<void> {
+    const result = await run(
+        config.gcloud,
+        ["auth", "activate-service-account", config.serviceAccount, "--key-file", secretPath(SERVICE, "GCP_SA_KEY_JSON"), "--project", config.project, "--quiet"],
+        { env: gcloudEnv(config), timeoutMs: 60_000 },
+    );
+    if (result.code !== 0) throw new ServiceError(`gcloud auth activate-service-account failed: ${result.stderr.trim()}`);
+}
+
+/** Opens the IAP tunnel, runs one fixed command over it, closes the tunnel. */
+async function overTunnel(config: EdgeConfig, remote: string, timeoutMs: number, input?: string): Promise<{ stdout: string; stderr: string; code: number }> {
+    await activateServiceAccount(config);
+    const tunnel = await openTunnel(
+        config.gcloud,
+        [
+            "compute",
+            "start-iap-tunnel",
+            config.instance,
+            "22",
+            `--local-host-port=localhost:${config.iapLocalPort}`,
+            "--zone",
+            config.zone,
+            "--project",
+            config.project,
+            "--quiet",
+        ],
+        { env: gcloudEnv(config), port: config.iapLocalPort, readyTimeoutMs: 45_000 },
+    );
+    try {
+        return await sshFixed(
+            {
+                host: "127.0.0.1",
+                port: config.iapLocalPort,
+                hostKeyAlias: config.instance,
+                user: config.sshUser,
+                keyFile: secretPath(SERVICE, "SSH_KEY_FRONTDOOR"),
+                knownHostsFile: join(specialistsHome(), "config", "known_hosts"),
+            },
+            remote,
+            timeoutMs,
+            input,
+        );
+    } finally {
+        await tunnel.close();
+    }
+}
+
+function repoSpec(config: EdgeConfig): RepoSpec {
+    return {
+        service: SERVICE,
+        checkoutName: "homelab",
+        remote: config.homelabRemote,
+        branch: config.homelabBranch,
+        deployKeyField: "HOMELAB_DEPLOY_KEY",
+        writeRoot: config.repoArea,
+        help: HELP,
+    };
+}
+
+/** The nginx.conf to deploy: only what origin already has. */
+async function trackedNginxConf(config: EdgeConfig): Promise<string> {
+    const spec = repoSpec(config);
+    const dir = await ensureCheckout(spec);
+    const status = await repoStatus(spec, dir);
+    if (status.changed.length > 0) throw new UsageError(`checkout has uncommitted changes: ${status.changed.join(", ")}; commit and push first`);
+    if (status.ahead > 0) throw new UsageError(`checkout is ${status.ahead} commit(s) ahead of origin; push first`);
+    if (status.behind > 0) throw new UsageError(`checkout is ${status.behind} commit(s) behind origin; run git pull first`);
+    return readFileSync(safeRepoPath(dir, config.nginxConf), "utf-8");
+}
+
+async function vps(config: EdgeConfig, args: string[]): Promise<number> {
+    const { remote, stdin } = buildVpsRemote(args);
+    const input = stdin ? await trackedNginxConf(config) : undefined;
+    const result = await overTunnel(config, remote, remote === "reboot" ? 30_000 : 120_000, input);
+    if (result.stdout.length > 0) printRaw(result.stdout);
+    if (remote === "reboot") {
+        printJson({ rebooting: true, note: "the ssh session ends with the reboot; run probe until it succeeds, then vps status" });
+        return 0;
+    }
+    if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `vps ${args[0]} exited ${result.code}`);
+    return 0;
+}
+
+async function probe(config: EdgeConfig): Promise<number> {
+    const url = `https://${config.probeHost}/.well-known/openid-configuration`;
+    const result = await run(
+        "/usr/bin/curl",
+        ["--silent", "--output", "/dev/null", "--max-time", "5", "--resolve", `${config.probeHost}:443:${config.publicIp}`, "--write-out", "%{http_code} %{time_total}", url],
+        { timeoutMs: 15_000 },
+    );
+    const [httpCode, seconds] = result.stdout.trim().split(" ");
+    const ok = result.code === 0 && httpCode === "200";
+    printJson({ ok, url, via: config.publicIp, httpCode: httpCode || null, seconds: seconds ? Number(seconds) : null, curlExit: result.code });
+    return ok ? 0 : 1;
+}
+
+export async function command(args: string[]): Promise<number> {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
+        printRaw(HELP);
+        return 0;
+    }
+    const config = readConfig<EdgeConfig>(SERVICE, SHAPE);
+    switch (args[0]) {
+        case "probe":
+            return probe(config);
+        case "vps":
+            return vps(config, args.slice(1));
+        case "git":
+            return repoCommand(repoSpec(config), args.slice(1));
+        default:
+            throw new UsageError(`unknown command: ${args[0]}\n${HELP}`);
+    }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    await main(SERVICE, command);
+}

package/specialists/entry/remote/spc-edge-frontdoor-entry.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+# Forced command for the spc-edge key on the Frontdoor VPS (user spc-edge).
+# authorized_keys line:
+#   command="/usr/local/sbin/spc-edge-frontdoor-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 AAAA... spc-edge-frontdoor@cortex
+# Privileged steps go through the exact sudoers entries in sudoers-spc-edge.
+set -eu
+cmd="${SSH_ORIGINAL_COMMAND:-}"
+name="${cmd%% *}"
+rest=""
+[ "$cmd" != "$name" ] && rest="${cmd#* }"
+since_ok() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9 :+-]{1,40}$'; }
+units="nginx wg-quick@wg0 crowdsec-firewall-bouncer wazuh-agent rsyslog"
+staged=/var/lib/spc-edge/nginx.conf.new
+
+case "$name" in
+  status)
+    for s in $units; do printf '%-28s %s\n' "$s" "$(systemctl is-active "$s" || true)"; done
+    printf '%-28s %s\n' "wireguard handshake" "$(sudo -n /usr/bin/wg show wg0 latest-handshakes | awk '{ print systime()-$2 "s ago" }')"
+    printf '%-28s %s\n' "reboot required" "$([ -f /var/run/reboot-required ] && echo yes || echo no)"
+    printf '%-28s %s\n' "kernel" "$(uname -r)"
+    printf '%-28s %s\n' "uptime" "$(uptime -p)" ;;
+  nginx-conf) cat /etc/nginx/nginx.conf ;;
+  nginx-test) sudo -n /usr/sbin/nginx -t ;;
+  journal)
+    unit="${rest%% *}"; since="${rest#* }"
+    case "$unit" in nginx|wg-quick@wg0|crowdsec-firewall-bouncer|wazuh-agent|rsyslog|unattended-upgrades|ssh) ;; *) echo "bad unit" >&2; exit 2 ;; esac
+    since_ok "$since" || { echo "bad since" >&2; exit 2; }
+    journalctl -u "$unit" --since "$since" --no-pager -n 200 ;;
+  wg) sudo -n /usr/bin/wg show wg0 ;;
+  bouncer)
+    systemctl status crowdsec-firewall-bouncer --no-pager --lines=5 || true
+    sudo -n /usr/sbin/nft list set ip crowdsec crowdsec-blacklists ;;
+  updates)
+    apt list --upgradable 2>/dev/null
+    if [ -f /var/run/reboot-required.pkgs ]; then echo "reboot required by:"; cat /var/run/reboot-required.pkgs; fi ;;
+  deploy-nginx)
+    umask 022
+    cat > "$staged"
+    sudo -n /usr/sbin/nginx -t -c "$staged"
+    sudo -n /usr/bin/install -o root -g root -m 644 "$staged" /etc/nginx/nginx.conf
+    rm -f "$staged"
+    sudo -n /usr/sbin/nginx -t
+    sudo -n /usr/bin/systemctl reload nginx
+    systemctl is-active nginx ;;
+  reboot) sudo -n /usr/bin/systemctl reboot ;;
+  *) echo "refused: $cmd" >&2; exit 2 ;;
+esac

package/specialists/entry/remote/spc-edge-frontdoor-install.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# One-time setup of the spc-edge user on the Frontdoor VPS. Run as root with
+# these files in /tmp: spc-edge-frontdoor-entry, spc-edge-frontdoor-sudoers,
+# spc-edge-frontdoor.pub. Idempotent.
+set -eu
+for f in spc-edge-frontdoor-entry spc-edge-frontdoor-sudoers spc-edge-frontdoor.pub; do
+  [ -f "/tmp/$f" ] || { echo "missing /tmp/$f" >&2; exit 2; }
+done
+id spc-edge >/dev/null 2>&1 || useradd --system --create-home --home-dir /var/lib/spc-edge --shell /bin/sh --groups systemd-journal spc-edge
+install -o root -g root -m 0755 /tmp/spc-edge-frontdoor-entry /usr/local/sbin/spc-edge-frontdoor-entry
+install -o root -g root -m 0440 /tmp/spc-edge-frontdoor-sudoers /etc/sudoers.d/spc-edge
+visudo -cf /etc/sudoers.d/spc-edge
+install -d -o spc-edge -g spc-edge -m 0700 /var/lib/spc-edge/.ssh
+printf 'command="/usr/local/sbin/spc-edge-frontdoor-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding %s\n' "$(cat /tmp/spc-edge-frontdoor.pub)" > /var/lib/spc-edge/.ssh/authorized_keys
+chown spc-edge:spc-edge /var/lib/spc-edge/.ssh/authorized_keys
+chmod 0600 /var/lib/spc-edge/.ssh/authorized_keys
+rm -f /tmp/spc-edge-frontdoor-entry /tmp/spc-edge-frontdoor-sudoers /tmp/spc-edge-frontdoor.pub
+echo "spc-edge ready: $(id spc-edge)"
+echo "sshd key sources:"
+sshd -T 2>/dev/null | grep -Ei '^(authorizedkeysfile|authorizedkeyscommand|pubkeyauthentication) ' || true

package/specialists/entry/remote/spc-edge-frontdoor-sudoers

@@ -0,0 +1,2 @@
+# /etc/sudoers.d/spc-edge (0440): the exact privileged commands spc-edge-frontdoor-entry runs.
+spc-edge ALL=(root) NOPASSWD: /usr/sbin/nginx -t, /usr/sbin/nginx -t -c /var/lib/spc-edge/nginx.conf.new, /usr/bin/install -o root -g root -m 644 /var/lib/spc-edge/nginx.conf.new /etc/nginx/nginx.conf, /usr/bin/systemctl reload nginx, /usr/bin/systemctl reboot, /usr/bin/wg show wg0, /usr/bin/wg show wg0 latest-handshakes, /usr/sbin/nft list set ip crowdsec crowdsec-blacklists

package/specialists/entry/remote/spc-security-obs-entry.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+# Forced command for the spc-security key on VM 106 (user observability, passwordless sudo).
+# authorized_keys line:
+#   command="/usr/local/sbin/spc-security-obs-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 AAAA... spc-security-obs@cortex
+set -eu
+cmd="${SSH_ORIGINAL_COMMAND:-}"
+name="${cmd%% *}"
+rest=""
+[ "$cmd" != "$name" ] && rest="${cmd#* }"
+since_ok() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9 :+-]{1,40}$'; }
+int_ok() { printf '%s' "$1" | grep -Eq '^[1-9][0-9]{0,3}$'; }
+name_ok() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$'; }
+ip_ok() { printf '%s' "$1" | grep -Eq '^[0-9]{1,3}(\.[0-9]{1,3}){3}$'; }
+wazuh=observability-wazuh-manager-1
+
+case "$name" in
+  status)
+    for s in rsyslog crowdsec nftables docker security-attention.timer update-home-whitelist.timer; do
+      printf '%-32s %s\n' "$s" "$(systemctl is-active "$s" || true)"
+    done
+    sudo -n docker ps --format '{{.Names}} {{.Status}}' ;;
+  attention) sudo -n /usr/local/sbin/security-attention status ;;
+  agents) sudo -n docker exec "$wazuh" /var/ossec/bin/agent_control -l ;;
+  alerts)
+    days="${rest%% *}"; ip=""; [ "$rest" != "$days" ] && ip="${rest#* }"
+    int_ok "$days" || { echo "bad days" >&2; exit 2; }
+    if [ -n "$ip" ]; then
+      ip_ok "$ip" || { echo "bad ip" >&2; exit 2; }
+      sudo -n cscli alerts list --since "${days}d" -l 0 -o json --ip "$ip"
+    else
+      sudo -n cscli alerts list --since "${days}d" -l 0 -o json
+    fi ;;
+  decisions) sudo -n cscli decisions list -l 0 -o json ;;
+  bouncers) sudo -n cscli bouncers list -o json ;;
+  metrics) sudo -n cscli metrics -o json ;;
+  wazuh-alerts)
+    int_ok "$rest" || { echo "bad days" >&2; exit 2; }
+    sudo -n docker exec "$wazuh" sh -c "find /var/ossec/logs/alerts -type f -name '*.json.gz' -mtime -$((rest + 1)) -exec zcat {} + 2>/dev/null; cat /var/ossec/logs/alerts/alerts.json" ;;
+  wazuh-log)
+    int_ok "$rest" || { echo "bad lines" >&2; exit 2; }
+    sudo -n docker logs --tail "$rest" "$wazuh" 2>&1 ;;
+  remote-hosts) sudo -n find /var/log/remote -mindepth 2 -maxdepth 2 -name '*.log' -printf '%P\n' | sort ;;
+  remote-log)
+    set -- $rest
+    [ "$#" -eq 3 ] || { echo "remote-log <host> <program> <lines>" >&2; exit 2; }
+    name_ok "$1" && name_ok "$2" && int_ok "$3" || { echo "bad argument" >&2; exit 2; }
+    sudo -n tail -n "$3" "/var/log/remote/$1/$2.log" ;;
+  journal)
+    unit="${rest%% *}"; since="${rest#* }"
+    case "$unit" in crowdsec|rsyslog|nftables|docker|security-attention|update-home-whitelist|ssh) ;; *) echo "bad unit" >&2; exit 2 ;; esac
+    since_ok "$since" || { echo "bad since" >&2; exit 2; }
+    sudo -n journalctl -u "$unit" --since "$since" --no-pager -n 200 ;;
+  *) echo "refused: $cmd" >&2; exit 2 ;;
+esac

package/specialists/install/install.sh

@@ -11,9 +11,9 @@ bin="$root/bin"
 
 [ -d "$src/specialists/lib" ] || { echo "not a pi-astro package: $src" >&2; exit 2; }
 mkdir -p "$bin" "$root/config" "$root/secrets" "$root/work"
-rm -rf "$bin/lib" "$bin/arcane" "$bin/identity" "$bin/network"
+rm -rf "$bin/lib" "$bin/arcane" "$bin/identity" "$bin/network" "$bin/dns" "$bin/edge" "$bin/security"
 cp -R "$src/specialists/lib" "$bin/lib"
-for s in arcane identity network; do
+for s in arcane identity network dns edge security; do
   mkdir -p "$bin/$s"
   cp "$src/specialists/$s/run.ts" "$bin/$s/run.ts"
 done

package/specialists/lib/repo.ts

@@ -0,0 +1,171 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { ServiceError, UsageError } from "./errors.ts";
+import { printJson, printRaw } from "./output.ts";
+import { specialistsHome, workDir } from "./paths.ts";
+import { run } from "./proc.ts";
+import { secretPath } from "./secrets.ts";
+
+/** A Git repository the specialist edits through a write deploy key. */
+export interface RepoSpec {
+    /** Specialist that owns the deploy key. */
+    service: string;
+    /** Folder name under ~/.specialists/work. */
+    checkoutName: string;
+    remote: string;
+    branch: string;
+    /** Secret field holding the private deploy key. */
+    deployKeyField: string;
+    /** Folder inside the repository that `git write` may touch; the whole checkout when absent. */
+    writeRoot?: string;
+    /** Wrapper help, printed with usage errors. */
+    help: string;
+}
+
+export const REPO_HELP = `  git status                  branch, ahead/behind, changed files of the repository checkout
+  git pull                    fast-forward the checkout from origin
+  git ls [dir]                list files in the checkout
+  git show <path>             print a file from the checkout
+  git diff                    unstaged and staged changes
+  git log [n]                 last n commits (default 10)
+  git write <path> <content>  write a file inside the checkout (creates folders)
+  git commit <message>        stage everything and commit
+  git push                    push the branch to origin`;
+
+const TIMEOUT_MS = 240_000;
+
+export interface RepoStatus {
+    branch: string;
+    ahead: number;
+    behind: number;
+    changed: string[];
+}
+
+function gitEnv(spec: RepoSpec): Record<string, string> {
+    const key = secretPath(spec.service, spec.deployKeyField);
+    const knownHosts = join(specialistsHome(), "config", "known_hosts");
+    return {
+        GIT_SSH_COMMAND: `/usr/bin/ssh -i ${key} -o IdentitiesOnly=yes -o BatchMode=yes -o UserKnownHostsFile=${knownHosts} -o StrictHostKeyChecking=accept-new`,
+        GIT_AUTHOR_NAME: "specialist",
+        GIT_AUTHOR_EMAIL: "specialists@monadeo.com",
+        GIT_COMMITTER_NAME: "specialist",
+        GIT_COMMITTER_EMAIL: "specialists@monadeo.com",
+    };
+}
+
+async function git(spec: RepoSpec, dir: string, args: string[]): Promise<string> {
+    const result = await run("/usr/bin/git", ["-C", dir, ...args], { env: gitEnv(spec), timeoutMs: TIMEOUT_MS });
+    if (result.code !== 0) throw new ServiceError(`git ${args[0]} failed: ${result.stderr.trim()}`);
+    return result.stdout;
+}
+
+export async function ensureCheckout(spec: RepoSpec): Promise<string> {
+    const dir = workDir(spec.checkoutName);
+    if (existsSync(join(dir, ".git"))) return dir;
+    mkdirSync(dirname(dir), { recursive: true, mode: 0o700 });
+    const result = await run("/usr/bin/git", ["clone", "--branch", spec.branch, "--single-branch", spec.remote, dir], {
+        env: gitEnv(spec),
+        timeoutMs: TIMEOUT_MS,
+    });
+    if (result.code !== 0) throw new ServiceError(`git clone failed: ${result.stderr.trim()}`);
+    return dir;
+}
+
+export function safeRepoPath(dir: string, rel: string): string {
+    if (rel.length === 0 || rel.startsWith("/") || rel.split("/").includes("..") || rel.includes("\0")) {
+        throw new UsageError(`invalid repository path: ${rel}`);
+    }
+    const target = resolve(dir, rel);
+    const inside = relative(dir, target);
+    if (inside.startsWith("..") || inside.startsWith(".git/") || inside === ".git") {
+        throw new UsageError(`path escapes the checkout: ${rel}`);
+    }
+    return target;
+}
+
+/** `git write` target; refuses paths outside `writeRoot` when the spec has one. */
+export function safeWritePath(dir: string, rel: string, writeRoot?: string): string {
+    const target = safeRepoPath(dir, rel);
+    if (writeRoot !== undefined) {
+        const inside = relative(resolve(dir, writeRoot), target);
+        if (inside.length === 0 || inside.startsWith("..")) throw new UsageError(`writes are limited to ${writeRoot}/`);
+    }
+    return target;
+}
+
+/** Fetches origin and reports how the checkout relates to it. */
+export async function repoStatus(spec: RepoSpec, dir: string): Promise<RepoStatus> {
+    await git(spec, dir, ["fetch", "--quiet", "origin", spec.branch]);
+    const branch = (await git(spec, dir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+    const counts = (await git(spec, dir, ["rev-list", "--left-right", "--count", `HEAD...origin/${spec.branch}`])).trim();
+    const [ahead, behind] = counts.split(/\s+/).map(Number);
+    const changed = (await git(spec, dir, ["status", "--porcelain"])).split("\n").filter(Boolean);
+    return { branch, ahead, behind, changed };
+}
+
+export async function repoCommand(spec: RepoSpec, args: string[]): Promise<number> {
+    const [sub, ...rest] = args;
+    const dir = await ensureCheckout(spec);
+    switch (sub) {
+        case "status":
+            printJson(await repoStatus(spec, dir));
+            return 0;
+        case "pull":
+            printRaw(await git(spec, dir, ["pull", "--ff-only", "origin", spec.branch]));
+            return 0;
+        case "diff":
+            printRaw((await git(spec, dir, ["diff", "HEAD"])) || "(no changes)");
+            return 0;
+        case "ls": {
+            if (rest.length > 1) throw new UsageError("git ls [dir]");
+            const target = rest[0] === undefined ? dir : safeRepoPath(dir, rest[0]);
+            if (!existsSync(target) || !statSync(target).isDirectory()) throw new UsageError(`not a directory in the checkout: ${rest[0] ?? "."}`);
+            printJson(
+                readdirSync(target, { withFileTypes: true })
+                    .filter((e) => e.name !== ".git")
+                    .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+                    .sort(),
+            );
+            return 0;
+        }
+        case "show": {
+            if (rest.length !== 1) throw new UsageError("git show <path>");
+            const target = safeRepoPath(dir, rest[0]);
+            if (!existsSync(target) || !statSync(target).isFile()) throw new UsageError(`not a file in the checkout: ${rest[0]}`);
+            printRaw(readFileSync(target, "utf-8"));
+            return 0;
+        }
+        case "log": {
+            const n = rest[0] === undefined ? 10 : Number(rest[0]);
+            if (!Number.isInteger(n) || n <= 0 || n > 200) throw new UsageError("git log [n]: n must be 1..200");
+            printRaw(await git(spec, dir, ["log", `-n${n}`, "--format=%h %ad %s", "--date=short"]));
+            return 0;
+        }
+        case "write": {
+            if (rest.length !== 2) throw new UsageError("git write <path> <content>");
+            const target = safeWritePath(dir, rest[0], spec.writeRoot);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, rest[1].endsWith("\n") ? rest[1] : `${rest[1]}\n`, { mode: 0o600 });
+            printJson({ written: rest[0], bytes: Buffer.byteLength(rest[1]) });
+            return 0;
+        }
+        case "commit": {
+            const message = rest.join(" ").trim();
+            if (message.length === 0) throw new UsageError("git commit <message>");
+            await git(spec, dir, ["add", "--all"]);
+            const staged = (await git(spec, dir, ["diff", "--cached", "--name-only"])).split("\n").filter(Boolean);
+            if (staged.length === 0) throw new UsageError("nothing to commit");
+            await git(spec, dir, ["commit", "--quiet", "-m", message]);
+            printJson({ committed: (await git(spec, dir, ["rev-parse", "--short", "HEAD"])).trim(), files: staged });
+            return 0;
+        }
+        case "push": {
+            const result = await run("/usr/bin/git", ["-C", dir, "push", "origin", spec.branch], { env: gitEnv(spec), timeoutMs: TIMEOUT_MS });
+            if (result.code !== 0) throw new ServiceError(`git push failed: ${result.stderr.trim()}`);
+            printRaw(result.stderr.trim() || "pushed");
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown git subcommand: ${sub ?? "(none)"}\n${spec.help}`);
+    }
+}

package/specialists/lib/ssh.ts

@@ -5,32 +5,34 @@ export interface SshTarget {
     user: string;
     keyFile: string;
     knownHostsFile: string;
+    /** TCP port; ssh's default when absent. */
+    port?: number;
+    /** known_hosts name when `host` is a local tunnel endpoint. */
+    hostKeyAlias?: string;
 }
 
 /**
  * Runs one fixed remote command through a key that the target pins to a
  * forced command. `remote` is a string from the wrapper's own table, never
- * agent input.
+ * agent input. `input`, when given, becomes the remote command's stdin.
  */
-export function sshFixed(target: SshTarget, remote: string, timeoutMs: number): Promise<RunResult> {
-    return run(
-        "/usr/bin/ssh",
-        [
-            "-i",
-            target.keyFile,
-            "-o",
-            "IdentitiesOnly=yes",
-            "-o",
-            "BatchMode=yes",
-            "-o",
-            `UserKnownHostsFile=${target.knownHostsFile}`,
-            "-o",
-            "StrictHostKeyChecking=accept-new",
-            "-o",
-            "ConnectTimeout=10",
-            `${target.user}@${target.host}`,
-            remote,
-        ],
-        { timeoutMs },
-    );
+export function sshFixed(target: SshTarget, remote: string, timeoutMs: number, input?: string): Promise<RunResult> {
+    const args = [
+        "-i",
+        target.keyFile,
+        "-o",
+        "IdentitiesOnly=yes",
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        `UserKnownHostsFile=${target.knownHostsFile}`,
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-o",
+        "ConnectTimeout=10",
+    ];
+    if (target.port !== undefined) args.push("-p", String(target.port));
+    if (target.hostKeyAlias !== undefined) args.push("-o", `HostKeyAlias=${target.hostKeyAlias}`);
+    args.push(`${target.user}@${target.host}`, remote);
+    return run("/usr/bin/ssh", args, { timeoutMs, input });
 }

package/specialists/lib/tunnel.test.ts

@@ -0,0 +1,44 @@
+import { connect } from "node:net";
+import { describe, expect, it } from "vitest";
+import { ServiceError } from "./errors.ts";
+import { openTunnel } from "./tunnel.ts";
+
+function freePort(): Promise<number> {
+    return new Promise((resolve, reject) => {
+        import("node:net").then(({ createServer }) => {
+            const server = createServer();
+            server.listen(0, "127.0.0.1", () => {
+                const address = server.address();
+                server.close(() => (typeof address === "object" && address ? resolve(address.port) : reject(new Error("no port"))));
+            });
+        });
+    });
+}
+
+describe("openTunnel", () => {
+    it("resolves once the process listens and closes it afterwards", async () => {
+        const port = await freePort();
+        const script = `setTimeout(() => require("node:net").createServer().listen(${port}, "127.0.0.1"), 300); setInterval(() => {}, 1000);`;
+        const tunnel = await openTunnel(process.execPath, ["-e", script], { env: {}, port, readyTimeoutMs: 5000 });
+        await tunnel.close();
+        const closed = await new Promise<boolean>((resolve) => {
+            const socket = connect({ port, host: "127.0.0.1" });
+            socket.once("connect", () => {
+                socket.destroy();
+                resolve(false);
+            });
+            socket.once("error", () => resolve(true));
+        });
+        expect(closed).toBe(true);
+    });
+
+    it("reports a process that exits before listening", async () => {
+        const port = await freePort();
+        await expect(openTunnel("/bin/sh", ["-c", "echo denied >&2; exit 3"], { env: {}, port, readyTimeoutMs: 5000 })).rejects.toThrow(/exited with code 3: denied/);
+    });
+
+    it("gives up when nothing listens in time", async () => {
+        const port = await freePort();
+        await expect(openTunnel("/bin/sleep", ["5"], { env: {}, port, readyTimeoutMs: 600 })).rejects.toThrow(ServiceError);
+    });
+});