@astrofoundry/pi-astro 0.40.9 → 0.40.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -80,7 +80,7 @@ pi # launch; confirm [Extensions] lists astro-subagents, grimoire
80
80
 
81
81
  **Bundled subagents** (call them as `astro.<name>`):
82
82
  - General-purpose: `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
83
- - Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first; sanitized host checks, Mealie and Paperless dumps, stack image updates with rollback, and the documented manager upgrade, both with buttons on the daily report), `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, public route checks), `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, Europa health), `media` (trendarr: trending titles, recommendations from the library, Radarr and Sonarr adds, SABnzbd pause)
83
+ - Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first; sanitized host checks, Mealie and Paperless dumps, stack image updates with rollback, and the documented manager upgrade, both with buttons on the daily report), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi consoles of sites 37 and Mira: reads and every Network API write, through the cloud with local fallback; FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository, public route checks), `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, Europa health), `media` (trendarr: trending titles, recommendations from the library, Radarr and Sonarr adds, SABnzbd pause)
84
84
  - Release notes: `release-reviewer` (no tools; judges whether an update could break how we use a tool or image, for the Cortex Tools Report and the Arcane Daily Report)
85
85
  - Supervision: `foreman` (read only; diagnoses an unattended update that failed its check, through the specialists)
86
86
  - 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)
package/agents/network.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: network
3
- 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.
3
+ description: Operates the UniFi consoles of sites 37 (Madrid homelab) and Mira (networks, Wi-Fi, zones, firewall policies, ACL rules, DNS policies, devices, clients; reads and writes), FreeRADIUS on LXC 108, and the Tailscale router on LXC 105 through the network tool. Use for network, VLAN, Wi-Fi, firewall, and remote-access questions, checks, and changes on either site.
4
4
  tools: read, network, subagent
5
5
  skills: network
6
6
  systemPromptMode: replace
@@ -14,10 +14,11 @@ You are the network specialist. The `network` tool is your only way to reach Uni
14
14
 
15
15
  Rules:
16
16
 
17
- - 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.
18
- - `policy-delete` only when the task names the policy exactly; read it first and quote its name.
19
- - Every other UniFi change (networks, Wi-Fi, devices, zones) is an operator task: describe the exact setting and value and stop.
20
- - Start with `["unifi", "sites"]` to get the site id; every other UniFi read needs it.
17
+ - Name the site in every UniFi call: `37` (Madrid homelab) or `mira`. When the task does not say which site, ask.
18
+ - Before a write, read the current object (or one of the same kind for a create) and copy its structure; never invent a field name. After a write, read the object back and report its id, name, and what changed.
19
+ - A delete only when the task names the object exactly; read it first and quote its name.
20
+ - A change that can cut connectivity (networks, Wi-Fi, firewall, DNS, device restart or adoption) states first what traffic it affects and on which site.
21
+ - Start with `["unifi", "<site>", "sites"]` to get that console's site id; every other UniFi call needs it.
21
22
  - RADIUS and Tailscale operations are fixed checks on the guests; `radius-check` validates the FreeRADIUS configuration without restarting it.
22
23
  - Wi-Fi CA rotation and device certificates are out of scope for this tool; point the caller to the homelab repository's `radius` folder.
23
24
  - Report facts from the JSON output. Never infer a client's identity beyond what UniFi returns.
