@astrofoundry/pi-astro 0.17.1 → 0.18.2

package/specialists/lib/sanitize.ts

@@ -0,0 +1,64 @@
+/**
+ * Output filters. Arcane responses carry container environments, labels,
+ * mounts, and Compose content; Zitadel responses can carry secrets. Both are
+ * removed before anything reaches the agent.
+ */
+export const ARCANE_DENIED_KEYS: readonly string[] = [
+    "env",
+    "envs",
+    "environment",
+    "environmentVariables",
+    "labels",
+    "mounts",
+    "mountPoints",
+    "binds",
+    "compose",
+    "composeContent",
+    "composeFile",
+    "content",
+    "runtime",
+    "hostConfig",
+    "config",
+    "command",
+    "cmd",
+    "entrypoint",
+    "args",
+];
+
+export const SECRET_KEY_PATTERN = /(secret|token|password|passwd|privatekey|private_key|apikey|api_key|pat|credential)s?$/i;
+
+export function stripKeys(value: unknown, denied: readonly string[]): unknown {
+    if (Array.isArray(value)) return value.map((item) => stripKeys(item, denied));
+    if (typeof value === "object" && value !== null) {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            if (denied.includes(k)) continue;
+            out[k] = stripKeys(v, denied);
+        }
+        return out;
+    }
+    return value;
+}
+
+export function redactSecrets(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(redactSecrets);
+    if (typeof value === "object" && value !== null) {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            out[k] = SECRET_KEY_PATTERN.test(k) && typeof v === "string" ? "[redacted]" : redactSecrets(v);
+        }
+        return out;
+    }
+    return value;
+}
+
+/** Applies a filter to JSON text; non-JSON text passes through untouched. */
+export function filterJsonText(text: string, filter: (value: unknown) => unknown): string {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) return text;
+    try {
+        return JSON.stringify(filter(JSON.parse(trimmed)), null, 2);
+    } catch {
+        return text;
+    }
+}

package/specialists/lib/secrets.ts

@@ -0,0 +1,28 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ServiceError } from "./errors.ts";
+import { secretsDir } from "./paths.ts";
+
+const NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/** Path of one secret file; the name must be UPPER_SNAKE so it cannot escape the folder. */
+export function secretPath(service: string, field: string): string {
+    if (!NAME.test(field)) throw new ServiceError(`invalid secret name: ${field}`);
+    return join(secretsDir(service), field);
+}
+
+/**
+ * Read a secret written by specialist-provision. Refuses files readable by
+ * anyone but the owner, so a permission slip is caught before use.
+ */
+export function readSecret(service: string, field: string): string {
+    const path = secretPath(service, field);
+    let mode: number;
+    try {
+        mode = statSync(path).mode;
+    } catch {
+        throw new ServiceError(`secret ${field} for ${service} is missing; run specialist-cli provision`);
+    }
+    if ((mode & 0o077) !== 0) throw new ServiceError(`secret ${path} must be mode 0600`);
+    return readFileSync(path, "utf-8").replace(/\r?\n$/, "");
+}

package/specialists/lib/ssh.ts

@@ -0,0 +1,36 @@
+import { run, type RunResult } from "./proc.ts";
+
+export interface SshTarget {
+    host: string;
+    user: string;
+    keyFile: string;
+    knownHostsFile: 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.
+ */
+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 },
+    );
+}

package/specialists/lib/zitadel.ts

