@astrofoundry/pi-astro 0.40.23 → 0.40.25

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.
@@ -21,6 +21,8 @@ describe("approvals", () => {
21
21
  expect(isRisky("network", ["unifi", "mira", "--local", "write", "PUT", "/v1/sites/x/networks/y", "{}"])).toBe(true);
22
22
  expect(isRisky("network", ["unifi", "mira", "nat-write", "POST", "{}"])).toBe(true);
23
23
  expect(isRisky("network", ["unifi", "37", "nat"])).toBe(false);
24
+ expect(isRisky("network", ["unifi", "mira", "device-network", "0123456789abcdef01234567", "{}"])).toBe(true);
25
+ expect(isRisky("network", ["unifi", "mira", "app-get", "/api/s/default/stat/device"])).toBe(false);
24
26
  expect(isRisky("arcane", ["projects", "list"])).toBe(false);
25
27
  expect(isRisky("arcane", ["projects", "redeploy", "mealie"])).toBe(false);
26
28
  expect(isRisky("arcane", ["projects", "upgrade", "media", "sonarr", "--yes"])).toBe(false);
@@ -33,7 +33,7 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
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|nat-write)\b/],
36
+ network: [/^unifi\s+\S+\s+(write|nat-write|device-network)\b/],
37
37
  dns: [
38
38
  /^technitium\s+primary\s+(zone-create|zone-catalog|zone-delete|record-add|record-update|record-delete|cluster-init|cluster-delete|cluster-remove|server-domain)\b/,
39
39
  /^technitium\s+node\s+\S+\s+(server-domain|stale-zone-delete)\b/,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.23",
3
+ "version": "0.40.25",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -90,6 +90,18 @@ Behavior learned on the live consoles:
90
90
  - A policy has exactly one source zone and one destination zone; several destination zones need one policy each. The `SYSTEM_DEFINED` policies show each zone pair's default (on 37: Vpn to Dmz allows, Vpn to Services blocks).
91
91
  - Traffic between 37 and Mira crosses two firewalls: `<zone> to Vpn` on the sending site and `Vpn to <zone>` on the receiving site. A subnet routes only if Site Magic shares it: `unifi cloud /v1/sd-wan-configs/<id>` lists the shared networks per site. 37 shares Services, Management, Trusted, and DMZ; Mira shares Trusted, IoT, Services, and Management.
92
92
 
93
+ ## `unifi <37|mira> app-get <path>` and `unifi <37|mira> device-network <deviceId> <json>`
94
+
95
+ `app-get` reads any path of the Network application's own API under `/api/s/default/` or `/v2/api/site/default/`, through the same connector and key. Use it to find the fields a change needs before adding a narrow write command. Useful reads: `/api/s/default/stat/device` (devices with `mgmt_network_id`, `config_network`, `port_table`, `port_overrides`, `uplink`), `/api/s/default/stat/sta` (clients with `ap_mac`, `sw_mac`, `sw_port`), `/api/s/default/rest/networkconf` (networks with their 24-hex ids, VLAN, subnet, DHCP range).
96
+
97
+ `device-network` changes only a device's management network and address: a PUT of `/api/s/default/rest/device/<deviceId>` whose body may hold just `mgmt_network_id` and `config_network`. Both sites use the same layout: the uplink port stays native Default with all VLANs tagged, and each device sits on Management with a static address and the local DNS nodes.
98
+
99
+ ```json
100
+ { "args": ["unifi", "mira", "device-network", "<24-hex deviceId>", "{\"mgmt_network_id\":\"<Management networkconf id>\",\"config_network\":{\"type\":\"static\",\"ip\":\"10.1.10.3\",\"netmask\":\"255.255.255.0\",\"gateway\":\"10.1.10.1\",\"dns1\":\"10.1.40.53\",\"dns2\":\"10.0.40.54\",\"dnssuffix\":\"\",\"bonding_enabled\":false}}"] }
101
+ ```
102
+
103
+ Change one device at a time, downstream devices and the AP serving the operator last, and wait until `devices` shows it `ONLINE` at the new address before the next. An AP takes the Management network and the static address in one step. A switch does not: on 2026-10-31 the Flex XG lost the controller after getting both at once, and reverted to its previous settings by itself about 10 minutes later. For a switch, first send `mgmt_network_id` with `config_network: {"type":"dhcp"}` and wait for `ONLINE`; then send the static address. If it stays in provisioning (`state` 5, `last_config_applied_successfully: false`), restart it. The official `RESTART` device action works only on an `ONLINE` device. A switch powered by PoE can be restarted from its upstream port: `write POST /v1/sites/<siteId>/devices/<upstreamId>/interfaces/ports/<n>/actions '{"action":"POWER_CYCLE"}'`. A restart interrupts everything behind the switch; at Mira that is SPACE-X and technitium3 on Flex XG port 2.
104
+
93
105
  ## `unifi <37|mira> nat` and `unifi <37|mira> nat-write ...`
94
106
 
95
107
  The gateway's NAT rules (Policy Table, type NAT), which the official API lacks. The wrapper calls the Network application's own path `/proxy/network/v2/api/site/default/nat` through the cloud connector with the account key `UNIFI_API_KEY`; `--local` uses the console's local key instead.
@@ -77,6 +77,9 @@ ${Object.values(UNIFI_READS)
77
77
  unifi <37|mira> get <path> [--local] any GET under /v1/ of the console's Network API
78
78
  unifi <37|mira> write <POST|PUT|PATCH|DELETE> <path> [json] [--local]
79
79
  any write under /v1/sites/<siteId>/ (JSON body except for DELETE)
80
+ unifi <37|mira> app-get <path> [--local] any GET of the Network application under /api/s/default/ or /v2/api/site/default/
81
+ unifi <37|mira> device-network <deviceId> <json> [--local]
82
+ set a device's management network and IP (keys mgmt_network_id, config_network)
80
83
  unifi <37|mira> nat [--local] the console's NAT rules (Policy Table; not in the official API)
81
84
  unifi <37|mira> nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId> [--local]
82
85
  unifi <37|mira> fingerprint the local console's certificate fingerprint (for the pin)
@@ -197,6 +200,29 @@ export function unifiWrite(args: string[]): UnifiWrite {
197
200
  export const NAT_PATH = "/v2/api/site/default/nat";
198
201
  const NAT_ID = /^[0-9a-f]{24}$/;
199
202
 
203
+ const APP_READ = /^\/(api\/s\/default|v2\/api\/site\/default)\/[A-Za-z0-9/_.-]+$/;
204
+
205
+ /** `app-get <path>`: a read of the Network application's own API, to find the fields a wrapper command needs. */
206
+ export function appGetPath(args: string[]): string {
207
+ const [path, ...extra] = args;
208
+ if (path === undefined || extra.length > 0 || !APP_READ.test(path) || path.split("/").includes("..")) {
209
+ throw new UsageError("app-get <path>: one path under /api/s/default/ or /v2/api/site/default/");
210
+ }
211
+ return path;
212
+ }
213
+
214
+ const DEVICE_NETWORK_KEYS = new Set(["mgmt_network_id", "config_network"]);
215
+
216
+ /** `device-network <deviceId> <json>`: only a device's management network and IP configuration. */
217
+ export function deviceNetworkWrite(args: string[]): UnifiWrite {
218
+ const [id, json, ...extra] = args;
219
+ if (id === undefined || !NAT_ID.test(id) || json === undefined || extra.length > 0) throw new UsageError("device-network <deviceId> <json>");
220
+ const body = jsonBody(json);
221
+ const keys = Object.keys(JSON.parse(body) as Record<string, unknown>);
222
+ if (keys.length === 0 || keys.some((k) => !DEVICE_NETWORK_KEYS.has(k))) throw new UsageError(`device-network body keys: ${[...DEVICE_NETWORK_KEYS].join(", ")}`);
223
+ return { method: "PUT", path: `/api/s/default/rest/device/${id}`, body };
224
+ }
225
+
200
226
  /** `nat-write POST <json>`, `nat-write PUT <ruleId> <json>`, or `nat-write DELETE <ruleId>`. */
201
227
  export function natWrite(args: string[]): UnifiWrite {
202
228
  const [method, first, second, ...extra] = args;
@@ -303,6 +329,11 @@ async function unifi(args: string[]): Promise<number> {
303
329
  printJson({ site, host: base.host, fingerprint256: probe.fingerprint });
304
330
  return 0;
305
331
  }
332
+ if (rest[0] === "app-get") return printAnswer(await siteRequest(site, readSite(site), local, appGetPath(rest.slice(1)), "GET", undefined, "app"), `UniFi ${site} application`);
333
+ if (rest[0] === "device-network") {
334
+ const call = deviceNetworkWrite(rest.slice(1));
335
+ return printAnswer(await siteRequest(site, readSite(site), local, call.path, call.method, call.body, "app"), `UniFi ${site} device`);
336
+ }
306
337
  if (rest[0] === "nat" || rest[0] === "nat-write") {
307
338
  if (rest[0] === "nat" && rest.length > 1) throw new UsageError("unifi <37|mira> nat takes no arguments");
308
339
  const call = rest[0] === "nat" ? { method: "GET", path: NAT_PATH, body: undefined } : natWrite(rest.slice(1));
@@ -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 { buildPulsarRemote, cloudPath, NAT_PATH, natWrite, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
14
+ import { appGetPath, buildPulsarRemote, cloudPath, deviceNetworkWrite, NAT_PATH, natWrite, 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,6 +115,20 @@ describe("network wrapper", () => {
115
115
  expect(() => unifiPath(["reboot"])).toThrow(/unknown unifi read/);
116
116
  });
117
117
 
118
+ it("limits application reads and device network writes", () => {
119
+ const id = "0123456789abcdef01234567";
120
+ expect(appGetPath(["/api/s/default/stat/device"])).toBe("/api/s/default/stat/device");
121
+ expect(appGetPath(["/v2/api/site/default/nat"])).toBe("/v2/api/site/default/nat");
122
+ expect(() => appGetPath(["/api/s/other/stat/device"])).toThrow(UsageError);
123
+ expect(() => appGetPath(["/api/s/default/../../x"])).toThrow(UsageError);
124
+ expect(() => appGetPath(["/api/s/default/stat/device?x=1"])).toThrow(UsageError);
125
+ const body = JSON.stringify({ mgmt_network_id: "abc", config_network: { type: "dhcp" } });
126
+ expect(deviceNetworkWrite([id, body])).toEqual({ method: "PUT", path: `/api/s/default/rest/device/${id}`, body });
127
+ expect(() => deviceNetworkWrite([id, JSON.stringify({ name: "x" })])).toThrow(/body keys/);
128
+ expect(() => deviceNetworkWrite([id, "{}"])).toThrow(/body keys/);
129
+ expect(() => deviceNetworkWrite(["bad", body])).toThrow(UsageError);
130
+ });
131
+
118
132
  it("maps NAT rule writes to the application path", () => {
119
133
  const id = "0123456789abcdef01234567";
120
134
  expect(natWrite(["POST", '{"type":"DNAT"}'])).toEqual({ method: "POST", path: NAT_PATH, body: '{"type":"DNAT"}' });