@@ -12,6 +12,9 @@ describe("approvals", () => {
12
12
  expect(isRisky("identity", ["zitadel", "GET", "/v2/users"])).toBe(false);
13
13
  expect(isRisky("identity", ["zitadel", "DELETE", "/v2/users/1"])).toBe(true);
14
14
  expect(isRisky("identity", ["dmz", "deploy-config"])).toBe(true);
15
+ expect(isRisky("network", ["unifi", "mira", "networks", "x"])).toBe(false);
16
+ expect(isRisky("network", ["unifi", "37", "write", "DELETE", "/v1/sites/x/acl-rules/y"])).toBe(true);
17
+ expect(isRisky("network", ["unifi", "mira", "--local", "write", "PUT", "/v1/sites/x/networks/y", "{}"])).toBe(true);
15
18
  expect(isRisky("arcane", ["projects", "list"])).toBe(false);
16
19
  expect(isRisky("arcane", ["projects", "redeploy", "mealie"])).toBe(false);
17
20
  expect(isRisky("arcane", ["projects", "upgrade", "media", "sonarr", "--yes"])).toBe(false);
@@ -32,7 +32,8 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
32
32
  /^host\s+(db-restore|radarr-movie|radarr-interface)\b/,
33
33
  ],
34
34
  identity: [/^zitadel\s+(DELETE|POST|PUT|PATCH)\b/, /^dmz\s+(deploy-config|pomerium-restart|render|lego-renew)\b/],
35
- network: [/^unifi\s+policy-(create|update|delete)\b/],
35
+ // Every UniFi write, on either console.
36
+ network: [/^unifi\s+\S+\s+write\b/],
36
37
  dns: [/^technitium\s+primary\s+(zone-create|zone-delete|record-add|record-update|record-delete)\b/, /^cloudflare\s+record-(add|update|delete)\b/],
37
38
  edge: [/^vps\s+deploy-nginx\b/],
38
39
  backup: [/^(vzdump-run|host-backup-run|arcane-backup-run|gcs-run|restic-check-run|restic-restore|restore-clean)\b/],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.9",
3
+ "version": "0.40.11",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -86,6 +86,7 @@ The usual trigger is the owner's **Upgrade Arcane** button under the Arcane Dail
86
86
  - `service-check grimoire|mealie` (guest-local endpoints), `crawl4ai-info`, `recyclarr-naming`, `arcane-version`, `queue-callback`, `bazarr-providers`, `mealie-api`, `queue-job <uuid>`, `object-stat grimoire <path>`.
87
87
  - `radarr-movie <tt…> [command-id]` and `radarr-interface` read Radarr's key from its host config; each needs an owner's approval.
88
88
  - `db-list mealie|paperless`, `db-dump mealie|paperless` (gzip pg_dump into `/var/backups/spc-arcane/<stack>/<UTC>`, checked, with row counts), `db-restore <stack> <stamp>` (owner approval): fills an **empty** database from one of those dumps, the app container stopped meanwhile. It refuses a database that holds tables; emptying one is an operator decision. Dumps are never deleted by the tool; `db-list` names those beyond the last three in `over_keep`.
89
+ - `supabase-backup`: the backup `supabase/AGENTS.md` asks for before a Supabase change. It writes custom-format dumps of `postgres` and `_supabase`, `globals.sql`, and `db-config.tar.gz` (the pgsodium root key) into `/var/backups/supabase-upgrades/<UTC>`, checks each dump with pg_restore's listing and full decoding, and prints the manifest with the image's repo digests (record them as the rollback digest). It refuses when the disk has less free space than the databases. Restoring stays an operator step.
89
90
 
90
91
  Public routes (Supabase, Grimoire, Mealie URLs) are `astro.edge`'s `route-probe`, run from Cortex.
91
92
 
@@ -1,15 +1,24 @@
1
1
  ---
2
2
  name: network
3
- description: How the network specialist reads UniFi, manages firewall policies, and checks FreeRADIUS and Tailscale through the network tool.
3
+ description: How the network specialist reads and changes the UniFi consoles of sites 37 and Mira, and checks FreeRADIUS and Tailscale through the network tool.
4
4
  ---
5
5
 
6
6
  # Network specialist
7
7
 
8
- UniFi (console `https://10.0.10.1`) enforces the homelab's network policy: nine VLANs, inter-zone traffic denied unless a policy allows it, Wi-Fi `Ardilla-37` (EAP-TLS via FreeRADIUS on LXC 108), `Ardilla-IoT`, `Ardilla-GUEST`. LXC 105 runs the Tailscale subnet router for remote administration. The `network` tool has two families.
8
+ Two UniFi sites, each with its own console:
9
9
 
10
- ## `unifi <read> [--limit n] [--offset n] [--filter expr]`
10
+ - `37` (Madrid, console `10.0.10.1`): the homelab. Nine VLANs, inter-zone traffic denied unless a policy allows it, Wi-Fi `Ardilla-37` (EAP-TLS via FreeRADIUS on LXC 108), `Ardilla-IoT`, `Ardilla-GUEST`. LXC 105 runs the Tailscale subnet router for remote administration.
11
+ - `mira` (console `192.168.1.1`): the second location. Wi-Fi `Astro` (192.168.1.0/24) and `AstroGuest` (192.168.40.0/24).
11
12
 
12
- Read-only calls to the console's Network API, TLS pinned to the console certificate.
13
+ The consoles are joined by Site Magic (SD-WAN). Never call either site "home". The `network` tool has three families.
14
+
15
+ ## Paths to a console
16
+
17
+ Every `unifi <37|mira>` call goes through the UniFi cloud connector (`api.ui.com`) with the account key. When the cloud cannot serve a read (timeout, rate limit, 5xx, no connection), the wrapper reads from the console directly with that console's local key, TLS pinned, and says so on stderr. A write never retries: the cloud may have applied it before failing, so read the object back first, then retry with `--local` only if it is missing. `--local` skips the cloud. Cortex reaches `37`'s console directly; `mira`'s only once Site Magic carries the route.
18
+
19
+ ## `unifi <37|mira> <read> [--local] [--limit n] [--offset n] [--filter expr]`
20
+
21
+ Reads of that console's Network API. `<siteId>` is the UUID that `sites` returns for that console (each console has its own).
13
22
 
14
23
  | Read | Path |
15
24
  |---|---|
@@ -22,32 +31,37 @@ Read-only calls to the console's Network API, TLS pinned to the console certific
22
31
  | `firewall-policy <siteId> <policyId>` | one policy, full object |
23
32
  | `firewall-zones <siteId>` | zones with ids and member networks |
24
33
  | `wans <siteId>` | WAN interfaces |
25
- | `get /v1/...` | any other documented GET |
34
+ | `get /v1/...` | any other documented GET, such as `/v1/sites/{siteId}/wifi/broadcasts`, `/acl-rules`, `/dns/policies`, `/networks/{id}/references` |
26
35
 
27
36
  Filters use the API's syntax, for example `--filter "state.eq('ONLINE')"`. Pagination fields `offset`, `limit`, `totalCount` are in every list response.
28
37
 
29
38
  ```json
30
- { "args": ["unifi", "sites"] }
31
- { "args": ["unifi", "clients", "<siteId>", "--limit", "100"] }
39
+ { "args": ["unifi", "37", "sites"] }
40
+ { "args": ["unifi", "mira", "clients", "<siteId>", "--limit", "100"] }
32
41
  ```
33
42
 
34
- `unifi fingerprint` prints the console certificate fingerprint; the operator uses it to pin the certificate in the wrapper config.
43
+ `unifi <37|mira> fingerprint` prints that console's certificate fingerprint; the operator uses it to pin the certificate in the wrapper config.
35
44
 
36
- ## `unifi policy-create|policy-update|policy-delete`
45
+ ## `unifi <37|mira> write <POST|PUT|PATCH|DELETE> <path> [json] [--local]`
37
46
 
38
- | Command | Effect |
39
- |---|---|
40
- | `policy-create <siteId> <json>` | `POST /v1/sites/{siteId}/firewall/policies`; the body needs `name`, `enabled`, `action`, `source`, `destination`, `ipProtocolScope`, `loggingEnabled` |
41
- | `policy-update <siteId> <policyId> <json>` | `PUT` with the complete policy object |
42
- | `policy-delete <siteId> <policyId> --confirm` | delete |
47
+ Any write of the Network API under `/v1/sites/<siteId>/`: networks, Wi-Fi broadcasts, firewall policies and their ordering, firewall zones, ACL rules and their ordering, DNS policies, traffic matching lists, device adoption and actions, client actions, hotspot vouchers. POST, PUT, and PATCH take one JSON body as one argument; DELETE takes none. The wrapper checks only the method, the path, and that the body is JSON; the console validates the rest, so quote its error message when it rejects one. Every write waits for the owner's approval when the call comes from Discord.
48
+
49
+ Procedure for every write:
43
50
 
44
- 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>`.
51
+ 1. Read the current object (or, for a create, an existing object of the same kind) with `get` and copy its structure; never invent a field name. A PUT sends the complete object without `id` and `metadata`.
52
+ 2. For a firewall policy, read `firewall-zones` for the zone ids; names follow `<what> - from <source>` (the `from Cortex` family on 37: source zone plus source IP filter, destination zone plus IP and port filter, TCP, IPv4, return traffic allowed, logging off).
53
+ 3. Write, then read the object back and report its id, name, and the fields that changed.
45
54
 
46
55
  ```json
47
- { "args": ["unifi", "firewall-policies", "<siteId>", "--filter", "name.like('%from Cortex')"] }
48
- { "args": ["unifi", "policy-create", "<siteId>", "{\"name\":\"Proxmox API - from Cortex\", ...}"] }
56
+ { "args": ["unifi", "37", "firewall-policies", "<siteId>", "--filter", "name.like('%from Cortex')"] }
57
+ { "args": ["unifi", "37", "write", "POST", "/v1/sites/<siteId>/firewall/policies", "{\"name\":\"Proxmox API - from Cortex\", ...}"] }
58
+ { "args": ["unifi", "mira", "write", "DELETE", "/v1/sites/<siteId>/acl-rules/<aclRuleId>"] }
49
59
  ```
50
60
 
61
+ ## `unifi cloud <path>`
62
+
63
+ Reads of the Site Manager API itself (`/v1/` or `/ea/`): `/v1/hosts` (consoles and their host ids), `/v1/sites`, `/v1/devices`, `/v1/sd-wan-configs` and `/v1/sd-wan-configs/{id}/status` (Site Magic), `/v1/isp-metrics/{type}`. Lists page with `pageSize` and `nextToken` in the query.
64
+
51
65
  ## `pulsar <command>`
52
66
 
53
67
  Fixed checks through a forced-command SSH key to Pulsar (Proxmox host `10.0.10.37`), which runs them inside the guests.
@@ -64,4 +78,4 @@ Fixed checks through a forced-command SSH key to Pulsar (Proxmox host `10.0.10.3
64
78
 
65
79
  ## Out of scope in this version
66
80
 
67
- 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.
81
+ Site Magic configuration (read-only through the API; the owner changes it at unifi.ui.com), console settings outside the Network API, Wi-Fi CA rotation, device certificate enrollment, and DNS records. Describe the needed change precisely and stop. DNS records belong to the `dns` specialist; UniFi DNS policies on a console are yours.
@@ -40,7 +40,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
40
40
  - Output filters: Arcane responses pass `stripKeys(ARCANE_DENIED_KEYS)`; Zitadel responses pass `redactSecrets`. Add keys there rather than in a wrapper.
41
41
  - 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/`, `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), 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`.
42
42
  - Repository access is `lib/repo.ts` (`repoCommand`, `RepoSpec`, `trackedFile`): one clone per specialist under `~/.specialists/work/<checkoutName>` (`homelab-edge`, `homelab-identity`; never share a checkout between specialists), 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.
43
- - `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.
43
+ - `network` reaches two consoles, `37` and `mira` (`SITES`), each with `unifi<Site>HostId`, `unifi<Site>LocalUrl`, and `unifi<Site>CertSha256` in `network.json`. `siteRequest` goes through the Site Manager cloud connector (`api.ui.com/v1/connector/consoles/<hostId>/network/integration/...`, account key `UNIFI_API_KEY`); a read the cloud cannot serve (no connection, 408, 429, 5xx) retries on the console itself with its local key (`UNIFI_LOCAL_37_API_KEY`, `UNIFI_LOCAL_MIRA_API_KEY`) through the pinned request, a write never retries because the cloud may have applied it before failing; `--local` skips the cloud. Writes are `unifiWrite`: any `POST`, `PUT`, `PATCH`, or `DELETE` under `/v1/sites/<siteId>/` with a JSON body (none for `DELETE`); UniFi validates the rest, and the gate asks the owner for every one. `unifi cloud <path>` reads the Site Manager API (`/v1/`, `/ea/`, never the connector). Each command reads only the config keys it needs, so `pulsar` works without the UniFi keys.
44
44
  - Pi executes sibling tool calls in parallel, so two wrapper processes of the same specialist can run at once. `lib/lock.ts` (`withLock`, a directory lock under `~/.specialists/work/locks`, stale after 10 minutes) serialises shared resources; `edge` holds `edge-tunnel` around the fixed IAP port and the gcloud configuration directory. `arcane` holds `arcane-gitops` (stale after 3 hours) around `git`, `manager-upgrade`, and `stack-update`, because an update keeps the checkout for up to about two hours; the other `repo.ts` checkouts are not locked yet.
45
45
  - `edge` retries one SSH call through the IAP tunnel when the first connection is closed during setup (`isTransientSshFailure`: exit 255 with "closed by remote host" or a reset), except `reboot`. 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.
