@astrofoundry/pi-astro 0.40.10 → 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 +1 -1
- package/agents/network.md +6 -5
- package/extensions/specialist-gate/approvals.test.ts +3 -0
- package/extensions/specialist-gate/index.ts +2 -1
- package/package.json +1 -1
- package/skills/network/SKILL.md +32 -18
- package/specialists/AGENTS.md +2 -2
- package/specialists/README.md +8 -7
- package/specialists/network/run.ts +144 -56
- package/specialists/wrappers.test.ts +30 -15
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
|
|
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
|
|
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
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
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
|
-
|
|
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
package/skills/network/SKILL.md
CHANGED
|
@@ -1,15 +1,24 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: network
|
|
3
|
-
description: How the network specialist reads UniFi
|
|
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
|
|
8
|
+
Two UniFi sites, each with its own console:
|
|
9
9
|
|
|
10
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
45
|
+
## `unifi <37|mira> write <POST|PUT|PATCH|DELETE> <path> [json] [--local]`
|
|
37
46
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
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", "
|
|
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
|
-
|
|
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.
|
package/specialists/AGENTS.md
CHANGED
|
@@ -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`
|
|
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.
|
|
@@ -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
|
|
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).
|
package/specialists/README.md
CHANGED
|
@@ -6,7 +6,7 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
|
|
|
6
6
|
|---|---|---|
|
|
7
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
-
{ "
|
|
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
|
|
|
@@ -10,20 +10,38 @@ import { sshFixed } from "../lib/ssh.ts";
|
|
|
10
10
|
|
|
11
11
|
const SERVICE = "network";
|
|
12
12
|
|
|
13
|
-
|
|
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
|
-
|
|
30
|
+
localUrl: string;
|
|
16
31
|
/** SHA-256 fingerprint of the console certificate, colon-separated uppercase hex. */
|
|
17
|
-
|
|
18
|
-
pulsarHost: string;
|
|
19
|
-
pulsarUser: string;
|
|
32
|
+
certSha256: string;
|
|
20
33
|
}
|
|
21
34
|
|
|
22
|
-
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 (
|
|
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>
|
|
60
|
-
unifi
|
|
61
|
-
|
|
62
|
-
unifi
|
|
63
|
-
unifi
|
|
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
|
-
|
|
138
|
-
|
|
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
|
|
141
|
-
method:
|
|
163
|
+
export interface UnifiWrite {
|
|
164
|
+
method: WriteMethod;
|
|
142
165
|
path: string;
|
|
143
166
|
body?: string;
|
|
144
167
|
}
|
|
145
168
|
|
|
146
|
-
/**
|
|
147
|
-
export function
|
|
148
|
-
const [
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
if (
|
|
152
|
-
if (
|
|
153
|
-
if (
|
|
154
|
-
return { method
|
|
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(
|
|
182
|
+
parsed = JSON.parse(json);
|
|
163
183
|
} catch {
|
|
164
|
-
throw new UsageError(
|
|
184
|
+
throw new UsageError("body must be JSON");
|
|
165
185
|
}
|
|
166
|
-
if (typeof parsed !== "object" || parsed === null
|
|
167
|
-
|
|
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
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
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
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
|
|
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 (
|
|
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(
|
|
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(
|
|
319
|
+
return unifi(args.slice(1));
|
|
232
320
|
case "pulsar":
|
|
233
|
-
return pulsar(
|
|
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 {
|
|
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
|
|
119
|
-
const
|
|
120
|
-
|
|
121
|
-
expect(
|
|
122
|
-
expect(
|
|
123
|
-
expect(
|
|
124
|
-
expect(() =>
|
|
125
|
-
expect(() =>
|
|
126
|
-
expect(() =>
|
|
127
|
-
expect(() =>
|
|
128
|
-
expect(() =>
|
|
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
|
-
|
|
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/);
|