@astrofoundry/pi-astro 0.18.5 → 0.19.0

package/specialists/README.md

@@ -7,6 +7,9 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
 | `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
 | `astro.identity` | Zitadel; Pomerium, nginx, lego on VM 104 | Any Zitadel API call (v2, management, admin, auth) with responses redacted; `dmz status|journal|config-template|render|pomerium-restart|nginx-reload|lego-renew` |
 | `astro.network` | UniFi, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read UniFi sites, devices, clients, networks, firewall policies, WANs; RADIUS and Tailscale checks on Pulsar |
+| `astro.dns` | Technitium primary (Synapse) and secondary (LXC 107); Cloudflare zones `37pla.net`, `monadeo.com` | Read zones and records on both resolvers, resolve, stats; create and delete zones, add, update, delete records on the primary; Cloudflare zones and record add, update, delete |
+| `astro.edge` | Frontdoor VPS (`frontdoor-1337`) over an IAP tunnel; `00-frontdoor-vps/` in the homelab repository | `probe` the public path; `vps status|nginx-conf|nginx-test|journal|wg|bouncer|updates|deploy-nginx|reboot --confirm`; `git` on the homelab checkout, writes limited to `00-frontdoor-vps/` |
+| `astro.security` | Wazuh, CrowdSec, rsyslog archive on VM 106 | Read-only: `status`, `attention`, `agents`, `alerts`, `decisions`, `bouncers`, `metrics`, `wazuh-alerts`, `wazuh-log`, `remote-hosts`, `remote-log`, `journal` |
 
 Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both from the bundled `astro-subagents` extension). Specialists may call each other once (`maxSubagentDepth: 1`). They run on `openai-codex/gpt-6-astra` with `xhigh` thinking, set by `model` and `thinking` in each `agents/<name>.md`; an agent without these fields inherits the caller's model and thinking. Each tool takes `args`, an array of strings; `["--help"]` lists the subcommands.
 
@@ -14,19 +17,25 @@ Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both
 
 - Credentials and CLIs belong to a dedicated macOS user `specialist` on the host. Agents run as the main user and reach the wrappers only through `sudo -n -u specialist -H /usr/local/bin/specialist-cli`, the single passwordless sudo rule. General sudo asks for a password.
 - Credentials come from Vaultwarden (`homelab` / `specialists`, one Secure Note per specialist) through `specialist-cli provision`, into `0600` files. Wrappers never call `bw`.
-- Arcane is reached with a Zitadel service user: a fresh token per call, exchanged for a 300 s Arcane token. Other services use API keys, a PAT, or SSH keys that the targets pin to forced commands.
+- Arcane is reached with a Zitadel service user: a fresh token per call, exchanged for a 300 s Arcane token. Other services use API keys, a PAT, tokens, or SSH keys that the targets pin to forced commands. The VPS is reached through `gcloud compute start-iap-tunnel` with a service account that may only open IAP tunnels and read instances; its gcloud state lives in `/Users/specialist/.specialists/work/gcloud`.
 - Every call is logged in `/Users/specialist/.specialists/audit.log`.
 - The `specialist-gate` extension registers the tool only inside the matching specialist child and blocks other agents from calling the CLIs or reading `/Users/specialist`. `security-guard` carries the same blocks.
 
-Limits: `network` is read-only on UniFi. `identity` cannot deploy Pomerium route changes; those are edits to `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository, deployed with its `deploy.sh`.
+Limits: `network` is read-only on UniFi. `security` is read-only. `identity` cannot deploy Pomerium route changes; those are edits to `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository, deployed with its `deploy.sh`. `edge` changes only `nginx.conf` on the VPS; `dns` writes only to the Technitium primary.
 
 ## Enable specialists on a host
 
-Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, git). Steps 1 to 3 are one-time on the services; 4 to 8 are per host.
+Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14`, git). Steps 1 to 3 are one-time on the services; 4 to 8 are per host.
 