46
46
  - `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.
@@ -58,7 +58,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
58
58
  - `main()` waits for stdout and stderr to flush before `process.exit`: on a pipe, exiting right after a write drops everything past the 64 KiB buffer, which cut large answers such as `projects list --all` until 2026-09-25 (`lib/flush.test.ts`).
59
59
  - `arcane update-report [--all]` is `lib/image-updates.ts` over `lib/registry.ts`: a fresh `images updates check --all`, then `projects list --all` for the stack and service of each image reference, then the registries' tag lists and manifest digests (anonymous bearer tokens from each registry's challenge; digests by HEAD, which Docker Hub does not count as a pull; lscr.io is read from ghcr.io). A floating or major-series tag is resolved to the release tag whose digest matches the running and the latest build, searching the newest tags of the three commonest release shapes; a fixed tag is compared with the newest tag of the same shape; a digest pin with the newest release. Checks older than one minute before the run count as stale and show as unknown. Private images (anonymous access refused with 401 or 403) are excluded from rows, counts, and table, listed in `privateImages`, and counted in the summary line. The table is fixed-width text for a code block, because Discord renders no Markdown tables. The answer adds `holds` from `update-holds.json` at origin's branch head (`git show`, no working-tree read), or `holdsError` when that file is malformed.
60
60
  - `arcane stack-update <stack> [--confirm]` (`lib/stack-update.ts` for the pure parts) is deterministic: refuses `arcane`, held stacks (the checkout's `update-holds.json` after `pull --ff-only`; a malformed file is an error), a dirty or ahead checkout, stopped stacks, and an update across a major version without `--confirm` (which the gate turns into an owner approval). Pending rows come from a fresh per-image check resolved like `update-report`. `edit tag`/`edit digest` rows rewrite `image:` lines that name exactly the old reference (`replaceImageRef`, quoted or not, trailing comment kept) in the sync's `composePath`, then commit, push, and wait for `gitops list` to report success at that commit (20 min, polled every 30 s). Then `projects redeploy <stack> --yes` (35 min), container checks through `containers list --all` and `containers get` (`composeInfo.projectName`, health; 5 min, polled every 15 s; a job that exited with code 0 counts as done whatever health its image's inherited check left, as bigcapital's migration did on 2026-10-28), and a fresh check that each service is current. A failure after a commit reverts, pushes, waits for the sync, redeploys, and checks again (`rolled back`); a pull-only failure stays `failed`. Every outcome prints JSON with `status` and exits 0. Worst case about 125 minutes, so the gate's `timeoutMs` for arcane must exceed it (8,100,000). The checkout is not locked, so an agent call and a bridge click at the same time can collide on it; the bridge runs one Arcane update at a time.
61
- - `arcane host <command>` runs over the forced-command key of user `spc-arcane` on VM 100. `HOST_COMMANDS` in `lib/arcane-host.ts` must list exactly the operations of `entry/remote/spc-arcane-op.py` (a test compares them); the tracked copies live in the arcane repository's `host/` (`spc-arcane-host-entry`, `spc-arcane-op`, `spc-arcane-sudoers`, `spc-arcane-install.sh`) with the probes in `host/spc-arcane-probes/`. The entry only splits words (letters, digits, space, `._:/+-`) and hands them to `sudo -n /usr/local/sbin/spc-arcane-op`, the one command its sudoers line allows; the op checks the name and every argument and runs the reviewed arcane-ops probes, which print only allowlisted fields. Manager steps (`manager-*`) are internal to `manager-upgrade`/`manager-rollback` and refused through `host`. Nothing on the host deletes data: a manager rollback restores the image and Compose file, not the data volume (R3 stays manual), `db-restore` only fills an empty database, and dumps are never pruned by the tool. `host-audit` compares the host's hashes with `host/<name>` of the `arcane-gitops` checkout after a pull.
61
+ - `arcane host <command>` runs over the forced-command key of user `spc-arcane` on VM 100. `HOST_COMMANDS` in `lib/arcane-host.ts` must list exactly the operations of `entry/remote/spc-arcane-op.py` (a test compares them); the tracked copies live in the arcane repository's `host/` (`spc-arcane-host-entry`, `spc-arcane-op`, `spc-arcane-sudoers`, `spc-arcane-install.sh`) with the probes in `host/spc-arcane-probes/`. The entry only splits words (letters, digits, space, `._:/+-`) and hands them to `sudo -n /usr/local/sbin/spc-arcane-op`, the one command its sudoers line allows; the op checks the name and every argument and runs the reviewed arcane-ops probes, which print only allowlisted fields. Manager steps (`manager-*`) are internal to `manager-upgrade`/`manager-rollback` and refused through `host`. Nothing on the host deletes data: a manager rollback restores the image and Compose file, not the data volume (R3 stays manual), `db-restore` only fills an empty database, and dumps are never pruned by the tool. `supabase-backup` writes the pre-change backup of `supabase/AGENTS.md` (both databases with `pg_dump -Fc`, each listed and fully decoded by `pg_restore`, `pg_dumpall --globals-only`, and the `supabase-db-config` volume, which must hold `pgsodium_root.key`) into `/var/backups/supabase-upgrades/<UTC>`, the folder of the earlier manual backups. `host-audit` compares the host's hashes with `host/<name>` of the `arcane-gitops` checkout after a pull.
62
62
  - `arcane manager-upgrade <version>` (`lib/arcane-manager.ts`) follows arcane/AGENTS.md "Manager upgrades": the official image's revision label must equal the release tag's commit (GitHub API), `manager-prepare` records `compose.before.yaml` and every container before the pin commit, the pin goes through the `arcane-gitops` checkout (`git` is exported from `lib/repo.ts` for this), the wait polls `gitops list` and the deployed Compose hash every 30 s for up to 30 minutes, then pull, cold backup, `up -d --no-deps --pull never`, and checks. Any failure before the restart reverts the pin (`stopped`); a failed check after it reverts the pin and runs `manager-rollback` (`rolled back`). The answer always exits 0 with `status`, so the bridge and the agent both see it.
63
63
  - `media` runs trendarr unchanged: `trendarrCli` in `media.json` is its `dist/cli.js`, started with `process.execPath` because sudo's PATH has no node. Each call gets `HOME` set to a fresh `0700` directory under `~/.specialists/work/media/` that holds only `.trendarr/config.json` (`0600`, trendarr's own schema, built from the note fields and `media.json`) and is removed in `finally`; trendarr reads no environment variables and has no config flag, and Node's `os.homedir()` follows `$HOME` on POSIX. Every call passes `--json`; `init` is refused. An add prints trendarr's per-ID `results` and exits 0 even when trendarr exits 1 for a failed ID, because the gate shows only stderr on failure; other failures carry trendarr's stderr without its `warning:` lines, which go into the JSON as `warnings`. The bridge's slash commands and Add buttons call the same wrapper through the entry point (`extensions/astro-discord/media.ts`).
64
64
  - `arcane release-notes <stack>[/<service>]` is `lib/releases.ts`: a single-image check and `resolveRef` give the running and latest versions, `HttpRegistry.labels` reads `org.opencontainers.image.source` from the latest image (index to linux/amd64 manifest to config blob), and the anonymous GitHub releases API (60 requests an hour, up to 3 pages of 100) gives the releases in between, oldest first. `condenseNotes` keeps each release under 12,000 characters by section priority; `capTotal` drops the oldest releases past 40,000 characters in total.
@@ -83,4 +83,4 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
83
83
 
84
84
  ## Next
85
85
 
86
- All ten specialists exist; `media` (trendarr, slash commands and Add buttons in Discord) was added on 2026-10-19; `network` writes firewall policies, `identity` deploys Pomerium routes, and Discord access is live. The Astrogate webhook route was built end to end through `identity`, `edge`, `network`, and `dns` on 2026-09-17. Open: Europa scheduled-task control for `inference` (needs Europa on to test Windows OpenSSH forced commands).
86
+ All ten specialists exist; `media` (trendarr, slash commands and Add buttons in Discord) was added on 2026-10-19; `network` writes anything the UniFi Network API offers on the consoles of 37 and Mira (2026-10-28), `identity` deploys Pomerium routes, and Discord access is live. The Astrogate webhook route was built end to end through `identity`, `edge`, `network`, and `dns` on 2026-09-17. Open: Europa scheduled-task control for `inference` (needs Europa on to test Windows OpenSSH forced commands).
@@ -4,9 +4,9 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
4
4
 
5
5
  | Agent | Area | What it can do |
6
6
  |---|---|---|
7
- | `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; `update-report` (fresh check of every stack with running and latest release versions); `release-notes <stack>/<service>` (GitHub notes between the two versions); `change-origin <path> <sha256|-> <utc>` (whether a deployment-file change Wazuh saw is a GitOps commit or one of our operations); `project-status`, `deployment check|wait`; `stack-update <stack>` (a stack's pending image updates through GitOps, redeploy, checks, and rollback; across a major version only with `--confirm`, owner approval; held stacks in the repository's `update-holds.json` are refused); `manager-upgrade <version>` and `manager-rollback <stamp>` (the documented manager upgrade, owner approval); `host <command>`: sanitized host checks (memory, stats, logs, OOM, kernel OOM, audit, capacity, storage, Docker usage, service and queue checks) and `db-list|db-dump|db-restore` for Mealie and Paperless through user `spc-arcane` on VM 100; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
7
+ | `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; `update-report` (fresh check of every stack with running and latest release versions); `release-notes <stack>/<service>` (GitHub notes between the two versions); `change-origin <path> <sha256|-> <utc>` (whether a deployment-file change Wazuh saw is a GitOps commit or one of our operations); `project-status`, `deployment check|wait`; `stack-update <stack>` (a stack's pending image updates through GitOps, redeploy, checks, and rollback; across a major version only with `--confirm`, owner approval; held stacks in the repository's `update-holds.json` are refused); `manager-upgrade <version>` and `manager-rollback <stamp>` (the documented manager upgrade, owner approval); `host <command>`: sanitized host checks (memory, stats, logs, OOM, kernel OOM, audit, capacity, storage, Docker usage, service and queue checks) `db-list|db-dump|db-restore` for Mealie and Paperless, and `supabase-backup` (both Supabase databases, roles, and the pgsodium key) through user `spc-arcane` on VM 100; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
8
8
  | `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/` |
9
- | `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 |
9
+ | `astro.network` | UniFi consoles of sites 37 and Mira, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read and write everything the UniFi Network API offers on either console (cloud connector, local console as read fallback); Site Manager reads; RADIUS and Tailscale checks on Pulsar |
10
10
  | `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 |
11
11
  | `astro.edge` | Frontdoor VPS (`frontdoor-1337`) over an IAP tunnel; `00-frontdoor-vps/` in the homelab repository | `probe` the public path; `route-probe` (status of the Supabase, Grimoire, and Mealie public routes from Cortex); `vps status|nginx-conf|nginx-test|journal|wg|bouncer|updates|package|changelog|auto-upgrades|deploy-nginx|reboot --confirm`; `git` on the homelab checkout, writes limited to `00-frontdoor-vps/` |
12
12
  | `astro.security` | Wazuh, CrowdSec, rsyslog archive on VM 106 | Read-only: `status`, `attention`, `agents`, `alerts`, `decisions`, `bouncers`, `metrics`, `wazuh-alerts`, `wazuh-vulns`, `wazuh-events`, `wazuh-vuln-events`, `wazuh-log`, `remote-hosts`, `remote-log`, `journal` |
@@ -26,7 +26,7 @@ Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both
26
26
  - Every call is logged in `/Users/specialist/.specialists/audit.log`.
27
27
  - 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.
28
28
 
29
- 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. `media` adds titles and toggles the download queue; it cannot delete anything or change Radarr, Sonarr, or SABnzbd settings.
29
+ Limits: `network` writes only through the UniFi Network API (no Site Magic or console settings). `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. `media` adds titles and toggles the download queue; it cannot delete anything or change Radarr, Sonarr, or SABnzbd settings.
30
30
 
