@astrofoundry/pi-astro 0.20.3 → 0.21.0

package/README.md

@@ -79,7 +79,7 @@ pi                # launch; confirm [Extensions] lists astro-subagents, grimoire
 
 **Bundled subagents** (call them as `astro.<name>`):
 - General-purpose: `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
-- Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first), `identity` (Zitadel, Pomerium, certificates), `network` (UniFi, FreeRADIUS, Tailscale, read-only), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Hermes gateways and upgrades, Europa health)
+- Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi reads and firewall policies, FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Hermes gateways and upgrades, Europa health)
 - Flourish pipeline: `flourish-input-vision` (image to spec), `flourish-input-narrative` (text to spec), `flourish-input-codebase` (HTML to spec), `flourish-architect` (spec to plan), `flourish-template-developer` (plan to SDK template, needs `@flourish/sdk`), `flourish-example-builder` (template to realistic example), `flourish-preview-runner` (multi-breakpoint preview + screenshots, needs `@flourish/sdk`), `flourish-reviewer` (audit)
 
 **Skills** (loadable via `/skill:<name>`):

package/agents/identity.md

@@ -17,6 +17,6 @@ Rules:
 - Read before you write. List existing Zitadel resources before creating one; never create duplicates.
 - Zitadel calls use the v2 resource APIs (`/v2/...`); use `/management/v1/` or `/admin/v1/` only when v2 lacks the operation.
 - Responses are redacted; a client secret or key is shown once by Zitadel and is not recoverable through this tool. When an operation returns a secret, tell the caller to store it in Vaultwarden immediately.
-- Pomerium route changes are edits to `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository, deployed with its `deploy.sh`. Through this tool you can render, restart, reload, renew certificates, and read state. Propose the route diff; do not claim to have deployed it.
+- Pomerium routes live in `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository. Change them there (`git pull`, `git show`, `git write`, `git diff`, `git commit`, `git push`), then `dmz deploy-config`, then `dmz status` and `dmz journal pomerium`. Never describe a route as live before `deploy-config` succeeded; when it rolls back, report the error and leave the repository commit for the operator to revert or fix.
 - Confirm destructive operations (deleting users, applications, projects) are explicitly requested in the task.
 - Delegate through `subagent` only to another specialist (`astro.arcane`, `astro.network`, `astro.dns`, `astro.edge`, `astro.security`, `astro.backup`, `astro.proxmox`, `astro.inference`) and only for that specialist's own area.

package/agents/network.md

@@ -1,6 +1,6 @@
 ---
 name: network
-description: Operates the UniFi network (sites, devices, clients, networks, firewall policies), FreeRADIUS on LXC 108, and the Tailscale router on LXC 105 through the network tool. Use for network, VLAN, Wi-Fi, policy, and remote-access questions and checks.
+description: Operates the UniFi network (sites, devices, clients, networks, zones, firewall policies including policy create, update, and delete), FreeRADIUS on LXC 108, and the Tailscale router on LXC 105 through the network tool. Use for network, VLAN, Wi-Fi, firewall policy, and remote-access questions, checks, and policy changes.
 tools: read, network, subagent
 skills: network
 systemPromptMode: replace
@@ -14,7 +14,9 @@ You are the network specialist. The `network` tool is your only way to reach Uni
 
 Rules:
 
-- UniFi access is read-only in this version. Report configuration and state; when a change is needed, describe the exact UniFi setting and value and stop.
+- UniFi writes are limited to firewall policies. Before `policy-create`, read an existing policy of the same kind with `firewall-policy` and copy its structure; read `firewall-zones` for the zone ids; never invent a field name. After a write, read the policy back and report id, name, zones, filters, and action.
+- `policy-delete` only when the task names the policy exactly; read it first and quote its name.
+- Every other UniFi change (networks, Wi-Fi, devices, zones) is an operator task: describe the exact setting and value and stop.
 - Start with `["unifi", "sites"]` to get the site id; every other UniFi read needs it.
 - RADIUS and Tailscale operations are fixed checks on the guests; `radius-check` validates the FreeRADIUS configuration without restarting it.
 - Wi-Fi CA rotation and device certificates are out of scope for this tool; point the caller to the homelab repository's `radius` folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/identity/SKILL.md

@@ -34,10 +34,20 @@ Fixed operations on VM 104 through a forced-command SSH key. No other command re
 | `pomerium-restart` | restart Pomerium |
 | `nginx-reload` | `nginx -t` then reload |
 | `lego-renew` | run the certificate renewal now |
+| `deploy-config` | install the pushed `config.yaml` as `/etc/pomerium/config.yaml.template`, render with the Vaultwarden values, restart Pomerium, check it is active; on failure restores the previous template and restarts |
+
+## `git <command>` (homelab repository)
+
+`status`, `pull`, `ls [dir]`, `show <path>`, `diff`, `log [n]`, `write <path> <content>`, `commit <message>`, `push`. Writes are limited to `02-pulsar-proxmox/dmz/`. The checkout is the specialist's own clone; `git pull` before reading or editing.
 
 ## Pomerium route changes
 
-Routes are defined in `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository and deployed with `deploy.sh --proxy-only`, which also runs `render`. You cannot deploy a route change through this tool. Produce the exact YAML diff for the caller, then after deployment verify with `status` and `journal pomerium`.
+1. `git pull`, `git show 02-pulsar-proxmox/dmz/config.yaml`; find a route of the same kind (public with policy, or internal) and copy its shape. Secrets in the file are `{{ }}` placeholders rendered on the guest from Vaultwarden; never write a literal secret.
+2. `git write 02-pulsar-proxmox/dmz/config.yaml <whole file>`, `git diff` (only the intended lines), `git commit "Add Pomerium route for <hostname>"`, `git push`.
+3. `dmz deploy-config`; it refuses while the checkout is dirty or differs from origin.
+4. `dmz status`, `dmz journal pomerium '5 minutes ago'`. Report the route, the commit, and the health.
+
+A public hostname also needs the VPS SNI entry (edge specialist), the internal DNS zone pointing at `10.0.20.10` and the public record (dns specialist); say which of those still misses.
 
 ## When to stop and report
 