-1. **Vaultwarden.** Account `specialists@monadeo.com` with **Can view** on collection `specialists` in organization `homelab`. Secure Notes with Hidden fields: `arcane`: `ZITADEL_KEY_JSON`, `GITOPS_DEPLOY_KEY_B64`, `ZITADEL_USER_ID` (plain); `identity`: `ZITADEL_PAT`, `SSH_KEY_DMZ_B64`; `network`: `UNIFI_API_KEY`, `SSH_KEY_PULSAR_B64`. `_B64` fields hold `base64 -i <keyfile> | tr -d '\n'`.
-2. **Zitadel** (`https://auth.37pla.net/ui/console`). Service user `spc-arcane` with Access Token Type JWT and a JSON key (Keys, New). Service user `spc-identity` with a Personal Access Token and the Instance Owner role (Default settings, Managers).
-3. **Arcane** (Settings, Authentication, Federated Credentials). Issuer `https://auth.37pla.net`, Audience `387825541182390275`, Subject exact = `spc-arcane` user ID, Role Admin, Global, lifetime 300. **UniFi**: API key (Settings, API Keys) and two policies allowing Cortex `10.0.40.37` to TCP 22 on `10.0.20.10` and `10.0.10.37`. **GitHub**: the `spc-arcane-gitops` public key as a write deploy key on `astronaute77/arcane`.
+1. **Vaultwarden.** Account `specialists@monadeo.com` with **Can view** on collection `specialists` in organization `homelab`. Secure Notes with Hidden fields (`_B64` fields hold `base64 -i <keyfile> | tr -d '\n'`):
+   - `arcane`: `ZITADEL_KEY_JSON`, `GITOPS_DEPLOY_KEY_B64`, `ZITADEL_USER_ID` (plain).
+   - `identity`: `ZITADEL_PAT`, `SSH_KEY_DMZ_B64`.
+   - `network`: `UNIFI_API_KEY`, `SSH_KEY_PULSAR_B64`.
+   - `dns`: `TECHNITIUM_TOKEN`, `TECHNITIUM2_TOKEN` (Technitium API tokens of the primary and the secondary), `CLOUDFLARE_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`.
+   - `edge`: `GCP_SA_KEY_JSON` (service account key), `SSH_KEY_FRONTDOOR_B64`, `HOMELAB_DEPLOY_KEY_B64`.
+   - `security`: `SSH_KEY_OBS_B64`.
+2. **Identities.** Zitadel (`https://auth.37pla.net/ui/console`): service user `spc-arcane` with Access Token Type JWT and a JSON key; service user `spc-identity` with a Personal Access Token and the Instance Owner role. Technitium (both resolvers): a user with Zones View/Modify/Delete, Dashboard View, DNS Client View, and an API token each. Cloudflare: an account-owned API token with `Zone:Read` and `DNS:Edit` on both zones. GCP project `frontdoor-1337`: service account `spc-edge` with `roles/iap.tunnelResourceAccessor` and `roles/compute.viewer`, JSON key.
+3. **Services.** Arcane (Settings, Authentication, Federated Credentials): Issuer `https://auth.37pla.net`, Audience `387825541182390275`, Subject exact = `spc-arcane` user ID, Role Admin, Global, lifetime 300. UniFi: API key (Settings, API Keys) and policies allowing Cortex `10.0.40.37` to TCP 22 on `10.0.20.10`, `10.0.10.37`, `10.0.90.10` and TCP 5380 on `10.0.40.53`, `10.0.40.54`. GitHub: `spc-arcane-gitops` as a write deploy key on `astronaute77/arcane`, `spc-edge-homelab` as a write deploy key on `astronaute77/homelab`.
 4. **Sudo and user**, as an administrator:
    ```sh
    printf 'cortex ALL=(ALL) ALL\n' | sudo tee /etc/sudoers.d/cortex >/dev/null
@@ -35,33 +44,47 @@ Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, git). Steps 1 to 3 are one-tim
    sudo sysadminctl -addUser specialist -fullName "Specialists" -home /Users/specialist -shell /bin/zsh -password -
    sudo dscl . create /Users/specialist IsHidden 1 && sudo createhomedir -c -u specialist && sudo chmod 700 /Users/specialist
    sudo install -m 0755 -o root -g wheel <package>/specialists/entry/specialist-cli.sh /usr/local/bin/specialist-cli
+   brew install --cask gcloud-cli
    ```
    Add `cortex ALL=(specialist) NOPASSWD: ALL` as `/etc/sudoers.d/specialists-setup` (mode `0440`) for the duration of steps 5 to 7, then delete it.
 5. **Bootstrap**, as `specialist` (`sudo -u specialist -H zsh`, `umask 077`): `~/.config/specialists/client.env` with `BW_SERVER=https://vault.37pla.net`, `BW_CLIENTID`, `BW_CLIENTSECRET`; `~/.config/specialists/master-password`. Both `0600`.