@@ -0,0 +1,79 @@
+import { createSign } from "node:crypto";
+import { ServiceError } from "./errors.ts";
+
+export interface ServiceAccountKey {
+    keyId: string;
+    key: string;
+    userId: string;
+}
+
+export function parseServiceAccountKey(text: string): ServiceAccountKey {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(text);
+    } catch {
+        throw new ServiceError("ZITADEL_KEY_JSON is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null) throw new ServiceError("ZITADEL_KEY_JSON is not an object");
+    const r = parsed as Record<string, unknown>;
+    if (r.type !== "serviceaccount") throw new ServiceError("ZITADEL_KEY_JSON: type must be serviceaccount");
+    for (const field of ["keyId", "key", "userId"]) {
+        if (typeof r[field] !== "string" || (r[field] as string).length === 0) {
+            throw new ServiceError(`ZITADEL_KEY_JSON: missing ${field}`);
+        }
+    }
+    return { keyId: r.keyId as string, key: r.key as string, userId: r.userId as string };
+}
+
+function b64url(input: Buffer | string): string {
+    return Buffer.from(input).toString("base64url");
+}
+
+/** JWT profile assertion per Zitadel docs: RS256, kid header, iss = sub = userId, aud = issuer domain. */
+export function buildAssertion(key: ServiceAccountKey, domain: string, nowSeconds: number, ttlSeconds = 300): string {
+    const header = b64url(JSON.stringify({ alg: "RS256", kid: key.keyId }));
+    const payload = b64url(
+        JSON.stringify({
+            iss: key.userId,
+            sub: key.userId,
+            aud: `https://${domain}`,
+            iat: nowSeconds,
+            exp: nowSeconds + ttlSeconds,
+        }),
+    );
+    const signer = createSign("RSA-SHA256");
+    signer.update(`${header}.${payload}`);
+    const signature = signer.sign(key.key).toString("base64url");
+    return `${header}.${payload}.${signature}`;
+}
+
+export interface TokenRequest {
+    key: ServiceAccountKey;
+    domain: string;
+    /** Project ID added to the token audience through the reserved scope. */
+    audienceProjectId: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+
+export async function mintAccessToken(request: TokenRequest): Promise<string> {
+    const nowSeconds = Math.floor((request.now ?? Date.now)() / 1000);
+    const assertion = buildAssertion(request.key, request.domain, nowSeconds);
+    const body = new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion,
+        scope: `openid urn:zitadel:iam:org:project:id:${request.audienceProjectId}:aud`,
+    });
+    const doFetch = request.fetchImpl ?? fetch;
+    const response = await doFetch(`https://${request.domain}/oauth/v2/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    if (!response.ok) {
+        throw new ServiceError(`Zitadel token endpoint answered ${response.status}`);
+    }
+    const json = (await response.json()) as { access_token?: unknown };
+    if (typeof json.access_token !== "string") throw new ServiceError("Zitadel token response has no access_token");
+    return json.access_token;
+}

package/specialists/network/run.ts

@@ -0,0 +1,222 @@
+import { request as httpsRequest } from "node:https";
+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 } from "../lib/paths.ts";
+import { readSecret, secretPath } from "../lib/secrets.ts";
+import { sshFixed } from "../lib/ssh.ts";
+
+const SERVICE = "network";
+
+interface NetworkConfig extends Record<string, string> {
+    /** e.g. https://10.0.10.1/proxy/network/integration */
+    unifiBaseUrl: string;
+    /** SHA-256 fingerprint of the console certificate, colon-separated uppercase hex. */
+    unifiCertSha256: string;
+    pulsarHost: string;
+    pulsarUser: string;
+}
+
+const SHAPE = { unifiBaseUrl: "string", unifiCertSha256: "string", pulsarHost: "string", pulsarUser: "string" } as const;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** UniFi Network API (local console, /v1) read operations. */
+export const UNIFI_READS: Readonly<Record<string, { params: number; path: (p: string[]) => string; help: string }>> = {
+    sites: { params: 0, path: () => "/v1/sites", help: "sites" },
+    devices: { params: 1, path: ([s]) => `/v1/sites/${s}/devices`, help: "devices <siteId>" },
+    device: { params: 2, path: ([s, d]) => `/v1/sites/${s}/devices/${d}`, help: "device <siteId> <deviceId>" },
+    clients: { params: 1, path: ([s]) => `/v1/sites/${s}/clients`, help: "clients <siteId>" },
+    networks: { params: 1, path: ([s]) => `/v1/sites/${s}/networks`, help: "networks <siteId>" },
+    "firewall-policies": { params: 1, path: ([s]) => `/v1/sites/${s}/firewall/policies`, help: "firewall-policies <siteId>" },
+    wans: { params: 1, path: ([s]) => `/v1/sites/${s}/wans`, help: "wans <siteId>" },
+};
+
+/** Fixed remote commands on Pulsar; the forced command there accepts exactly these names. */
+export const PULSAR_COMMANDS: Readonly<Record<string, { args: number; help: string }>> = {
+    "guest-status": { args: 1, help: "guest-status <105|107|108>" },
+    "radius-check": { args: 0, help: "freeradius -XC inside LXC 108" },
+    "radius-status": { args: 0, help: "systemctl status freeradius inside LXC 108" },
+    "radius-journal": { args: 1, help: "radius-journal <since>" },
+    "radius-crl-timer": { args: 0, help: "radius-crl-monitor.timer schedule inside LXC 108" },
+    "tailscale-status": { args: 0, help: "tailscale status inside LXC 105" },
+    "tailscale-journal": { args: 1, help: "tailscale-journal <since>" },
+};
+
+const GUESTS = ["105", "107", "108"];
+const SINCE = /^[A-Za-z0-9 :\-+]{1,40}$/;
+
+const HELP = `network specialist
+
+  unifi <read> [--limit n] [--offset n] [--filter expr]
+${Object.values(UNIFI_READS)
+    .map((r) => `      ${r.help}`)
+    .join("\n")}
+  unifi get <path>            any GET under /v1 (path must start with /v1/)
+  unifi fingerprint           print the console certificate fingerprint (for the initial pin)
+  pulsar <command> [args]     fixed operations through a forced-command SSH key
+${Object.entries(PULSAR_COMMANDS)
+    .map(([name, c]) => `      ${name.padEnd(18)} ${c.help}`)
+    .join("\n")}`;
+
+export interface Query {
+    limit?: number;
+    offset?: number;
+    filter?: string;
+}
+
+export function parseQuery(args: string[]): { positional: string[]; query: Query } {
+    const positional: string[] = [];
+    const query: Query = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--limit" || a === "--offset") {
+            const n = Number(args[i + 1]);
+            if (!Number.isInteger(n) || n < 0) throw new UsageError(`${a} needs a non-negative integer`);
+            query[a === "--limit" ? "limit" : "offset"] = n;
+            i++;
+        } else if (a === "--filter") {
+            if (args[i + 1] === undefined) throw new UsageError("--filter needs an expression");
+            query.filter = args[i + 1];
+            i++;
+        } else if (a.startsWith("-")) {
+            throw new UsageError(`unknown option ${a}`);
+        } else {
+            positional.push(a);
+        }
+    }
+    return { positional, query };
+}
+
+export function unifiPath(args: string[]): string {
+    const { positional, query } = parseQuery(args);
+    const [read, ...params] = positional;
+    let path: string;
+    if (read === "get") {
+        if (params.length !== 1 || !params[0].startsWith("/v1/") || params[0].includes("..") || /\s/.test(params[0])) {
+            throw new UsageError("unifi get <path>: path must start with /v1/");
+        }
+        path = params[0];
+    } else {
+        const spec = read === undefined ? undefined : UNIFI_READS[read];
+        if (!spec) throw new UsageError(`unknown unifi read: ${read ?? "(none)"}`);
+        if (params.length !== spec.params) throw new UsageError(`unifi ${read} takes ${spec.params} id(s)`);
+        for (const p of params) if (!UUID.test(p)) throw new UsageError(`not a UUID: ${p}`);
+        path = spec.path(params);
+    }
+    const search = new URLSearchParams();
+    if (query.limit !== undefined) search.set("limit", String(query.limit));
+    if (query.offset !== undefined) search.set("offset", String(query.offset));
+    if (query.filter !== undefined) search.set("filter", query.filter);
+    const qs = search.toString();
+    return qs.length > 0 ? `${path}?${qs}` : path;
+}
+
+interface PinnedResponse {
+    status: number;
+    body: string;
+    fingerprint: string;
+}
+
+/** GET over TLS pinned to the console certificate; the console is self-signed. */
+export function pinnedGet(url: URL, apiKey: string | null, expectedFingerprint: string | null): Promise<PinnedResponse> {
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest(
+            url,
+            {
+                method: "GET",
+                rejectUnauthorized: false,
+                headers: { Accept: "application/json", ...(apiKey ? { "X-API-KEY": apiKey } : {}) },
+                timeout: 30_000,
+            },
+            (res) => {
+                const socket = res.socket as { getPeerCertificate?: () => { fingerprint256?: string } };
+                const fingerprint = socket.getPeerCertificate?.().fingerprint256 ?? "";
+                if (expectedFingerprint !== null && fingerprint.toUpperCase() !== expectedFingerprint.toUpperCase()) {
+                    res.destroy();
+                    reject(new ServiceError(`console certificate fingerprint ${fingerprint} does not match the pinned value`));
+                    return;
+                }
+                let body = "";
+                res.setEncoding("utf-8");
+                res.on("data", (chunk: string) => {
+                    body += chunk;
+                });
+                res.on("end", () => resolve({ status: res.statusCode ?? 0, body, fingerprint }));
+            },
+        );
+        req.on("timeout", () => req.destroy(new ServiceError("UniFi request timed out")));
+        req.on("error", (err) => reject(err instanceof ServiceError ? err : new ServiceError(`UniFi request failed: ${err.message}`)));
+        req.end();
+    });
+}
+
+async function unifi(config: NetworkConfig, args: string[]): Promise<number> {
+    const base = new URL(config.unifiBaseUrl);
+    if (args[0] === "fingerprint") {
+        const probe = await pinnedGet(new URL("/", base), null, null);
+        printJson({ host: base.host, fingerprint256: probe.fingerprint });
+        return 0;
+    }
+    const url = new URL(`${base.pathname.replace(/\/$/, "")}${unifiPath(args)}`, base);
+    const apiKey = readSecret(SERVICE, "UNIFI_API_KEY");
+    const response = await pinnedGet(url, apiKey, config.unifiCertSha256);
+    let parsed: unknown = response.body;
+    try {
+        parsed = JSON.parse(response.body);
+    } catch {
+        /* non-JSON body stays text */
+    }
+    printJson(parsed);
+    if (response.status < 200 || response.status >= 300) throw new ServiceError(`UniFi answered ${response.status}`);
+    return 0;
+}
+
+export function buildPulsarRemote(args: string[]): string {
+    const [name, ...rest] = args;
+    const spec = name === undefined ? undefined : PULSAR_COMMANDS[name];
+    if (!spec) throw new UsageError(`unknown pulsar command: ${name ?? "(none)"}`);
+    if (rest.length !== spec.args) throw new UsageError(`pulsar ${name} takes ${spec.args} argument(s)`);
+    if (name === "guest-status" && !GUESTS.includes(rest[0])) throw new UsageError(`guest must be one of ${GUESTS.join(", ")}`);
+    if (name.endsWith("-journal") && !SINCE.test(rest[0])) throw new UsageError("since: letters, digits, spaces, colon, plus, minus only");
+    return [name, ...rest].join(" ");
+}
+
+async function pulsar(config: NetworkConfig, args: string[]): Promise<number> {
+    const remote = buildPulsarRemote(args);
+    const result = await sshFixed(
+        {
+            host: config.pulsarHost,
+            user: config.pulsarUser,
+            keyFile: secretPath(SERVICE, "SSH_KEY_PULSAR"),
+            knownHostsFile: join(specialistsHome(), "config", "known_hosts"),
+        },
+        remote,
+        120_000,
+    );
+    if (result.stdout.length > 0) printRaw(result.stdout);
+    if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `pulsar ${args[0]} exited ${result.code}`);
+    return 0;
+}
+
+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<NetworkConfig>(SERVICE, SHAPE);
+    switch (args[0]) {
+        case "unifi":
+            return unifi(config, args.slice(1));
+        case "pulsar":
+            return pulsar(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/provision/provision.sh

@@ -0,0 +1,96 @@
+#!/bin/sh
+# specialist-provision: copy every Secure Note of the Vaultwarden collection
+# `specialists` into ~/.specialists/secrets/<note>/<FIELD> (mode 0600).
+# Fields ending in _B64 are base64-decoded and written without the suffix.
+# Runs as the `specialist` user. Idempotent; stale fields are removed.
+set -eu
+umask 077
+
+home="${HOME:?}"
+config_dir="$home/.config/specialists"
+client_file="$config_dir/client.env"
+password_file="$config_dir/master-password"
+root="$home/.specialists"
+collection_name="${SPECIALISTS_COLLECTION:-specialists}"
+BW=/opt/homebrew/bin/bw
+JQ=/opt/homebrew/bin/jq
+
+for f in "$client_file" "$password_file"; do
+  [ -f "$f" ] || { echo "missing $f" >&2; exit 2; }
+done
+
+read_value() {
+  awk -v key="$1" 'index($0, key "=") == 1 { sub("^[^=]*=", ""); print; found = 1; exit } END { if (!found) exit 1 }' "$client_file"
+}
+
+export BITWARDENCLI_APPDATA_DIR="$config_dir/bw-data"
+export BW_CLIENTID="$(read_value BW_CLIENTID)"
+export BW_CLIENTSECRET="$(read_value BW_CLIENTSECRET)"
+bw_server="$(read_value BW_SERVER)"
+
+cleanup() {
+  "$BW" lock >/dev/null 2>&1 || true
+  unset BW_CLIENTID BW_CLIENTSECRET BW_SESSION
+}
+trap cleanup EXIT HUP INT TERM
+
+status_json="$("$BW" status)"
+status="$(printf '%s' "$status_json" | "$JQ" -r '.status')"
+current_server="$(printf '%s' "$status_json" | "$JQ" -r '.serverUrl // ""')"
+if [ "$current_server" != "$bw_server" ]; then
+  [ "$status" = "unauthenticated" ] || "$BW" logout >/dev/null
+  "$BW" config server "$bw_server" >/dev/null
+  status="unauthenticated"
+fi
+case "$status" in
+  unauthenticated) "$BW" login --apikey >/dev/null ;;
+  unlocked) "$BW" lock >/dev/null ;;
+  locked) ;;
+  *) echo "unexpected bw status: $status" >&2; exit 1 ;;
+esac
+
+BW_SESSION="$("$BW" unlock --passwordfile "$password_file" --raw)"
+export BW_SESSION
+"$BW" sync >/dev/null
+
+collection_id="$("$BW" list collections | "$JQ" -er --arg n "$collection_name" '[.[] | select(.name == $n) | .id] | if length == 1 then .[0] else error("collection not found or ambiguous") end')"
+
+mkdir -p "$root/bin" "$root/config" "$root/secrets" "$root/work"
+[ -f "$root/audit.log" ] || : > "$root/audit.log"
+
+# One line per field: note<TAB>field<TAB>base64(value). Secure Notes only (type 2).
+"$BW" list items --collectionid "$collection_id" |
+  "$JQ" -r '.[] | select(.type == 2) | .name as $n | (.fields // [])[] | select(.value != null and .value != "") | [$n, .name, (.value | @base64)] | @tsv' |
+  while IFS="$(printf '\t')" read -r note field value_b64; do
+    case "$note" in ""|*[!a-z0-9-]*) echo "skip note with unsupported name: $note" >&2; continue ;; esac
+    case "$field" in ""|*[!A-Z0-9_]*) echo "skip field with unsupported name: $note/$field" >&2; continue ;; esac
+    dir="$root/secrets/$note"
+    mkdir -p "$dir"
+    target="$field"
+    case "$field" in *_B64) target="${field%_B64}" ;; esac
+    tmp="$dir/.$target.tmp"
+    if [ "$target" != "$field" ]; then
+      printf '%s' "$value_b64" | base64 -d | base64 -d > "$tmp"
+    else
+      printf '%s' "$value_b64" | base64 -d > "$tmp"
+    fi
+    chmod 600 "$tmp"
+    mv -f "$tmp" "$dir/$target"
+    printf '%s\t%s\n' "$note" "$target" >> "$root/.provisioned.$$"
+  done
+
+# Remove files no longer present in Vaultwarden.
+if [ -f "$root/.provisioned.$$" ]; then
+  for dir in "$root"/secrets/*/; do
+    [ -d "$dir" ] || continue
+    note="$(basename "$dir")"
+    for file in "$dir"*; do
+      [ -f "$file" ] || continue
+      name="$(basename "$file")"
+      grep -qx "$(printf '%s\t%s' "$note" "$name")" "$root/.provisioned.$$" || { rm -f "$file"; echo "removed stale $note/$name" >&2; }
+    done
+  done
+  awk -F '\t' '{ print $1 "/" $2 }' "$root/.provisioned.$$" | sort
+  rm -f "$root/.provisioned.$$"
+fi
+unset BW_CLIENTID BW_CLIENTSECRET BW_SESSION

package/specialists/wrappers.test.ts

@@ -0,0 +1,119 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { refusedPrefix, safeRepoPath, command as arcaneCommand } from "./arcane/run.ts";
+import { API_PREFIXES, buildDmzRemote, validateApiPath, command as identityCommand } from "./identity/run.ts";
+import { UsageError } from "./lib/errors.ts";
+import { buildPulsarRemote, parseQuery, unifiPath, command as networkCommand } from "./network/run.ts";
+
+describe("arcane wrapper", () => {
+    it("refuses only the wrapper's own setup paths", () => {
+        expect(refusedPrefix(["projects", "create", "x"])).toBeNull();
+        expect(refusedPrefix(["projects", "update", "arcane", "--flag"])).toBeNull();
+        expect(refusedPrefix(["--env", "0", "auth", "login"])).toBe("auth");
+        expect(refusedPrefix(["self-update"])).toBe("self-update");
+        expect(refusedPrefix(["config", "set", "api-key", "x"])).toBe("config");
+        expect(refusedPrefix(["projects", "list"])).toBeNull();
+        expect(refusedPrefix(["projects", "up", "my-app"])).toBeNull();
+        expect(refusedPrefix(["containers", "logs", "c1"])).toBeNull();
+    });
+
+    it("keeps gitops writes inside the checkout", () => {
+        const dir = "/repo";
+        expect(safeRepoPath(dir, "mealie/compose.yaml")).toBe("/repo/mealie/compose.yaml");
+        for (const bad of ["", "/etc/passwd", "../x", "a/../../b", ".git/config", "a\0b"]) {
+            expect(() => safeRepoPath(dir, bad), bad).toThrow(UsageError);
+        }
+    });
+
+    it("prints help without touching config", async () => {
+        const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        expect(await arcaneCommand(["--help"])).toBe(0);
+        expect(String(write.mock.calls[0][0])).toContain("gitops write");
+        expect(String(write.mock.calls[0][0])).toContain("gitops show");
+        write.mockRestore();
+    });
+});
+
+describe("identity wrapper", () => {
+    it("limits Zitadel paths to the API families", () => {
+        for (const p of API_PREFIXES) expect(validateApiPath(`${p}users`)).toBe(`${p}users`);
+        expect(() => validateApiPath("/oauth/v2/token")).toThrow(UsageError);
+        expect(() => validateApiPath("/v2/../admin")).toThrow(UsageError);
+    });
+
+    it("maps dmz commands to fixed remote strings and validates arguments", () => {
+        expect(buildDmzRemote(["status"])).toBe("status");
+        expect(buildDmzRemote(["journal", "pomerium", "1 hour ago"])).toBe("journal pomerium 1 hour ago");
+        expect(() => buildDmzRemote(["journal", "sshd", "1 hour ago"])).toThrow(/unit/);
+        expect(() => buildDmzRemote(["journal", "pomerium", "x; rm -rf /"])).toThrow(/since/);
+        expect(() => buildDmzRemote(["render", "extra"])).toThrow(/0 argument/);
+        expect(() => buildDmzRemote(["reboot"])).toThrow(/unknown dmz command/);
+    });
+
+    it("prints help without touching config", async () => {
+        const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        expect(await identityCommand([])).toBe(0);
+        expect(String(write.mock.calls[0][0])).toContain("zitadel <GET|POST|PUT|PATCH|DELETE>");
+        write.mockRestore();
+    });
+});
+
+describe("network wrapper", () => {
+    const site = "12341234-5656-7878-9090-123456789012";
+
+    it("parses list options", () => {
+        expect(parseQuery(["devices", site, "--limit", "5", "--filter", "state.eq('ONLINE')"])).toEqual({
+            positional: ["devices", site],
+            query: { limit: 5, filter: "state.eq('ONLINE')" },
+        });
+        expect(() => parseQuery(["--limit", "-1"])).toThrow(UsageError);
+        expect(() => parseQuery(["--bogus"])).toThrow(UsageError);
+    });
+
+    it("builds UniFi paths and validates ids", () => {
+        expect(unifiPath(["sites"])).toBe("/v1/sites");
+        expect(unifiPath(["devices", site, "--offset", "25"])).toBe(`/v1/sites/${site}/devices?offset=25`);
+        expect(unifiPath(["firewall-policies", site])).toBe(`/v1/sites/${site}/firewall/policies`);
+        expect(unifiPath(["get", "/v1/countries"])).toBe("/v1/countries");
+        expect(() => unifiPath(["devices", "not-a-uuid"])).toThrow(/UUID/);
+        expect(() => unifiPath(["get", "/proxy/network/api/s/default"])).toThrow(/\/v1\//);
+        expect(() => unifiPath(["reboot"])).toThrow(/unknown unifi read/);
+    });
+
+    it("maps pulsar commands to fixed remote strings", () => {
+        expect(buildPulsarRemote(["guest-status", "108"])).toBe("guest-status 108");
+        expect(buildPulsarRemote(["radius-journal", "2 hours ago"])).toBe("radius-journal 2 hours ago");
+        expect(() => buildPulsarRemote(["guest-status", "100"])).toThrow(/guest/);
+        expect(() => buildPulsarRemote(["radius-check", "x"])).toThrow(/0 argument/);
+        expect(() => buildPulsarRemote(["shell"])).toThrow(/unknown pulsar command/);
+    });
+
+    it("prints help without touching config", async () => {
+        const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        expect(await networkCommand(["help"])).toBe(0);
+        expect(String(write.mock.calls[0][0])).toContain("unifi fingerprint");
+        write.mockRestore();
+    });
+});
+
+describe("wrapper config errors", () => {
+    let home: string;
+    const originalHome = process.env.HOME;
+
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "spec-home-"));
+        process.env.HOME = home;
+    });
+
+    afterEach(() => {
+        process.env.HOME = originalHome;
+        rmSync(home, { recursive: true, force: true });
+    });
+
+    it("fails clearly when the config file is absent", async () => {
+        await expect(arcaneCommand(["projects", "list"])).rejects.toThrow(/cannot read .*arcane\.json/);
+        await expect(networkCommand(["unifi", "sites"])).rejects.toThrow(/network\.json/);
+    });
+});