31
31
  ## Enable specialists on a host
32
32
 
@@ -35,7 +35,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
35
35
  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'`):
36
36
  - `arcane`: `ZITADEL_KEY_JSON`, `GITOPS_DEPLOY_KEY_B64`, `ZITADEL_USER_ID` (plain), `SSH_KEY_ARCANE_HOST_B64` (user `spc-arcane` on VM 100, for `host`, `manager-*`), and optionally `MEALIE_API_KEY` (only `host mealie-api` reads it).
37
37
  - `identity`: `ZITADEL_PAT`, `SSH_KEY_DMZ_B64`, `HOMELAB_DEPLOY_KEY_B64`.
38
- - `network`: `UNIFI_API_KEY`, `SSH_KEY_PULSAR_B64`.
38
+ - `network`: `UNIFI_API_KEY` (account key: unifi.ui.com, Settings, API Keys), `UNIFI_LOCAL_37_API_KEY` and `UNIFI_LOCAL_MIRA_API_KEY` (each console: Network, Settings, Integrations), `SSH_KEY_PULSAR_B64`.
39
39
  - `dns`: `TECHNITIUM_TOKEN`, `TECHNITIUM2_TOKEN` (Technitium API tokens of the primary and the secondary), `CLOUDFLARE_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`.
40
40
  - `edge`: `GCP_SA_KEY_JSON` (service account key), `SSH_KEY_FRONTDOOR_B64`, `HOMELAB_DEPLOY_KEY_B64`.
41
41
  - `security`: `SSH_KEY_OBS_B64`.
@@ -44,7 +44,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
44
44
  - `inference`: `SSH_KEY_NEXUS_B64`.
45
45
  - `media`: `TMDB_ACCESS_TOKEN` (TMDB API Read Access Token), `OMDB_API_KEY`, `RADARR_API_KEY`, `SONARR_API_KEY` (Settings, General, Security; each app has one), `SABNZBD_API_KEY` (the API key, not the NZB key, which can only add NZBs and cannot read or pause the queue).
46
46
  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`).
47
- 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`.
47
+ 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: the account key and a local key per console (fields above) and policies on 37 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`.
48
48
  4. **Sudo and user**, as an administrator:
49
49
  ```sh
50
50
  printf 'cortex ALL=(ALL) ALL\n' | sudo tee /etc/sudoers.d/cortex >/dev/null
@@ -71,7 +71,8 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
71
71
  "gitopsRemote": "git@github.com:astronaute77/arcane.git", "gitopsBranch": "main" }