-6. **Install and configure**, as `specialist`: `sh <package>/specialists/install/install.sh <package> 2.11.1` (`<package>` is the installed pi-astro directory, `~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro`). Write `~/.specialists/config/arcane.json`, `identity.json`, `network.json`:
+6. **Install and configure**, as `specialist`: `sh <package>/specialists/install/install.sh <package> 2.12.0` (`<package>` is the installed pi-astro directory, `~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro`). Write `~/.specialists/config/<name>.json` for every specialist:
    ```json
    { "serverUrl": "http://10.0.40.30:3552", "zitadelDomain": "auth.37pla.net", "audience": "387825541182390275",
      "arcaneCli": "/Users/specialist/.specialists/bin/arcane-cli", "arcaneCliConfig": "/Users/specialist/.specialists/config/arcanecli.yml",
      "gitopsRemote": "git@github.com:astronaute77/arcane.git", "gitopsBranch": "main" }
    { "zitadelDomain": "auth.37pla.net", "dmzHost": "10.0.20.10", "dmzUser": "dmz" }
    { "unifiBaseUrl": "https://10.0.10.1/proxy/network/integration", "unifiCertSha256": "<from: specialist-cli network -- unifi fingerprint>", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
+   { "technitiumPrimaryUrl": "http://10.0.40.53:5380", "technitiumSecondaryUrl": "http://10.0.40.54:5380", "technitiumCatalog": "catalog.invalid" }
+   { "gcloud": "/opt/homebrew/bin/gcloud", "gcloudPython": "/opt/homebrew/opt/python@3.14/bin/python3.14",
+     "project": "frontdoor-1337", "zone": "us-east1-c", "instance": "frontdoor-1337", "serviceAccount": "spc-edge@frontdoor-1337.iam.gserviceaccount.com",
+     "iapLocalPort": 22337, "sshUser": "spc-edge", "publicIp": "35.237.66.101", "probeHost": "auth.37pla.net",
+     "homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "00-frontdoor-vps", "nginxConf": "00-frontdoor-vps/nginx.conf" }
+   { "obsHost": "10.0.90.10", "obsUser": "observability" }
    ```
    Then `sudo -n -u specialist -H /usr/local/bin/specialist-cli provision`; it lists every note and field.
-7. **SSH targets.** Install `entry/remote/spc-identity-dmz-entry.sh` as `/usr/local/sbin/spc-identity-dmz-entry` on VM 104 and `entry/remote/spc-network-pulsar-entry.sh` as `/usr/local/sbin/spc-network-pulsar-entry` on Pulsar (`0755`, root). Add each public key to the target's `authorized_keys` (`dmz` on VM 104, root on Pulsar) as:
-   `command="/usr/local/sbin/<entry>",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 ...`
+7. **SSH targets.** Each target gets an entry script from `entry/remote/` as `/usr/local/sbin/<entry>` (`0755`, root) and the public key in the right `authorized_keys` as
+   `command="/usr/local/sbin/<entry>",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 ...`:
+   - VM 104, user `dmz`: `spc-identity-dmz-entry.sh`.
+   - Pulsar, root: `spc-network-pulsar-entry.sh`.
+   - VM 106, user `observability`: `spc-security-obs-entry.sh` (tracked in the homelab repository, installed by `02-pulsar-proxmox/observability/deploy.sh`).
+   - Frontdoor VPS: `spc-edge-frontdoor-install.sh` creates user `spc-edge` (group `systemd-journal`), installs `spc-edge-frontdoor-entry.sh` and the sudoers file `spc-edge-frontdoor-sudoers`, and writes `authorized_keys`. Copy the three files and the public key to `/tmp` with `gcloud compute scp --tunnel-through-iap`, then run it as root.
 8. **Pi**, as the main user: `~/.pi/agent/specialists.json` (below) and the specialist blocks in `~/.pi/agent/security-guard.json` (`specialist-cli`, `arcane-cli`, `-u specialist` in `operations`; `/Users/specialist/**` in `reads` and `writes`; keep the default rules next to them).
    ```json
    { "entry": "/usr/local/bin/specialist-cli", "user": "specialist",
      "specialists": [
        { "agent": "astro.arcane", "tool": "arcane", "service": "arcane", "timeoutMs": 300000 },
        { "agent": "astro.identity", "tool": "identity", "service": "identity", "timeoutMs": 120000 },
-       { "agent": "astro.network", "tool": "network", "service": "network", "timeoutMs": 120000 } ] }
+       { "agent": "astro.network", "tool": "network", "service": "network", "timeoutMs": 120000 },
+       { "agent": "astro.dns", "tool": "dns", "service": "dns", "timeoutMs": 60000 },
+       { "agent": "astro.edge", "tool": "edge", "service": "edge", "timeoutMs": 300000 },
+       { "agent": "astro.security", "tool": "security", "service": "security", "timeoutMs": 120000 } ] }
    ```
 
-Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller test -- projects list` prints JSON; the same for `identity -- dmz status` and `network -- unifi sites`; `/run astro.arcane -- list projects` works in Pi; `bash` with `arcane-cli --help` is blocked in a normal session.
+Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller test -- projects list` prints JSON; the same for `identity -- dmz status`, `network -- unifi sites`, `dns -- technitium primary zones`, `edge -- vps status`, `security -- attention`; `/run astro.arcane -- list projects` works in Pi; `bash` with `arcane-cli --help` is blocked in a normal session.
 
 ## Rotation and operations
 
-Rotation steps for every field live in the homelab repository, `03-cortex-macmini/ROTATION.md`. After any change in Vaultwarden run `specialist-cli provision`. Host state and the sudo rules are documented in `03-cortex-macmini/README.md`; the forced-command scripts are tracked under `02-pulsar-proxmox/dmz/system/` and `02-pulsar-proxmox/pulsar/system/`.
+Rotation steps for every field live in the homelab repository, `03-cortex-macmini/ROTATION.md`. After any change in Vaultwarden run `specialist-cli provision`. Host state and the sudo rules are documented in `03-cortex-macmini/README.md`; the forced-command scripts are tracked under `02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`, `02-pulsar-proxmox/observability/system/`, and `00-frontdoor-vps/system/`.
 
-Planned specialists (not built): `dns`, `edge`, `security` (batch 2); `backup`, `proxmox`, `inference` (batch 3). See `AGENTS.md` for how to add one.
+Planned specialists (not built): `backup`, `proxmox`, `inference` (batch 3). See `AGENTS.md` for how to add one.

package/specialists/arcane/run.ts

@@ -1,14 +1,14 @@
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, 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 { printRaw } from "../lib/output.ts";
 import { run } from "../lib/proc.ts";
+import { REPO_HELP, repoCommand, type RepoSpec } from "../lib/repo.ts";
 import { ARCANE_DENIED_KEYS, filterJsonText, stripKeys } from "../lib/sanitize.ts";
-import { readSecret, secretPath } from "../lib/secrets.ts";
+import { readSecret } from "../lib/secrets.ts";
 import { mintAccessToken, parseServiceAccountKey } from "../lib/zitadel.ts";
 
 const SERVICE = "arcane";
@@ -66,131 +66,22 @@ const HELP = `arcane specialist
 
   <arcane-cli args...>        run arcane-cli with a fresh federated token; JSON output, sensitive fields removed
                               (arcane-cli gitops ... manages the server-side syncs)
-  git status                  branch, ahead/behind, changed files of the GitOps 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
-
+${REPO_HELP}
 Refused: ${REFUSED_PREFIXES.join(", ")}. GitOps-managed projects (gitOpsManagedBy set) change in the repository, then sync.`;
 
 const TIMEOUT_MS = 240_000;
 
-function gitEnv(): Record<string, string> {
-    const key = secretPath(SERVICE, "GITOPS_DEPLOY_KEY");
-    const knownHosts = join(specialistsHome(), "config", "known_hosts");
+function repoSpec(config: ArcaneConfig): RepoSpec {
     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",
+        service: SERVICE,
+        checkoutName: "arcane-gitops",
+        remote: config.gitopsRemote,
+        branch: config.gitopsBranch,
+        deployKeyField: "GITOPS_DEPLOY_KEY",
+        help: HELP,
     };
 }
 