package/skills/network/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: network
-description: How the network specialist reads UniFi and checks FreeRADIUS and Tailscale through the network tool.
+description: How the network specialist reads UniFi, manages firewall policies, and checks FreeRADIUS and Tailscale through the network tool.
 ---
 
 # Network specialist
@@ -18,7 +18,9 @@ Read-only calls to the console's Network API, TLS pinned to the console certific
 | `device <siteId> <deviceId>` | one device with ports and radios |
 | `clients <siteId>` | connected clients |
 | `networks <siteId>` | networks and VLANs |
-| `firewall-policies <siteId>` | zone policies |
+| `firewall-policies <siteId>` | zone policies (filter with `--filter "name.like('%from Cortex')"`) |
+| `firewall-policy <siteId> <policyId>` | one policy, full object |
+| `firewall-zones <siteId>` | zones with ids and member networks |
 | `wans <siteId>` | WAN interfaces |
 | `get /v1/...` | any other documented GET |
 
@@ -31,6 +33,21 @@ Filters use the API's syntax, for example `--filter "state.eq('ONLINE')"`. Pagin
 
 `unifi fingerprint` prints the console certificate fingerprint; the operator uses it to pin the certificate in the wrapper config.
 
+## `unifi policy-create|policy-update|policy-delete`
+
+| Command | Effect |
+|---|---|
+| `policy-create <siteId> <json>` | `POST /v1/sites/{siteId}/firewall/policies`; the body needs `name`, `enabled`, `action`, `source`, `destination`, `ipProtocolScope`, `loggingEnabled` |
+| `policy-update <siteId> <policyId> <json>` | `PUT` with the complete policy object |
+| `policy-delete <siteId> <policyId> --confirm` | delete |
+
+Procedure for a new allow policy: `firewall-zones` for the two zone ids; `firewall-policies` with a name filter to find a policy of the same shape (the `from Cortex` family: source zone plus source IP filter, destination zone plus IP and port filter, TCP, IPv4, return traffic allowed, logging off); `firewall-policy` to read it in full; build the new body from that object with new `name`, addresses, and ports, without `id`, `index`, or `metadata`; `policy-create`; read the result back. UniFi validates the body; quote its error message when it rejects one. Names follow `<what> - from <source>`.
+
+```json
+{ "args": ["unifi", "firewall-policies", "<siteId>", "--filter", "name.like('%from Cortex')"] }
+{ "args": ["unifi", "policy-create", "<siteId>", "{\"name\":\"Proxmox API - from Cortex\", ...}"] }
+```
+
 ## `pulsar <command>`
 
 Fixed checks through a forced-command SSH key to Pulsar (Proxmox host `10.0.10.37`), which runs them inside the guests.