72
72
  { "zitadelDomain": "auth.37pla.net", "dmzHost": "10.0.20.10", "dmzUser": "dmz",
73
73
  "homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "02-pulsar-proxmox/dmz", "pomeriumConfig": "02-pulsar-proxmox/dmz/config.yaml" }
74
- { "unifiBaseUrl": "https://10.0.10.1/proxy/network/integration", "unifiCertSha256": "<from: specialist-cli network -- unifi fingerprint>", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
74
+ { "unifi37HostId": "<from: specialist-cli network -- unifi cloud /v1/hosts>", "unifi37LocalUrl": "https://10.0.10.1/proxy/network/integration", "unifi37CertSha256": "<from: specialist-cli network -- unifi 37 fingerprint>",
75
+ "unifiMiraHostId": "<the same>", "unifiMiraLocalUrl": "https://192.168.1.1/proxy/network/integration", "unifiMiraCertSha256": "<the same>", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
75
76
  { "technitiumPrimaryUrl": "http://10.0.40.53:5380", "technitiumSecondaryUrl": "http://10.0.40.54:5380", "technitiumCatalog": "catalog.invalid" }
76
77
  { "gcloud": "/usr/local/libexec/specialist-gcloud/current/bin/gcloud", "gcloudPython": "/usr/local/libexec/specialist-python/current/bin/python3",
77
78
  "project": "frontdoor-1337", "zone": "us-east1-c", "instance": "frontdoor-1337", "serviceAccount": "spc-edge@frontdoor-1337.iam.gserviceaccount.com",
@@ -134,7 +135,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
134
135
  { "agent": "astro.media", "tool": "media", "service": "media", "timeoutMs": 660000 } ] }
135
136
  ```
136
137
 
137
- 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`, `backup -- vzdump-tasks`, `proxmox -- guests`, `inference -- nexus-status`, `media -- sabnzbd status`; `/run astro.arcane -- list projects` works in Pi; `bash` with `arcane-cli --help` is blocked in a normal session.
138
+ 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 37 sites`, `dns -- technitium primary zones`, `edge -- vps status`, `security -- attention`, `backup -- vzdump-tasks`, `proxmox -- guests`, `inference -- nexus-status`, `media -- sabnzbd status`; `/run astro.arcane -- list projects` works in Pi; `bash` with `arcane-cli --help` is blocked in a normal session.
138
139
 
139
140
  ## Discord
140
141
 
@@ -144,7 +145,7 @@ The `astro-discord` extension gives Discord users access to the specialists from
144
145
  - Media: where the `media` specialist is present (`config channel <#channel> always media`), `/trending [type] [min_rating] [count]`, `/search <title> [type]`, and `/downloads <status|pause|resume|unpause>` run the wrapper without a model. `/downloads` answers "⏸️ Downloads are paused" with an Unpause button, or "▶️ Downloads are running"; no answer names the tool behind it. Lists arrive as two messages, Movies and Series, each title with a button beside it: **Add** adds it at once and turns into Added, In library, or Not found (Retry after a failure); a greyed-out In library or No IMDb ID button needs nothing. Notes go only to the user who clicked; when downloads are paused, the note has an **Unpause** button. When the media specialist adds a title by name and downloads stay paused, the bridge posts "⏸️ Downloads are paused" with Unpause under its answer; a click resumes the queue and the message names who resumed it. Owners and `access.media` users may use them; anyone else gets a refusal only they see, and in a channel without `media` the bot names the channels that have it. Plain messages in the channel still go to the agent, for requests by name ("add the new Dune"). A `media-weekly` report entry posts the weekly picks there every Friday at its time: three movies and three series from `recommend`, each with the library titles that led to it, an Add button, and a Not interested button; the owners are tagged when there is something new. A pick nobody acts on stays out for six months; Not interested keeps it out for good (`media-picks.json`). At startup the bridge sets the three commands as the application's global commands (servers only).
145
146
  - Arcane manager: when the morning Arcane Daily Report shows a newer manager release, the `arcane` section carries an **Upgrade Arcane to vX** button. Only an owner's click on the newest report runs `arcane manager-upgrade <version>` through the entry point (one at a time, counted as open work so no bridge restart interrupts it); the button turns into the outcome, a reply gives the result, and a successful upgrade installs the matching `arcane-cli` with `specialist-install`.
146
147
  - Access: `owners` may use every specialist and decide approvals; `access.<specialist>` lists extra users for that specialist; everyone else gets no reply. Owners change the configuration from the admin channel (`adminChannelId`) without a shell: `config show`, `config channel <#channel> <always|mention> <*|dns,edge>`, `config channel <#channel> remove`, `config access <specialist> add|remove <@user>`; the bot writes `~/.config/astro-discord/config.json` on Cortex, which is also editable by hand and re-read on every message. Deny the bot's role View Channel on channels it must never read; that is the boundary the map cannot provide.
147
- - Approvals: a risky call (anything with `--confirm`, plus writes such as record or zone deletes, Zitadel changes, Pomerium deploys, service restarts, and on Arcane destructive actions: `down`, deletes, prunes, image, volume, or network removal, `system upgrade`, `gitops delete`, plus `manager-upgrade`, `manager-rollback`, `host db-restore`, and the Radarr host-config reads; `stack-update` asks only across a major version, through its `--confirm`; an owner's Update click on the report needs no approval; help lookups never ask) pauses the specialist and posts Approve/Deny buttons; only owners' clicks count; no decision within `approvalTimeoutMinutes` denies it. The specialist then reports the denial. Ambiguous tasks get a question back instead of an action.
148
+ - Approvals: a risky call (anything with `--confirm`, plus writes such as record or zone deletes, Zitadel changes, every UniFi write, Pomerium deploys, service restarts, and on Arcane destructive actions: `down`, deletes, prunes, image, volume, or network removal, `system upgrade`, `gitops delete`, plus `manager-upgrade`, `manager-rollback`, `host db-restore`, and the Radarr host-config reads; `stack-update` asks only across a major version, through its `--confirm`; an owner's Update click on the report needs no approval; help lookups never ask) pauses the specialist and posts Approve/Deny buttons; only owners' clicks count; no decision within `approvalTimeoutMinutes` denies it. The specialist then reports the denial. Ambiguous tasks get a question back instead of an action.
148
149
  - Setup, as `cortex`: `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node does not strip types inside `node_modules`, so the files are copied first) prompts for the bot token and the ids, checks each against Discord, and writes `~/.config/astro-discord/{token,config.json,run.sh}` and the LaunchAgent; it prints the `launchctl bootstrap` line. After a pi-astro update restart the bridge with `launchctl kickstart -k gui/$(id -u)/com.astrofoundry.astro-discord`. Log: `~/Library/Logs/astro-discord.log`.
149
150
  - Discord side: application `Cortex` with a bot, Message Content Intent enabled, invited with scopes `bot` and `applications.commands` and permissions View Channel, Send Messages, Attach Files, Read Message History, Add Reactions.
150
151
 
@@ -47,6 +47,15 @@ DATABASES = {
47
47
  "paperless": {"db": "paperless-db", "user": "paperless", "database": "paperless", "app": "paperless", "table": "documents_document"},
48
48
  }
49
49
 
50
+ # The pre-change backup supabase/AGENTS.md asks for, in the layout of the
51
+ # earlier manual ones: both databases, global roles, and db-config, which holds
52
+ # the pgsodium root key that encrypted values need.
53
+ SUPABASE = {"db": "supabase-db", "user": "postgres"}
54
+ SUPABASE_DATABASES = ("postgres", "_supabase")
55
+ SUPABASE_CONFIG = Path("/var/lib/docker/volumes/supabase-db-config/_data")
56
+ SUPABASE_KEY = "./pgsodium_root.key"
57
+ SUPABASE_BACKUPS = Path("/var/backups/supabase-upgrades")
58
+
50
59
  # Tracked host files the audit compares with the repository's host/ folder.
51
60
  HOST_FILES = (
52
61
  ("arcane-backup.sh", "/usr/local/bin/arcane-backup.sh"),
@@ -634,6 +643,79 @@ def op_db_restore(args):
634
643
  raise Failed("restore failed; see the JSON above")
635
644
 
636
645
 
646
+ def to_private_file(argv, target, timeout):
647
+ descriptor = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
648
+ with os.fdopen(descriptor, "wb") as out:
649
+ return run(argv, timeout, stdout=out).returncode
650
+
651
+
652
+ def archive_readable(path):
653
+ """pg_restore reads the archive's index, then decodes every entry and row into nothing."""
654
+ for argv in (["pg_restore", "--list"], ["pg_restore", "-f", "/dev/null"]):
655
+ with open(path, "rb") as source:
656
+ if run([DOCKER, "exec", "-i", SUPABASE["db"], *argv], 1800, stdin=source, stdout=subprocess.DEVNULL).returncode != 0:
657
+ return False
658
+ return True
659
+
660
+
661
+ def op_supabase_backup(args):
662
+ """Online snapshots of each database (not one snapshot of both), roles, and the key volume; it never deletes a backup."""
663
+ arity(args, 0, 0, "supabase-backup")
664
+ if not container_running(SUPABASE["db"]):
665
+ raise Failed(f"{SUPABASE['db']} is not running")
666
+ if SUPABASE_CONFIG.is_symlink() or not SUPABASE_CONFIG.is_dir():
667
+ raise Failed(f"{SUPABASE_CONFIG} is not a plain directory")
668
+ names = ", ".join(f"'{name}'" for name in SUPABASE_DATABASES)
669
+ database_bytes = int(psql(SUPABASE, f"SELECT sum(pg_database_size(datname)) FROM pg_database WHERE datname IN ({names})", "postgres"))
670
+ root_dir(SUPABASE_BACKUPS)
671
+ free = shutil.disk_usage(SUPABASE_BACKUPS).free
672
+ # Custom-format dumps are compressed, so the databases' size bounds what the dumps need.
673
+ if free < database_bytes:
674
+ raise Failed(f"{free} bytes free under {SUPABASE_BACKUPS}, less than the databases' {database_bytes}; nothing was written")
675
+ stamp = utc_stamp()
676
+ path = SUPABASE_BACKUPS / stamp
677
+ if path.exists():
678
+ raise Failed(f"{path} already exists")
679
+ root_dir(path)
680
+ incomplete = f"{path} is incomplete and has no manifest"
681
+ files = []
682
+ for name in SUPABASE_DATABASES:
683
+ target = path / f"{name}.dump"
684
+ code = to_private_file([DOCKER, "exec", SUPABASE["db"], "pg_dump", "-U", SUPABASE["user"], "-d", name, "-Fc"], target, 3600)
685
+ if code != 0:
686
+ raise Failed(f"pg_dump of {name} failed (exit {code}); {incomplete}")
687
+ with open(target, "rb") as dumped:
688
+ magic = dumped.read(5)
689
+ if magic != b"PGDMP" or not archive_readable(target):
690
+ raise Failed(f"{target.name} did not pass pg_restore's listing and decoding; {incomplete}")
691
+ files.append(target)
692
+ roles = path / "globals.sql"
693
+ code = to_private_file([DOCKER, "exec", SUPABASE["db"], "pg_dumpall", "-U", SUPABASE["user"], "--globals-only"], roles, 600)
694
+ if code != 0 or b"CREATE ROLE" not in roles.read_bytes():
695
+ raise Failed(f"pg_dumpall --globals-only failed (exit {code}) or wrote no role; {incomplete}")
696
+ files.append(roles)
697
+ keys = path / "db-config.tar.gz"
698
+ descriptor = os.open(keys, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
699
+ with os.fdopen(descriptor, "wb") as raw, tarfile.open(fileobj=raw, mode="w:gz") as archive:
700
+ archive.add(SUPABASE_CONFIG, arcname=".")
701
+ with tarfile.open(keys, "r:gz") as archive:
702
+ if SUPABASE_KEY not in archive.getnames():
703
+ raise Failed(f"db-config holds no {SUPABASE_KEY[2:]}; {incomplete}")
704
+ files.append(keys)
705
+ sums = {f.name: sha256_file(f) for f in files}
706
+ write_private(path / "SHA256SUMS", "".join(f"{digest} {name}\n" for name, digest in sums.items()).encode())
707
+ image, image_id = must([DOCKER, "inspect", "--format", "{{.Config.Image}} {{.Image}}", SUPABASE["db"]], 30, "docker inspect").split()
708
+ digests = json.loads(must([DOCKER, "image", "inspect", "--format", "{{json .RepoDigests}}", image_id], 30, "docker image inspect"))
709
+ info = {
710
+ "stamp": stamp, "path": str(path), "image": image, "image_id": image_id, "repo_digests": digests,
711
+ "server_version": psql(SUPABASE, "SHOW server_version", "postgres"), "database_bytes": database_bytes,
712
+ "files": {f.name: {"bytes": f.stat().st_size, "sha256": sums[f.name]} for f in files},
713
+ "checked": "dumps listed and fully decoded by pg_restore, roles present, db-config holds the pgsodium key",
714
+ }
715
+ write_private(path / "manifest.json", json.dumps(info, sort_keys=True).encode())
716
+ emit(info)
717
+
718
+
637
719
  COMMANDS = {
638
720
  "container-memory": op_container_memory,
639
721
  "container-stats": op_container_stats,
@@ -665,6 +747,7 @@ COMMANDS = {
665
747
  "db-list": op_db_list,
666
748
  "db-dump": op_db_dump,
667
749
  "db-restore": op_db_restore,
750
+ "supabase-backup": op_supabase_backup,
668
751
  }
669
752
 
670
753
 
@@ -27,6 +27,7 @@ describe("Arcane host commands", () => {
27
27
  );
28
28
  expect(buildHostRemote(["db-restore", "mealie", "20261019T120000Z"]).name).toBe("db-restore");
29
29
  expect(buildHostRemote(["mealie-api"]).spec.stdinSecret).toBe("MEALIE_API_KEY");
30
+ expect(buildHostRemote(["supabase-backup"]).remote).toBe("supabase-backup");
30
31
  const bad = [
31
32
  [],
32
33
  ["rm"],
@@ -41,6 +42,7 @@ describe("Arcane host commands", () => {
41
42
  ["object-stat", "grimoire", "a/.git/config"],
42
43
  ["db-dump", "supabase"],
43
44
  ["db-restore", "mealie", "latest"],
45
+ ["supabase-backup", "_supabase"],
44
46
  ["container-stats", ...Array.from({ length: 9 }, (_, i) => `c${i}`)],
45
47
  ["manager-start"],
46
48
  ["manager-rollback", "20261019T120000Z"],
@@ -46,6 +46,7 @@ export const HOST_COMMANDS: Readonly<Record<string, HostCommand>> = {
46
46
  "db-list": { args: [1, 1], help: "db-list mealie|paperless this tool's dumps, newest last, with checksums and row counts", timeoutMs: MINUTE },
47
47
  "db-dump": { args: [1, 1], help: "db-dump mealie|paperless pg_dump into /var/backups/spc-arcane/<stack>/<UTC> (gzip, checked, sha256)", timeoutMs: 60 * MINUTE },
48
48
  "db-restore": { args: [2, 2], help: "db-restore <stack> <stamp> fill an EMPTY database from one of these dumps, the app stopped meanwhile (owner approval)", timeoutMs: 60 * MINUTE },
49
+ "supabase-backup": { args: [0, 0], help: "supabase-backup both Supabase databases, roles, and db-config (pgsodium key) into /var/backups/supabase-upgrades/<UTC>, checked", timeoutMs: 90 * MINUTE },
49
50
  "manager-state": { args: [0, 0], help: "manager-state", timeoutMs: MINUTE, internal: true },
50
51
  "manager-prepare": { args: [1, 1], help: "manager-prepare <stamp>", timeoutMs: 2 * MINUTE, internal: true },
51
52
  "manager-pull": { args: [1, 1], help: "manager-pull <digest>", timeoutMs: 16 * MINUTE, internal: true },
@@ -10,20 +10,38 @@ import { sshFixed } from "../lib/ssh.ts";
10
10
 
11
11
  const SERVICE = "network";
12
12
 
13
- interface NetworkConfig extends Record<string, string> {
13
+ /**
14
+ * The UniFi consoles: "37" (Madrid) and "mira". Each is reached through the
15
+ * cloud connector of api.ui.com with the account key UNIFI_API_KEY, or directly
16
+ * on its LAN address with its own local key, TLS pinned to its certificate.
17
+ */
18
+ export const SITES = ["37", "mira"] as const;
19
+ export type Site = (typeof SITES)[number];
20
+
21
+ const SITE_ACCESS: Readonly<Record<Site, { prefix: string; localKey: string }>> = {
22
+ "37": { prefix: "unifi37", localKey: "UNIFI_LOCAL_37_API_KEY" },
23
+ mira: { prefix: "unifiMira", localKey: "UNIFI_LOCAL_MIRA_API_KEY" },
24
+ };
25
+
26
+ interface SiteConfig {
27
+ /** Site Manager host id of the console, e.g. 900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:714694 */
28
+ hostId: string;
14
29
  /** e.g. https://10.0.10.1/proxy/network/integration */
15
- unifiBaseUrl: string;
30
+ localUrl: string;
16
31
  /** SHA-256 fingerprint of the console certificate, colon-separated uppercase hex. */
17
- unifiCertSha256: string;
18
- pulsarHost: string;
19
- pulsarUser: string;
32
+ certSha256: string;
20
33
  }
21
34
 
22
- const SHAPE = { unifiBaseUrl: "string", unifiCertSha256: "string", pulsarHost: "string", pulsarUser: "string" } as const;
35
+ const PULSAR_SHAPE = { pulsarHost: "string", pulsarUser: "string" } as const;
36
+
37
+ const CLOUD = "https://api.ui.com";
38
+ const HOST_ID = /^[A-Za-z0-9]+(:[0-9]+)?$/;
39
+ /** Cloud answers after which a read retries on the local console: timeout, rate limit, or a gateway or upstream failure. */
40
+ const CLOUD_UNAVAILABLE = new Set([408, 429, 500, 502, 503, 504]);
23
41
 
24
42
  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
25
43
 
26
- /** UniFi Network API (local console, /v1) read operations. */
44
+ /** UniFi Network API (/v1) read operations, the same on both consoles. */
27
45
  export const UNIFI_READS: Readonly<Record<string, { params: number; path: (p: string[]) => string; help: string }>> = {
28
46
  sites: { params: 0, path: () => "/v1/sites", help: "sites" },
29
47
  devices: { params: 1, path: ([s]) => `/v1/sites/${s}/devices`, help: "devices <siteId>" },
@@ -52,19 +70,22 @@ const SINCE = /^[A-Za-z0-9 :\-+]{1,40}$/;
52
70
 
53
71
  const HELP = `network specialist
54
72
 
55
- unifi <read> [--limit n] [--offset n] [--filter expr]
73
+ unifi <37|mira> <read> [--local] [--limit n] [--offset n] [--filter expr]
56
74
  ${Object.values(UNIFI_READS)
57
75
  .map((r) => ` ${r.help}`)
58
76
  .join("\n")}
59
- unifi get <path> any GET under /v1 (path must start with /v1/)
60
- unifi policy-create <siteId> <json> POST a firewall policy (name, enabled, action, source, destination, ipProtocolScope, loggingEnabled)
61
- unifi policy-update <siteId> <policyId> <json> PUT the full policy object
62
- unifi policy-delete <siteId> <policyId> --confirm
63
- unifi fingerprint print the console certificate fingerprint (for the initial pin)
77
+ unifi <37|mira> get <path> [--local] any GET under /v1/ of the console's Network API
78
+ unifi <37|mira> write <POST|PUT|PATCH|DELETE> <path> [json] [--local]
79
+ any write under /v1/sites/<siteId>/ (JSON body except for DELETE)
80
+ unifi <37|mira> fingerprint the local console's certificate fingerprint (for the pin)
81
+ unifi cloud <path> any GET of the Site Manager API (/v1/ or /ea/, not /v1/connector/)
64
82
  pulsar <command> [args] fixed operations through a forced-command SSH key
65
83
  ${Object.entries(PULSAR_COMMANDS)
66
84
  .map(([name, c]) => ` ${name.padEnd(18)} ${c.help}`)
67
- .join("\n")}`;
85
+ .join("\n")}
86
+
87
+ Calls go through the cloud connector; a read the cloud cannot serve retries on
88
+ the local console, a write never does. --local skips the cloud.`;
68
89
 
69
90
  export interface Query {
70
91
  limit?: number;
@@ -134,65 +155,132 @@ export function pinnedGet(url: URL, apiKey: string | null, expectedFingerprint:
134
155
  });
135
156
  }
136
157
 
137
- /** Documented required fields of "Create or update firewall policy". */
138
- export const POLICY_REQUIRED = ["name", "enabled", "action", "source", "destination", "ipProtocolScope", "loggingEnabled"];
158
+ export const WRITE_METHODS = ["POST", "PUT", "PATCH", "DELETE"] as const;
159
+ type WriteMethod = (typeof WRITE_METHODS)[number];
160
+
161
+ const SITE_PATH = /^\/v1\/sites\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[A-Za-z0-9/_.-]+$/i;
139
162
 
140
- export interface PolicyWrite {
141
- method: "POST" | "PUT" | "DELETE";
163
+ export interface UnifiWrite {
164
+ method: WriteMethod;
142
165
  path: string;
143
166
  body?: string;
144
167
  }
145
168
 
146
- /** Maps policy-create, policy-update, policy-delete to the firewall policy endpoints. */
147
- export function policyWrite(args: string[]): PolicyWrite {
148
- const [name, ...rest] = args;
149
- const confirmed = rest.filter((a) => a !== "--confirm");
150
- const site = confirmed[0];
151
- if (site === undefined || !UUID.test(site)) throw new UsageError(`${name}: siteId must be a UUID`);
152
- if (name === "policy-delete") {
153
- if (rest.length !== 3 || !rest.includes("--confirm") || !UUID.test(confirmed[1] ?? "")) throw new UsageError("policy-delete <siteId> <policyId> --confirm");
154
- return { method: "DELETE", path: `/v1/sites/${site}/firewall/policies/${confirmed[1]}` };
155
- }
156
- const jsonText = name === "policy-create" ? confirmed[1] : confirmed[2];
157
- if (name === "policy-create" ? confirmed.length !== 2 : confirmed.length !== 3 || !UUID.test(confirmed[1] ?? "")) {
158
- throw new UsageError(name === "policy-create" ? "policy-create <siteId> <json>" : "policy-update <siteId> <policyId> <json>");
169
+ /** `write <method> <path> [json]`: any write under one site of the Network API; the console validates the body. */
170
+ export function unifiWrite(args: string[]): UnifiWrite {
171
+ const [method, path, json, ...extra] = args;
172
+ if (!(WRITE_METHODS as readonly string[]).includes(method)) throw new UsageError(`write <${WRITE_METHODS.join("|")}> <path> [json]`);
173
+ if (path === undefined || !SITE_PATH.test(path) || path.split("/").includes("..")) throw new UsageError("write path: /v1/sites/<siteId>/... without query or traversal");
174
+ if (extra.length > 0) throw new UsageError("write takes one JSON body; quote it as one argument");
175
+ if (method === "DELETE") {
176
+ if (json !== undefined) throw new UsageError("DELETE takes no body");
177
+ return { method, path };
159
178
  }
179
+ if (json === undefined) throw new UsageError(`${method} needs a JSON body`);
160
180
  let parsed: unknown;
161
181
  try {
162
- parsed = JSON.parse(jsonText);
182
+ parsed = JSON.parse(json);
163
183
  } catch {
164
- throw new UsageError(`${name}: body must be JSON`);
184
+ throw new UsageError("body must be JSON");
165
185
  }
166
- if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new UsageError(`${name}: body must be a JSON object`);
167
- const missing = POLICY_REQUIRED.filter((k) => !(k in (parsed as Record<string, unknown>)));
168
- if (missing.length > 0) throw new UsageError(`${name}: body lacks ${missing.join(", ")}`);
169
- return name === "policy-create"
170
- ? { method: "POST", path: `/v1/sites/${site}/firewall/policies`, body: JSON.stringify(parsed) }
171
- : { method: "PUT", path: `/v1/sites/${site}/firewall/policies/${confirmed[1]}`, body: JSON.stringify(parsed) };
186
+ if (typeof parsed !== "object" || parsed === null) throw new UsageError("body must be a JSON object or array");
187
+ return { method: method as WriteMethod, path, body: JSON.stringify(parsed) };
172
188
  }
173
189
 
174
- async function unifi(config: NetworkConfig, args: string[]): Promise<number> {
175
- const base = new URL(config.unifiBaseUrl);
176
- if (args[0] === "fingerprint") {
177
- const probe = await pinnedGet(new URL("/", base), null, null);
178
- printJson({ host: base.host, fingerprint256: probe.fingerprint });
179
- return 0;
190
+ /** `cloud <path>`: a Site Manager read; the connector is reached through the site commands. */
191
+ export function cloudPath(args: string[]): string {
192
+ const [path, ...extra] = args;
193
+ if (path === undefined || extra.length > 0 || !/^\/(v1|ea)\/[A-Za-z0-9/_.:?=&%-]*$/.test(path) || path.includes("..") || path.startsWith("/v1/connector/")) {
194
+ throw new UsageError("unifi cloud <path>: one path under /v1/ or /ea/, not /v1/connector/");
180
195
  }
181
- const apiKey = readSecret(SERVICE, "UNIFI_API_KEY");
182
- const write = args[0] === "policy-create" || args[0] === "policy-update" || args[0] === "policy-delete" ? policyWrite(args) : null;
183
- const url = new URL(`${base.pathname.replace(/\/$/, "")}${write ? write.path : unifiPath(args)}`, base);
184
- const response = write ? await pinnedGet(url, apiKey, config.unifiCertSha256, write.method, write.body) : await pinnedGet(url, apiKey, config.unifiCertSha256);
185
- let parsed: unknown = response.body;
196
+ return path;
197
+ }
198
+
199
+ /** Splits `<37|mira> ... [--local]`. */
200
+ export function parseSiteArgs(args: string[]): { site: Site; local: boolean; rest: string[] } {
201
+ const [site, ...rest] = args;
202
+ if (!(SITES as readonly string[]).includes(site)) throw new UsageError(`unifi <${SITES.join("|")}> ...; or unifi cloud <path>`);
203
+ return { site: site as Site, local: rest.includes("--local"), rest: rest.filter((a) => a !== "--local") };
204
+ }
205
+
206
+ function readSite(site: Site): SiteConfig {
207
+ const { prefix } = SITE_ACCESS[site];
208
+ const keys = { hostId: `${prefix}HostId`, localUrl: `${prefix}LocalUrl`, certSha256: `${prefix}CertSha256` };
209
+ const config = readConfig<Record<string, string>>(SERVICE, { [keys.hostId]: "string" as const, [keys.localUrl]: "string" as const, [keys.certSha256]: "string" as const });
210
+ if (!HOST_ID.test(config[keys.hostId])) throw new ServiceError(`network.json: ${keys.hostId} is not a Site Manager host id`);
211
+ return { hostId: config[keys.hostId], localUrl: config[keys.localUrl], certSha256: config[keys.certSha256] };
212
+ }
213
+
214
+ interface Answer {
215
+ status: number;
216
+ body: string;
217
+ }
218
+
219
+ async function cloudRequest(path: string, method: string, body?: string): Promise<Answer> {
220
+ const response = await fetch(`${CLOUD}${path}`, {
221
+ method,
222
+ headers: { Accept: "application/json", "X-API-KEY": readSecret(SERVICE, "UNIFI_API_KEY"), ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
223
+ body,
224
+ signal: AbortSignal.timeout(30_000),
225
+ }).catch((err: unknown) => {
226
+ throw new ServiceError(`api.ui.com: request failed: ${err instanceof Error ? err.message : String(err)}`);
227
+ });
228
+ return { status: response.status, body: await response.text() };
229
+ }
230
+
231
+ async function localRequest(site: Site, config: SiteConfig, path: string, method: string, body?: string): Promise<Answer> {
232
+ const base = new URL(config.localUrl);
233
+ const url = new URL(`${base.pathname.replace(/\/$/, "")}${path}`, base);
234
+ return pinnedGet(url, readSecret(SERVICE, SITE_ACCESS[site].localKey), config.certSha256, method, body);
235
+ }
236
+
237
+ /**
238
+ * One Network API call on a console: through the cloud connector unless
239
+ * `local`; a read the cloud cannot serve retries on the console itself. A
240
+ * write never retries, because the cloud may have applied it before failing.
241
+ */
242
+ async function siteRequest(site: Site, config: SiteConfig, local: boolean, path: string, method = "GET", body?: string): Promise<Answer> {
243
+ if (local) return localRequest(site, config, path, method, body);
244
+ const connector = `/v1/connector/consoles/${config.hostId}/network/integration${path}`;
245
+ let reason: string;
186
246
  try {
187
- parsed = JSON.parse(response.body);
247
+ const answer = await cloudRequest(connector, method, body);
248
+ if (method !== "GET" || !CLOUD_UNAVAILABLE.has(answer.status)) return answer;
249
+ reason = `cloud answered ${answer.status}`;
250
+ } catch (err) {
251
+ if (method !== "GET") throw new ServiceError(`${err instanceof Error ? err.message : String(err)}; the write may have been applied: read the object back before retrying with --local`);
252
+ reason = err instanceof Error ? err.message : String(err);
253
+ }
254
+ process.stderr.write(`network: ${reason}; reading from the ${site} console directly\n`);
255
+ return localRequest(site, config, path, method, body);
256
+ }
257
+
258
+ function printAnswer(answer: Answer, source: string): number {
259
+ let parsed: unknown = answer.body;
260
+ try {
261
+ parsed = JSON.parse(answer.body);
188
262
  } catch {
189
263
  /* non-JSON body stays text */
190
264
  }
191
265
  printJson(parsed);
192
- if (response.status < 200 || response.status >= 300) throw new ServiceError(`UniFi answered ${response.status}`);
266
+ if (answer.status < 200 || answer.status >= 300) throw new ServiceError(`${source} answered ${answer.status}`);
193
267
  return 0;
194
268
  }
195
269
 
270
+ async function unifi(args: string[]): Promise<number> {
271
+ if (args[0] === "cloud") return printAnswer(await cloudRequest(cloudPath(args.slice(1)), "GET"), "api.ui.com");
272
+ const { site, local, rest } = parseSiteArgs(args);
273
+ if (rest[0] === "fingerprint") {
274
+ const base = new URL(readSite(site).localUrl);
275
+ const probe = await pinnedGet(new URL("/", base), null, null);
276
+ printJson({ site, host: base.host, fingerprint256: probe.fingerprint });
277
+ return 0;
278
+ }
279
+ const write = rest[0] === "write" ? unifiWrite(rest.slice(1)) : null;
280
+ const path = write ? write.path : unifiPath(rest);
281
+ return printAnswer(await siteRequest(site, readSite(site), local, path, write?.method, write?.body), `UniFi ${site}`);
282
+ }
283
+
196
284
  export function buildPulsarRemote(args: string[]): string {
197
285
  const [name, ...rest] = args;
198
286
  const spec = name === undefined ? undefined : PULSAR_COMMANDS[name];
@@ -203,8 +291,9 @@ export function buildPulsarRemote(args: string[]): string {
203
291
  return [name, ...rest].join(" ");
204
292
  }
205
293
 
206
- async function pulsar(config: NetworkConfig, args: string[]): Promise<number> {
294
+ async function pulsar(args: string[]): Promise<number> {
207
295
  const remote = buildPulsarRemote(args);
296
+ const config = readConfig<{ pulsarHost: string; pulsarUser: string }>(SERVICE, PULSAR_SHAPE);
208
297
  const result = await sshFixed(
209
298
  {
210
299
  host: config.pulsarHost,
@@ -225,12 +314,11 @@ export async function command(args: string[]): Promise<number> {
225
314
  printRaw(HELP);
226
315
  return 0;
227
316
  }
228
- const config = readConfig<NetworkConfig>(SERVICE, SHAPE);
229
317
  switch (args[0]) {
230
318
  case "unifi":
231
- return unifi(config, args.slice(1));
319
+ return unifi(args.slice(1));
232
320
  case "pulsar":
233
- return pulsar(config, args.slice(1));
321
+ return pulsar(args.slice(1));
234
322
  default:
235
323
  throw new UsageError(`unknown command: ${args[0]}\n${HELP}`);
236
324
  }
@@ -11,7 +11,7 @@ import { buildInferenceRemote, command as inferenceCommand } from "./inference/r
11
11
  import { MAX_ADD_IDS, MAX_EXCLUDE_IDS, buildTrendarrCall, interpretRun, parseImdbIds, trendarrConfig, trendarrError, trendarrWarnings, command as mediaCommand } from "./media/run.ts";
12
12
  import { ServiceError, UsageError } from "./lib/errors.ts";
13
13
  import { safeRepoPath, safeWritePath } from "./lib/repo.ts";
14
- import { POLICY_REQUIRED, buildPulsarRemote, parseQuery, policyWrite, unifiPath, command as networkCommand } from "./network/run.ts";
14
+ import { buildPulsarRemote, cloudPath, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
15
15
  import { buildHostRemote, needsConfirm, parseSetPairs, parseVmid, validateApiPath as validatePvePath, command as proxmoxCommand } from "./proxmox/run.ts";
16
16
  import { banLength, buildObsRemote, compactDecisions, parseGoDuration, summariseAlerts, summariseVulns, summariseWazuh, vulnEvents, wazuhEvents, command as securityCommand } from "./security/run.ts";
17
17
 
@@ -115,20 +115,34 @@ describe("network wrapper", () => {
115
115
  expect(() => unifiPath(["reboot"])).toThrow(/unknown unifi read/);
116
116
  });
117
117
 
118
- it("maps firewall policy writes to the documented endpoints", () => {
119
- const policy = { name: "x", enabled: true, action: { type: "ALLOW" }, source: { zoneId: site }, destination: { zoneId: site }, ipProtocolScope: { ipVersion: "IPV4" }, loggingEnabled: false };
120
- const body = JSON.stringify(policy);
121
- expect(policyWrite(["policy-create", site, body])).toEqual({ method: "POST", path: `/v1/sites/${site}/firewall/policies`, body });
122
- expect(policyWrite(["policy-update", site, site, body])).toEqual({ method: "PUT", path: `/v1/sites/${site}/firewall/policies/${site}`, body });
123
- expect(policyWrite(["policy-delete", site, site, "--confirm"])).toEqual({ method: "DELETE", path: `/v1/sites/${site}/firewall/policies/${site}` });
124
- expect(() => policyWrite(["policy-delete", site, site])).toThrow(/--confirm/);
125
- expect(() => policyWrite(["policy-create", "default", body])).toThrow(/UUID/);
126
- expect(() => policyWrite(["policy-create", site, "{"])).toThrow(/JSON/);
127
- expect(() => policyWrite(["policy-create", site, JSON.stringify({ name: "x" })])).toThrow(/lacks/);
128
- expect(() => policyWrite(["policy-update", site, "nope", body])).toThrow(UsageError);
118
+ it("maps writes under one site and checks the body", () => {
119
+ const body = JSON.stringify({ name: "x", enabled: true });
120
+ expect(unifiWrite(["POST", `/v1/sites/${site}/firewall/policies`, body])).toEqual({ method: "POST", path: `/v1/sites/${site}/firewall/policies`, body });
121
+ expect(unifiWrite(["PUT", `/v1/sites/${site}/firewall/policies/ordering`, "[1]"]).body).toBe("[1]");
122
+ expect(unifiWrite(["DELETE", `/v1/sites/${site}/acl-rules/${site}`])).toEqual({ method: "DELETE", path: `/v1/sites/${site}/acl-rules/${site}` });
123
+ expect(() => unifiWrite(["DELETE", `/v1/sites/${site}/acl-rules/${site}`, body])).toThrow(/no body/);
124
+ expect(() => unifiWrite(["POST", `/v1/sites/${site}/networks`])).toThrow(/JSON body/);
125
+ expect(() => unifiWrite(["POST", `/v1/sites/${site}/networks`, "{"])).toThrow(/JSON/);
126
+ expect(() => unifiWrite(["POST", `/v1/sites/${site}/networks`, "3"])).toThrow(/object or array/);
127
+ expect(() => unifiWrite(["GET", `/v1/sites/${site}/networks`])).toThrow(UsageError);
128
+ expect(() => unifiWrite(["POST", "/v1/sites/default/networks", body])).toThrow(/siteId/);
129
+ expect(() => unifiWrite(["POST", `/v1/sites/${site}/../x`, body])).toThrow(/traversal/);
130
+ expect(() => unifiWrite(["POST", `/v1/sites/${site}/networks?x=1`, body])).toThrow(UsageError);
131
+ expect(() => unifiWrite(["POST", `/v1/sites/${site}/networks`, body, "extra"])).toThrow(/one JSON body/);
129
132
  expect(unifiPath(["firewall-zones", site])).toBe(`/v1/sites/${site}/firewall/zones`);
130
133
  expect(unifiPath(["firewall-policy", site, site])).toBe(`/v1/sites/${site}/firewall/policies/${site}`);
131
- expect(POLICY_REQUIRED).toContain("ipProtocolScope");
134
+ });
135
+
136
+ it("picks the console and the cloud reads", () => {
137
+ expect(parseSiteArgs(["37", "sites"])).toEqual({ site: "37", local: false, rest: ["sites"] });
138
+ expect(parseSiteArgs(["mira", "devices", site, "--local"])).toEqual({ site: "mira", local: true, rest: ["devices", site] });
139
+ expect(() => parseSiteArgs(["sites"])).toThrow(/37\|mira/);
140
+ expect(cloudPath(["/v1/hosts"])).toBe("/v1/hosts");
141
+ expect(cloudPath(["/v1/devices?pageSize=100&nextToken=AB%3A1"])).toBe("/v1/devices?pageSize=100&nextToken=AB%3A1");
142
+ expect(cloudPath(["/ea/sites"])).toBe("/ea/sites");
143
+ expect(() => cloudPath(["/v1/connector/consoles/x/network/integration/v1/sites"])).toThrow(/connector/);
144
+ expect(() => cloudPath(["/v1/../x"])).toThrow(UsageError);
145
+ expect(() => cloudPath(["/proxy/network"])).toThrow(UsageError);
132
146
  });
133
147
 
134
148
  it("maps pulsar commands to fixed remote strings", () => {
@@ -142,7 +156,7 @@ describe("network wrapper", () => {
142
156
  it("prints help without touching config", async () => {
143
157
  const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
144
158
  expect(await networkCommand(["help"])).toBe(0);
145
- expect(String(write.mock.calls[0][0])).toContain("unifi fingerprint");
159
+ expect(String(write.mock.calls[0][0])).toContain("unifi <37|mira> fingerprint");
146
160
  write.mockRestore();
147
161
  });
148
162
  });
@@ -575,7 +589,8 @@ describe("wrapper config errors", () => {
575
589
 
576
590
  it("fails clearly when the config file is absent", async () => {
577
591
  await expect(arcaneCommand(["projects", "list"])).rejects.toThrow(/cannot read .*arcane\.json/);
578
- await expect(networkCommand(["unifi", "sites"])).rejects.toThrow(/network\.json/);
592
+ await expect(networkCommand(["unifi", "37", "sites"])).rejects.toThrow(/network\.json/);
593
+ await expect(networkCommand(["pulsar", "radius-status"])).rejects.toThrow(/network\.json/);
579
594
  await expect(dnsCommand(["technitium", "primary", "zones"])).rejects.toThrow(/dns\.json/);
580
595
  await expect(edgeCommand(["probe"])).rejects.toThrow(/edge\.json/);
581
596
  await expect(securityCommand(["attention"])).rejects.toThrow(/security\.json/);