-async function git(dir: string, args: string[]): Promise<string> {
-    const result = await run("/usr/bin/git", ["-C", dir, ...args], { env: gitEnv(), timeoutMs: TIMEOUT_MS });
-    if (result.code !== 0) throw new ServiceError(`git ${args[0]} failed: ${result.stderr.trim()}`);
-    return result.stdout;
-}
-
-async function ensureCheckout(config: ArcaneConfig): Promise<string> {
-    const dir = workDir("arcane-gitops");
-    if (existsSync(join(dir, ".git"))) return dir;
-    mkdirSync(dirname(dir), { recursive: true, mode: 0o700 });
-    const result = await run(
-        "/usr/bin/git",
-        ["clone", "--branch", config.gitopsBranch, "--single-branch", config.gitopsRemote, dir],
-        { env: gitEnv(), 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;
-}
-
-async function repo(config: ArcaneConfig, args: string[]): Promise<number> {
-    const [sub, ...rest] = args;
-    const dir = await ensureCheckout(config);
-    switch (sub) {
-        case "status": {
-            await git(dir, ["fetch", "--quiet", "origin", config.gitopsBranch]);
-            const branch = (await git(dir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
-            const counts = (await git(dir, ["rev-list", "--left-right", "--count", `HEAD...origin/${config.gitopsBranch}`])).trim();
-            const [ahead, behind] = counts.split(/\s+/).map(Number);
-            const changed = (await git(dir, ["status", "--porcelain"])).split("\n").filter(Boolean);
-            printJson({ branch, ahead, behind, changed });
-            return 0;
-        }
-        case "pull":
-            printRaw(await git(dir, ["pull", "--ff-only", "origin", config.gitopsBranch]));
-            return 0;
-        case "diff":
-            printRaw((await git(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(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 = safeRepoPath(dir, rest[0]);
-            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(dir, ["add", "--all"]);
-            const staged = (await git(dir, ["diff", "--cached", "--name-only"])).split("\n").filter(Boolean);
-            if (staged.length === 0) throw new UsageError("nothing to commit");
-            await git(dir, ["commit", "--quiet", "-m", message]);
-            printJson({ committed: (await git(dir, ["rev-parse", "--short", "HEAD"])).trim(), files: staged });
-            return 0;
-        }
-        case "push": {
-            const result = await run("/usr/bin/git", ["-C", dir, "push", "origin", config.gitopsBranch], { env: gitEnv(), 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${HELP}`);
-    }
-}
-
 async function federatedToken(config: ArcaneConfig): Promise<string> {
     const key = parseServiceAccountKey(readSecret(SERVICE, "ZITADEL_KEY_JSON"));
     const zitadelToken = await mintAccessToken({ key, domain: config.zitadelDomain, audienceProjectId: config.audience });
@@ -256,7 +147,7 @@ export async function command(args: string[]): Promise<number> {
         return 0;
     }
     const config = readConfig<ArcaneConfig>(SERVICE, SHAPE);
-    if (args[0] === "git") return repo(config, args.slice(1));
+    if (args[0] === "git") return repoCommand(repoSpec(config), args.slice(1));
     return passthrough(config, args);
 }
 

package/specialists/dns/run.ts

@@ -0,0 +1,339 @@
+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 { redactSecrets } from "../lib/sanitize.ts";
+import { readSecret } from "../lib/secrets.ts";
+
+const SERVICE = "dns";
+
+interface DnsConfig extends Record<string, string> {
+    technitiumPrimaryUrl: string;
+    technitiumSecondaryUrl: string;
+    /** Catalog zone new primary zones join, so the secondary receives them. */
+    technitiumCatalog: string;
+}
+
+const SHAPE = { technitiumPrimaryUrl: "string", technitiumSecondaryUrl: "string", technitiumCatalog: "string" } as const;
+
+const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
+const TIMEOUT_MS = 30_000;
+
+export const NODES = ["primary", "secondary"] as const;
+export type Node = (typeof NODES)[number];
+
+const NAME = /^[A-Za-z0-9_.-]{1,253}$/;
+const RECORD_TYPE = /^[A-Z0-9]{1,10}$/;
+const PARAM_KEY = /^[a-zA-Z]{1,40}$/;
+const STATS_TYPES = ["LastHour", "LastDay", "LastWeek", "LastMonth", "LastYear"];
+const HEX_ID = /^[0-9a-f]{32}$/;
+
+/** Technitium HTTP API reads, valid on both nodes. */
+export const TECHNITIUM_READS: Readonly<Record<string, { args: [number, number]; help: string }>> = {
+    zones: { args: [0, 1], help: "zones [filter]                   list authoritative zones (filter: * and ? wildcards)" },
+    records: { args: [1, 2], help: "records <zone> [domain]          all records of a zone, or those of one name" },
+    "zone-options": { args: [1, 1], help: "zone-options <zone>              zone settings, including its catalog" },
+    resolve: { args: [1, 2], help: "resolve <domain> [type]          query this server (type default A)" },
+    stats: { args: [0, 1], help: `stats [${STATS_TYPES.join("|")}]  dashboard counters` },
+};
+
+/** Technitium writes; the primary only, the secondary receives zones through the catalog. */
+export const TECHNITIUM_WRITES: Readonly<Record<string, { args: [number, number]; help: string }>> = {
+    "zone-create": { args: [1, 1], help: "zone-create <zone>                     Primary zone, member of the configured catalog" },
+    "zone-delete": { args: [1, 1], help: "zone-delete <zone>                     delete a zone and every record in it" },
+    "record-add": { args: [3, 40], help: "record-add <zone> <domain> <type> <key=value>...     e.g. ipAddress=10.0.40.99 ttl=300" },
+    "record-update": { args: [3, 40], help: "record-update <zone> <domain> <type> <key=value>...  e.g. ipAddress=10.0.40.99 newIpAddress=10.0.40.98" },
+    "record-delete": { args: [3, 40], help: "record-delete <zone> <domain> <type> <key=value>...  e.g. ipAddress=10.0.40.99" },
+};
+
+const HELP = `dns specialist
+
+  technitium <primary|secondary> <read> [args]
+${Object.values(TECHNITIUM_READS)
+    .map((r) => `      ${r.help}`)
+    .join("\n")}
+  technitium primary <write> [args]              (the secondary follows through the catalog zone)
+${Object.values(TECHNITIUM_WRITES)
+    .map((w) => `      ${w.help}`)
+    .join("\n")}
+      key=value pairs are the documented parameters of /api/zones/records/{add,update,delete}
+  cloudflare verify                              check the API token
+  cloudflare zones                               zones the token can see
+  cloudflare records <zone> [--type T] [--name fqdn]
+  cloudflare record-add <zone> <json>            {"type":"A","name":"x.37pla.net","content":"35.237.66.101","ttl":300,"proxied":false}
+  cloudflare record-update <zone> <recordId> <json>
+  cloudflare record-delete <zone> <recordId>`;
+
+export interface TechnitiumRequest {
+    path: string;
+    params: Record<string, string>;
+    write: boolean;
+}
+
+export function assertName(value: string | undefined, what: string): string {
+    if (value === undefined || !NAME.test(value)) throw new UsageError(`${what} must be a DNS name`);
+    return value;
+}
+
+export function parseParams(pairs: string[]): Record<string, string> {
+    const params: Record<string, string> = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0) throw new UsageError(`expected key=value, got ${pair}`);
+        const key = pair.slice(0, eq);
+        if (!PARAM_KEY.test(key) || key === "token" || key === "node") throw new UsageError(`invalid parameter name: ${key}`);
+        params[key] = pair.slice(eq + 1);
+    }
+    return params;
+}
+
+/** Maps a technitium subcommand to a documented API path and its parameters. */
+export function technitiumRequest(catalog: string, args: string[]): TechnitiumRequest {
+    const [name, ...rest] = args;
+    const spec = name === undefined ? undefined : (TECHNITIUM_READS[name] ?? TECHNITIUM_WRITES[name]);
+    if (!spec) throw new UsageError(`unknown technitium command: ${name ?? "(none)"}`);
+    if (rest.length < spec.args[0] || rest.length > spec.args[1]) {
+        throw new UsageError(`technitium ${name} takes ${spec.args[0]}${spec.args[1] > spec.args[0] ? ` to ${spec.args[1]}` : ""} argument(s)`);
+    }
+    switch (name) {
+        case "zones":
+            return { path: "/api/zones/list", params: rest[0] === undefined ? {} : { filterName: rest[0] }, write: false };
+        case "records": {
+            const zone = assertName(rest[0], "zone");
+            const domain = rest[1] === undefined ? zone : assertName(rest[1], "domain");
+            return { path: "/api/zones/records/get", params: { domain, zone, listZone: rest[1] === undefined ? "true" : "false" }, write: false };
+        }
+        case "zone-options":
+            return { path: "/api/zones/options/get", params: { zone: assertName(rest[0], "zone") }, write: false };
+        case "resolve": {
+            const type = rest[1] ?? "A";
+            if (!RECORD_TYPE.test(type)) throw new UsageError("type must be a record type such as A, AAAA, CNAME, TXT");
+            return { path: "/api/dnsClient/resolve", params: { server: "this-server", domain: assertName(rest[0], "domain"), type }, write: false };
+        }
+        case "stats": {
+            const type = rest[0] ?? "LastHour";
+            if (!STATS_TYPES.includes(type)) throw new UsageError(`stats type must be one of ${STATS_TYPES.join(", ")}`);
+            return { path: "/api/dashboard/stats/get", params: { type }, write: false };
+        }
+        case "zone-create":
+            return { path: "/api/zones/create", params: { zone: assertName(rest[0], "zone"), type: "Primary", catalog }, write: true };
+        case "zone-delete":
+            return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, write: true };
+        case "record-add":
+        case "record-update":
+        case "record-delete": {
+            const zone = assertName(rest[0], "zone");
+            const domain = assertName(rest[1], "domain");
+            if (!RECORD_TYPE.test(rest[2])) throw new UsageError("type must be a record type such as A, AAAA, CNAME, TXT");
+            const params = parseParams(rest.slice(3));
+            for (const fixed of ["zone", "domain", "type"]) {
+                if (fixed in params) throw new UsageError(`${fixed} is a positional argument`);
+            }
+            return { path: `/api/zones/records/${name.slice("record-".length)}`, params: { ...params, zone, domain, type: rest[2] }, write: true };
+        }
+        default:
+            throw new UsageError(`unknown technitium command: ${name}`);
+    }
+}
+
+interface TechnitiumResponse {
+    status?: string;
+    errorMessage?: string;
+    response?: unknown;
+}
+
+async function technitium(config: DnsConfig, args: string[]): Promise<number> {
+    const node = args[0];
+    if (!NODES.includes(node as Node)) throw new UsageError(`technitium <${NODES.join("|")}> <command> [args]`);
+    const request = technitiumRequest(config.technitiumCatalog, args.slice(1));
+    if (request.write && node !== "primary") throw new UsageError("writes go to the primary; the secondary follows through the catalog zone");
+    const base = node === "primary" ? config.technitiumPrimaryUrl : config.technitiumSecondaryUrl;
+    const token = readSecret(SERVICE, node === "primary" ? "TECHNITIUM_TOKEN" : "TECHNITIUM2_TOKEN");
+    const response = await fetch(new URL(request.path, base), {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams(request.params),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const text = await response.text();
+    let parsed: TechnitiumResponse;
+    try {
+        parsed = JSON.parse(text) as TechnitiumResponse;
+    } catch {
+        throw new ServiceError(`Technitium ${node} answered ${response.status} with a non-JSON body`);
+    }
+    if (parsed.status !== "ok") {
+        throw new ServiceError(`Technitium ${node}: ${parsed.status ?? response.status}${parsed.errorMessage ? `: ${parsed.errorMessage}` : ""}`);
+    }
+    printJson({ node, status: parsed.status, response: redactSecrets(parsed.response ?? null) });
+    return 0;
+}
+
+interface CloudflareEnvelope {
+    success: boolean;
+    errors?: { code: number; message: string }[];
+    result?: unknown;
+    result_info?: { page?: number; total_pages?: number; count?: number; total_count?: number };
+}
+
+async function cloudflareCall(method: string, path: string, body?: unknown): Promise<CloudflareEnvelope> {
+    const token = readSecret(SERVICE, "CLOUDFLARE_TOKEN");
+    const response = await fetch(`${CLOUDFLARE_API}${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}`, Accept: "application/json", ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    let envelope: CloudflareEnvelope;
+    try {
+        envelope = (await response.json()) as CloudflareEnvelope;
+    } catch {
+        throw new ServiceError(`Cloudflare answered ${response.status} with a non-JSON body`);
+    }
+    if (!response.ok || !envelope.success) {
+        const detail = (envelope.errors ?? []).map((e) => `${e.code} ${e.message}`).join("; ");
+        throw new ServiceError(`Cloudflare ${method} ${path} failed (${response.status})${detail ? `: ${detail}` : ""}`);
+    }
+    return envelope;
+}
+
+interface CloudflareZone {
+    id: string;
+    name: string;
+    status?: string;
+    paused?: boolean;
+    name_servers?: string[];
+}
+
+interface CloudflareRecord {
+    id: string;
+    type: string;
+    name: string;
+    content: string;
+    ttl: number;
+    proxied?: boolean;
+    comment?: string | null;
+    modified_on?: string;
+}
+
+function compactRecord(record: CloudflareRecord): CloudflareRecord {
+    const { id, type, name, content, ttl, proxied, comment, modified_on } = record;
+    return { id, type, name, content, ttl, proxied, comment: comment ?? undefined, modified_on };
+}
+
+async function zoneId(zone: string): Promise<string> {
+    const envelope = await cloudflareCall("GET", `/zones?name=${encodeURIComponent(assertName(zone, "zone"))}`);
+    const zones = envelope.result as CloudflareZone[];
+    if (zones.length !== 1) throw new UsageError(`zone ${zone} is not visible to the token`);
+    return zones[0].id;
+}
+
+export function parseRecordFilters(args: string[]): { zone: string; query: URLSearchParams } {
+    const query = new URLSearchParams();
+    let zone: string | undefined;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--type" || a === "--name") {
+            const value = args[i + 1];
+            if (value === undefined) throw new UsageError(`${a} needs a value`);
+            if (a === "--type" && !RECORD_TYPE.test(value)) throw new UsageError("--type must be a record type");
+            if (a === "--name") assertName(value, "--name");
+            query.set(a.slice(2), value);
+            i++;
+        } else if (a.startsWith("-")) {
+            throw new UsageError(`unknown option ${a}`);
+        } else if (zone === undefined) {
+            zone = a;
+        } else {
+            throw new UsageError("cloudflare records <zone> [--type T] [--name fqdn]");
+        }
+    }
+    if (zone === undefined) throw new UsageError("cloudflare records <zone> [--type T] [--name fqdn]");
+    return { zone: assertName(zone, "zone"), query };
+}
+
+function parseJsonObject(text: string | undefined, what: string): Record<string, unknown> {
+    if (text === undefined) throw new UsageError(`${what}: JSON body missing`);
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(text);
+    } catch {
+        throw new UsageError(`${what}: body must be JSON`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new UsageError(`${what}: body must be a JSON object`);
+    return parsed as Record<string, unknown>;
+}
+
+async function cloudflare(args: string[]): Promise<number> {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case "verify": {
+            const accountId = readSecret(SERVICE, "CLOUDFLARE_ACCOUNT_ID");
+            if (!HEX_ID.test(accountId)) throw new ServiceError("CLOUDFLARE_ACCOUNT_ID is not a 32-character hex id");
+            const envelope = await cloudflareCall("GET", `/accounts/${accountId}/tokens/verify`);
+            printJson(redactSecrets(envelope.result));
+            return 0;
+        }
+        case "zones": {
+            const envelope = await cloudflareCall("GET", "/zones?per_page=50");
+            printJson((envelope.result as CloudflareZone[]).map(({ id, name, status, paused, name_servers }) => ({ id, name, status, paused, name_servers })));
+            return 0;
+        }
+        case "records": {
+            const { zone, query } = parseRecordFilters(rest);
+            const id = await zoneId(zone);
+            query.set("per_page", "5000");
+            const records: CloudflareRecord[] = [];
+            for (let page = 1; ; page++) {
+                query.set("page", String(page));
+                const envelope = await cloudflareCall("GET", `/zones/${id}/dns_records?${query.toString()}`);
+                records.push(...(envelope.result as CloudflareRecord[]).map(compactRecord));
+                if (page >= (envelope.result_info?.total_pages ?? 1)) break;
+            }
+            printJson({ zone, zoneId: id, count: records.length, records });
+            return 0;
+        }
+        case "record-add": {
+            if (rest.length !== 2) throw new UsageError("cloudflare record-add <zone> <json>");
+            const body = parseJsonObject(rest[1], "record-add");
+            const envelope = await cloudflareCall("POST", `/zones/${await zoneId(rest[0])}/dns_records`, body);
+            printJson(compactRecord(envelope.result as CloudflareRecord));
+            return 0;
+        }
+        case "record-update": {
+            if (rest.length !== 3 || !HEX_ID.test(rest[1])) throw new UsageError("cloudflare record-update <zone> <recordId> <json>");
+            const body = parseJsonObject(rest[2], "record-update");
+            const envelope = await cloudflareCall("PATCH", `/zones/${await zoneId(rest[0])}/dns_records/${rest[1]}`, body);
+            printJson(compactRecord(envelope.result as CloudflareRecord));
+            return 0;
+        }
+        case "record-delete": {
+            if (rest.length !== 2 || !HEX_ID.test(rest[1])) throw new UsageError("cloudflare record-delete <zone> <recordId>");
+            const envelope = await cloudflareCall("DELETE", `/zones/${await zoneId(rest[0])}/dns_records/${rest[1]}`);
+            printJson(envelope.result);
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown cloudflare command: ${sub ?? "(none)"}\n${HELP}`);
+    }
+}
+
+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<DnsConfig>(SERVICE, SHAPE);
+    switch (args[0]) {
+        case "technitium":
+            return technitium(config, args.slice(1));
+        case "cloudflare":
+            return cloudflare(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);
+}