@@ -47,4 +64,4 @@ Fixed checks through a forced-command SSH key to Pulsar (Proxmox host `10.0.10.3
 
 ## Out of scope in this version
 
-UniFi changes, Wi-Fi CA rotation, device certificate enrollment, and DNS. Describe the needed change precisely and stop. DNS belongs to the `dns` specialist.
+UniFi changes other than firewall policies (networks, Wi-Fi, zones, devices), Wi-Fi CA rotation, device certificate enrollment, and DNS. Describe the needed change precisely and stop. DNS belongs to the `dns` specialist.

package/specialists/AGENTS.md

@@ -39,7 +39,8 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 - Exit codes: `UsageError` 2, `ServiceError` 1, success 0. Diagnostics on stderr, results on stdout, JSON where possible.
 - Output filters: Arcane responses pass `stripKeys(ARCANE_DENIED_KEYS)`; Zitadel responses pass `redactSecrets`. Add keys there rather than in a wrapper.
 - Fixed remote commands: `DMZ_COMMANDS`, `PULSAR_COMMANDS`, `VPS_COMMANDS`, `OBS_COMMANDS`, `BACKUP_COMMANDS`, `HOST_COMMANDS`, and `INFERENCE_COMMANDS` must match the entry scripts in `entry/remote/` and their tracked copies in the homelab repository (`02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`, `00-frontdoor-vps/system/`, `02-pulsar-proxmox/observability/system/`, `02-pulsar-proxmox/hermes/system/`, `04-nexus-macstudio/system/`, and `host/` of the `astronaute77/arcane` repository). Pulsar's root `authorized_keys` carries one forced key per specialist (network, backup, proxmox, inference), each pinned to its own entry script. Change both sides in the same commit and redeploy the remote script. A new privileged step on the VPS also needs its exact line in `spc-edge-frontdoor-sudoers`.
-- Repository access is `lib/repo.ts` (`repoCommand`, `RepoSpec`): one clone per specialist under `~/.specialists/work/<checkoutName>`, a write deploy key, and an optional `writeRoot` that limits `git write`. `edge` deploys only what origin has: `deploy-nginx` refuses a dirty, ahead, or behind checkout.
+- Repository access is `lib/repo.ts` (`repoCommand`, `RepoSpec`, `trackedFile`): one clone per specialist under `~/.specialists/work/<checkoutName>`, a write deploy key, and an optional `writeRoot` that limits `git write`. `edge` (`deploy-nginx`) and `identity` (`dmz deploy-config`) deploy only what origin has: `trackedFile` refuses a dirty, ahead, or behind checkout. The DMZ entry keeps the previous template and restores it when render or restart fails.
+- `network` firewall policy writes are `policyWrite`: JSON body from the agent, checked for the documented required fields, sent as `POST`, `PUT`, or `DELETE` through the same pinned request; UniFi validates the rest.
 - The IAP tunnel is `lib/tunnel.ts`: `gcloud compute start-iap-tunnel <instance> 22 --local-host-port=localhost:<port>` (a documented flag; the hidden `--listen-on-stdin` is not used), ready when the port accepts a connection, closed after the ssh call. `gcloud auth activate-service-account` runs before every tunnel with `CLOUDSDK_CONFIG` under `~/.specialists/work/gcloud` and `CLOUDSDK_PYTHON` from the config, because the Homebrew cask ships no interpreter.
 - `dns` builds every Technitium call from `TECHNITIUM_READS` and `TECHNITIUM_WRITES`; `key=value` record parameters pass through by name (`token` and `node` refused) because the API documents dozens of type-specific parameters. Writes are refused on the secondary in code: the catalog zone is the only replication path.
 - `security` parses Wazuh alert lines locally (`summariseWazuh`) so the guest never needs `jq`.
@@ -68,4 +69,4 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 
 ## Next
 
-All nine specialists exist. Next in the agreed order: second-level tools (UniFi policy writes for `network`, Pomerium route deployment for `identity`, Europa scheduled-task control for `inference`), then Discord access to the specialists, then the Astrogate route.
+All nine specialists exist; `network` writes firewall policies and `identity` deploys Pomerium routes. Open: Europa scheduled-task control for `inference` (needs Europa on to test Windows OpenSSH forced commands), then Discord access to the specialists, then the Astrogate route.

package/specialists/README.md

@@ -5,8 +5,8 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
 | Agent | Area | What it can do |
 |---|---|---|
 | `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.identity` | Zitadel; Pomerium, nginx, lego on VM 104; `02-pulsar-proxmox/dmz/` in the homelab repository | Any Zitadel API call (v2, management, admin, auth) with responses redacted; `dmz status|journal|config-template|render|pomerium-restart|nginx-reload|lego-renew|deploy-config`; `git` on the homelab checkout, writes limited to `02-pulsar-proxmox/dmz/` |
+| `astro.network` | UniFi, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read UniFi sites, devices, clients, networks, zones, firewall policies, WANs; create, update, delete firewall policies; 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` |
@@ -24,7 +24,7 @@ Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both
 - 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. `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. `proxmox` cannot create, clone, or destroy guests, change disks, or touch the host. `backup` cannot change retention or schedules. `inference` cannot start Europa or change models.
+Limits: `network` writes only firewall policies on UniFi. `security` is read-only. `identity` deploys only `config.yaml` to the DMZ. `edge` changes only `nginx.conf` on the VPS; `dns` writes only to the Technitium primary. `proxmox` cannot create, clone, or destroy guests, change disks, or touch the host. `backup` cannot change retention or schedules. `inference` cannot start Europa or change models.
 
 ## Enable specialists on a host
 
@@ -32,7 +32,7 @@ Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14
 
 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`.
+   - `identity`: `ZITADEL_PAT`, `SSH_KEY_DMZ_B64`, `HOMELAB_DEPLOY_KEY_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`.
@@ -41,7 +41,7 @@ Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14
    - `proxmox`: `PVE_TOKEN_ID` (plain, `spc-proxmox@pve!cortex`), `PVE_TOKEN_SECRET`, `SSH_KEY_PULSAR_B64`.
    - `inference`: `SSH_KEY_NEXUS_B64`, `SSH_KEY_HERMES_B64`, `SSH_KEY_PULSAR_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. Proxmox (`ssh pulsar`): user `spc-proxmox@pve`, role `SpecialistGuest` = `VM.Audit VM.PowerMgmt VM.Snapshot VM.Snapshot.Rollback VM.Config.CPU VM.Config.Memory VM.Config.Options VM.Config.Network VM.Config.CDROM VM.GuestAgent.Audit`, ACLs `PVEAuditor` on `/` and `SpecialistGuest` on `/vms` for both the user and the token `spc-proxmox@pve!cortex` (`-privsep 1`).
-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`, TCP 5380 on `10.0.40.53`, `10.0.40.54`, TCP 8006 on `10.0.10.37`, and TCP 8081 on `10.0.60.5`. GitHub: `spc-arcane-gitops` as a write deploy key on `astronaute77/arcane`, `spc-edge-homelab` as a write deploy key on `astronaute77/homelab`.
+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`, TCP 5380 on `10.0.40.53`, `10.0.40.54`, TCP 8006 on `10.0.10.37`, and TCP 8081 on `10.0.60.5`. GitHub: `spc-arcane-gitops` as a write deploy key on `astronaute77/arcane`, `spc-edge-homelab` and `spc-identity-homelab` as write deploy keys 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
@@ -59,7 +59,8 @@ Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14
    { "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" }
+   { "zitadelDomain": "auth.37pla.net", "dmzHost": "10.0.20.10", "dmzUser": "dmz",
+     "homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "02-pulsar-proxmox/dmz", "pomeriumConfig": "02-pulsar-proxmox/dmz/config.yaml" }
    { "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",

package/specialists/edge/run.ts

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { readConfig } from "../lib/config.ts";
 import { ServiceError, UsageError } from "../lib/errors.ts";
@@ -6,7 +5,7 @@ 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 { REPO_HELP, repoCommand, trackedFile, type RepoSpec } from "../lib/repo.ts";
 import { secretPath } from "../lib/secrets.ts";
 import { sshFixed } from "../lib/ssh.ts";
 import { openTunnel } from "../lib/tunnel.ts";
@@ -164,20 +163,9 @@ function repoSpec(config: EdgeConfig): RepoSpec {
     };
 }
 
-/** 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 input = stdin ? await trackedFile(repoSpec(config), config.nginxConf) : 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") {

package/specialists/entry/remote/spc-identity-dmz-entry.sh

@@ -21,5 +21,22 @@ case "$name" in
   pomerium-restart) sudo systemctl restart pomerium && systemctl is-active pomerium ;;
   nginx-reload) sudo nginx -t && sudo systemctl reload nginx ;;
   lego-renew) sudo systemctl start lego-renew.service && systemctl status lego-renew.service --no-pager --lines=10 ;;
+  deploy-config)
+    stage="$(mktemp -d)"
+    cat > "$stage/config.yaml"
+    sudo cp -p /etc/pomerium/config.yaml.template "$stage/template.previous"
+    sudo install -o root -g pomerium -m 0640 "$stage/config.yaml" /etc/pomerium/config.yaml.template
+    if sudo /usr/local/sbin/render-pomerium && sudo systemctl restart pomerium && systemctl is-active --quiet pomerium; then
+      echo "deployed Pomerium configuration; pomerium active"
+      sudo rm -rf "$stage"
+    else
+      echo "deploy failed; restoring the previous template" >&2
+      sudo install -o root -g pomerium -m 0640 "$stage/template.previous" /etc/pomerium/config.yaml.template
+      sudo /usr/local/sbin/render-pomerium || true
+      sudo systemctl restart pomerium || true
+      systemctl is-active pomerium >&2 || true
+      sudo rm -rf "$stage"
+      exit 1
+    fi ;;
   *) echo "refused: $cmd" >&2; exit 2 ;;
 esac

package/specialists/identity/run.ts

@@ -4,6 +4,7 @@ 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 { REPO_HELP, repoCommand, trackedFile, type RepoSpec } from "../lib/repo.ts";
 import { redactSecrets } from "../lib/sanitize.ts";
 import { readSecret, secretPath } from "../lib/secrets.ts";
 import { sshFixed } from "../lib/ssh.ts";
@@ -14,9 +15,23 @@ interface IdentityConfig extends Record<string, string> {
     zitadelDomain: string;
     dmzHost: string;
     dmzUser: string;
+    homelabRemote: string;
+    homelabBranch: string;
+    /** Folder of the homelab repository this specialist may write. */
+    repoArea: string;
+    /** Tracked Pomerium configuration deployed by `dmz deploy-config`. */
+    pomeriumConfig: string;
 }
 
-const SHAPE = { zitadelDomain: "string", dmzHost: "string", dmzUser: "string" } as const;
+const SHAPE = {
+    zitadelDomain: "string",
+    dmzHost: "string",
+    dmzUser: "string",
+    homelabRemote: "string",
+    homelabBranch: "string",
+    repoArea: "string",
+    pomeriumConfig: "string",
+} as const;
 
 const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
 type Method = (typeof METHODS)[number];
@@ -25,7 +40,7 @@ type Method = (typeof METHODS)[number];
 export const API_PREFIXES: readonly string[] = ["/v2/", "/management/v1/", "/admin/v1/", "/auth/v1/"];
 
 /** Fixed remote commands; the target's forced command accepts exactly these names. */
-export const DMZ_COMMANDS: Readonly<Record<string, { args: number; help: string }>> = {
+export const DMZ_COMMANDS: Readonly<Record<string, { args: number; help: string; stdin?: true }>> = {
     status: { args: 0, help: "pomerium, nginx, lego-renew.timer status" },
     journal: { args: 2, help: "journal <pomerium|nginx|lego-renew> <since>, e.g. journal pomerium '1 hour ago'" },
     "config-template": { args: 0, help: "print /etc/pomerium/config.yaml.template (no secrets; rendered values come from Vaultwarden)" },
@@ -33,6 +48,7 @@ export const DMZ_COMMANDS: Readonly<Record<string, { args: number; help: string
     "pomerium-restart": { args: 0, help: "restart pomerium" },
     "nginx-reload": { args: 0, help: "test nginx config and reload" },
     "lego-renew": { args: 0, help: "run lego-renew.service now" },
+    "deploy-config": { args: 0, help: "install the tracked Pomerium config.yaml from the pushed homelab checkout as the template, render, restart, check; rolls back on failure", stdin: true },
 };
 
 const DMZ_UNITS = ["pomerium", "nginx", "lego-renew"];
@@ -46,8 +62,10 @@ const HELP = `identity specialist
 ${Object.entries(DMZ_COMMANDS)
     .map(([name, c]) => `      ${name.padEnd(18)} ${c.help}`)
     .join("\n")}
+${REPO_HELP}
+      (homelab repository; writes are limited to the configured area)
 
-Pomerium route changes are edits to 02-pulsar-proxmox/dmz/config.yaml in the homelab repository, deployed with its deploy.sh. This wrapper renders, restarts, and reads.`;
+Pomerium routes: edit config.yaml in the checkout, commit, push, then dmz deploy-config; it refuses while the checkout is dirty or differs from origin.`;
 
 export function validateApiPath(path: string): string {
     if (!API_PREFIXES.some((p) => path.startsWith(p))) throw new UsageError(`path must start with one of ${API_PREFIXES.join(", ")}`);
@@ -97,8 +115,21 @@ async function zitadel(config: IdentityConfig, args: string[]): Promise<number>
     return 0;
 }
 
+function repoSpec(config: IdentityConfig): RepoSpec {
+    return {
+        service: SERVICE,
+        checkoutName: "homelab",
+        remote: config.homelabRemote,
+        branch: config.homelabBranch,
+        deployKeyField: "HOMELAB_DEPLOY_KEY",
+        writeRoot: config.repoArea,
+        help: HELP,
+    };
+}
+
 async function dmz(config: IdentityConfig, args: string[]): Promise<number> {
     const remote = buildDmzRemote(args);
+    const input = DMZ_COMMANDS[args[0]]?.stdin ? await trackedFile(repoSpec(config), config.pomeriumConfig) : undefined;
     const result = await sshFixed(
         {
             host: config.dmzHost,
@@ -107,7 +138,8 @@ async function dmz(config: IdentityConfig, args: string[]): Promise<number> {
             knownHostsFile: join(specialistsHome(), "config", "known_hosts"),
         },
         remote,
-        120_000,
+        180_000,
+        input,
     );
     if (result.stdout.length > 0) printRaw(result.stdout);
     if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `dmz ${args[0]} exited ${result.code}`);
@@ -125,6 +157,8 @@ export async function command(args: string[]): Promise<number> {
             return zitadel(config, args.slice(1));
         case "dmz":
             return dmz(config, args.slice(1));
+        case "git":
+            return repoCommand(repoSpec(config), args.slice(1));
         default:
             throw new UsageError(`unknown command: ${args[0]}\n${HELP}`);
     }

package/specialists/lib/repo.ts

@@ -103,6 +103,16 @@ export async function repoStatus(spec: RepoSpec, dir: string): Promise<RepoStatu
     return { branch, ahead, behind, changed };
 }
 
+/** Content of a tracked file, only when the checkout equals origin: nothing uncommitted, nothing unpushed, nothing behind. */
+export async function trackedFile(spec: RepoSpec, rel: string): Promise<string> {
+    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, rel), "utf-8");
+}
+
 export async function repoCommand(spec: RepoSpec, args: string[]): Promise<number> {
     const [sub, ...rest] = args;
     const dir = await ensureCheckout(spec);

package/specialists/network/run.ts

@@ -31,6 +31,8 @@ export const UNIFI_READS: Readonly<Record<string, { params: number; path: (p: st
     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>" },
+    "firewall-policy": { params: 2, path: ([s, p]) => `/v1/sites/${s}/firewall/policies/${p}`, help: "firewall-policy <siteId> <policyId>" },
+    "firewall-zones": { params: 1, path: ([s]) => `/v1/sites/${s}/firewall/zones`, help: "firewall-zones <siteId>" },
     wans: { params: 1, path: ([s]) => `/v1/sites/${s}/wans`, help: "wans <siteId>" },
 };
 
@@ -55,6 +57,9 @@ ${Object.values(UNIFI_READS)
     .map((r) => `      ${r.help}`)
     .join("\n")}
   unifi get <path>            any GET under /v1 (path must start with /v1/)
+  unifi policy-create <siteId> <json>              POST a firewall policy (name, enabled, action, source, destination, ipProtocolScope, loggingEnabled)
+  unifi policy-update <siteId> <policyId> <json>   PUT the full policy object
+  unifi policy-delete <siteId> <policyId> --confirm
   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)
@@ -114,16 +119,58 @@ export function unifiPath(args: string[]): string {
     return qs.length > 0 ? `${path}?${qs}` : path;
 }
 
-/** 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> {
+/** Request over TLS pinned to the console certificate; the console is self-signed. */
+export function pinnedGet(url: URL, apiKey: string | null, expectedFingerprint: string | null, method = "GET", body?: string): Promise<PinnedResponse> {
     return pinnedRequest(url, {
-        method: "GET",
-        headers: { Accept: "application/json", ...(apiKey ? { "X-API-KEY": apiKey } : {}) },
+        method,
+        headers: {
+            Accept: "application/json",
+            ...(apiKey ? { "X-API-KEY": apiKey } : {}),
+            ...(body === undefined ? {} : { "Content-Type": "application/json", "Content-Length": String(Buffer.byteLength(body)) }),
+        },
+        body,
         expectedFingerprint,
         timeoutMs: 30_000,
     });
 }
 
+/** Documented required fields of "Create or update firewall policy". */
+export const POLICY_REQUIRED = ["name", "enabled", "action", "source", "destination", "ipProtocolScope", "loggingEnabled"];
+
+export interface PolicyWrite {
+    method: "POST" | "PUT" | "DELETE";
+    path: string;
+    body?: string;
+}
+
+/** Maps policy-create, policy-update, policy-delete to the firewall policy endpoints. */
+export function policyWrite(args: string[]): PolicyWrite {
+    const [name, ...rest] = args;
+    const confirmed = rest.filter((a) => a !== "--confirm");
+    const site = confirmed[0];
+    if (site === undefined || !UUID.test(site)) throw new UsageError(`${name}: siteId must be a UUID`);
+    if (name === "policy-delete") {
+        if (rest.length !== 3 || !rest.includes("--confirm") || !UUID.test(confirmed[1] ?? "")) throw new UsageError("policy-delete <siteId> <policyId> --confirm");
+        return { method: "DELETE", path: `/v1/sites/${site}/firewall/policies/${confirmed[1]}` };
+    }
+    const jsonText = name === "policy-create" ? confirmed[1] : confirmed[2];
+    if (name === "policy-create" ? confirmed.length !== 2 : confirmed.length !== 3 || !UUID.test(confirmed[1] ?? "")) {
+        throw new UsageError(name === "policy-create" ? "policy-create <siteId> <json>" : "policy-update <siteId> <policyId> <json>");
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(jsonText);
+    } catch {
+        throw new UsageError(`${name}: body must be JSON`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new UsageError(`${name}: body must be a JSON object`);
+    const missing = POLICY_REQUIRED.filter((k) => !(k in (parsed as Record<string, unknown>)));
+    if (missing.length > 0) throw new UsageError(`${name}: body lacks ${missing.join(", ")}`);
+    return name === "policy-create"
+        ? { method: "POST", path: `/v1/sites/${site}/firewall/policies`, body: JSON.stringify(parsed) }
+        : { method: "PUT", path: `/v1/sites/${site}/firewall/policies/${confirmed[1]}`, body: JSON.stringify(parsed) };
+}
+
 async function unifi(config: NetworkConfig, args: string[]): Promise<number> {
     const base = new URL(config.unifiBaseUrl);
     if (args[0] === "fingerprint") {
@@ -131,9 +178,10 @@ async function unifi(config: NetworkConfig, args: string[]): Promise<number> {
         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);
+    const write = args[0] === "policy-create" || args[0] === "policy-update" || args[0] === "policy-delete" ? policyWrite(args) : null;
+    const url = new URL(`${base.pathname.replace(/\/$/, "")}${write ? write.path : unifiPath(args)}`, base);
+    const response = write ? await pinnedGet(url, apiKey, config.unifiCertSha256, write.method, write.body) : await pinnedGet(url, apiKey, config.unifiCertSha256);
     let parsed: unknown = response.body;
     try {
         parsed = JSON.parse(response.body);

package/specialists/wrappers.test.ts

@@ -10,7 +10,7 @@ import { API_PREFIXES, buildDmzRemote, validateApiPath, command as identityComma
 import { buildInferenceRemote, compactReleases, command as inferenceCommand } from "./inference/run.ts";
 import { UsageError } from "./lib/errors.ts";
 import { safeRepoPath, safeWritePath } from "./lib/repo.ts";
-import { buildPulsarRemote, parseQuery, unifiPath, command as networkCommand } from "./network/run.ts";
+import { POLICY_REQUIRED, buildPulsarRemote, parseQuery, policyWrite, unifiPath, command as networkCommand } from "./network/run.ts";
 import { buildHostRemote, needsConfirm, parseSetPairs, parseVmid, validateApiPath as validatePvePath, command as proxmoxCommand } from "./proxmox/run.ts";
 import { buildObsRemote, compactDecisions, summariseAlerts, summariseWazuh, command as securityCommand } from "./security/run.ts";
 
@@ -62,6 +62,7 @@ describe("identity wrapper", () => {
         expect(() => buildDmzRemote(["journal", "pomerium", "x; rm -rf /"])).toThrow(/since/);
         expect(() => buildDmzRemote(["render", "extra"])).toThrow(/0 argument/);
         expect(() => buildDmzRemote(["reboot"])).toThrow(/unknown dmz command/);
+        expect(buildDmzRemote(["deploy-config"])).toBe("deploy-config");
     });
 
     it("prints help without touching config", async () => {
@@ -94,6 +95,22 @@ describe("network wrapper", () => {
         expect(() => unifiPath(["reboot"])).toThrow(/unknown unifi read/);
     });
 
+    it("maps firewall policy writes to the documented endpoints", () => {
+        const policy = { name: "x", enabled: true, action: { type: "ALLOW" }, source: { zoneId: site }, destination: { zoneId: site }, ipProtocolScope: { ipVersion: "IPV4" }, loggingEnabled: false };
+        const body = JSON.stringify(policy);
+        expect(policyWrite(["policy-create", site, body])).toEqual({ method: "POST", path: `/v1/sites/${site}/firewall/policies`, body });
+        expect(policyWrite(["policy-update", site, site, body])).toEqual({ method: "PUT", path: `/v1/sites/${site}/firewall/policies/${site}`, body });
+        expect(policyWrite(["policy-delete", site, site, "--confirm"])).toEqual({ method: "DELETE", path: `/v1/sites/${site}/firewall/policies/${site}` });
+        expect(() => policyWrite(["policy-delete", site, site])).toThrow(/--confirm/);
+        expect(() => policyWrite(["policy-create", "default", body])).toThrow(/UUID/);
+        expect(() => policyWrite(["policy-create", site, "{"])).toThrow(/JSON/);
+        expect(() => policyWrite(["policy-create", site, JSON.stringify({ name: "x" })])).toThrow(/lacks/);
+        expect(() => policyWrite(["policy-update", site, "nope", body])).toThrow(UsageError);
+        expect(unifiPath(["firewall-zones", site])).toBe(`/v1/sites/${site}/firewall/zones`);
+        expect(unifiPath(["firewall-policy", site, site])).toBe(`/v1/sites/${site}/firewall/policies/${site}`);
+        expect(POLICY_REQUIRED).toContain("ipProtocolScope");
+    });
+
     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");