@astrofoundry/pi-astro 0.40.29 → 0.40.31

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.
@@ -22,6 +22,7 @@ describe("approvals", () => {
22
22
  expect(isRisky("network", ["unifi", "mira", "nat-write", "POST", "{}"])).toBe(true);
23
23
  expect(isRisky("network", ["unifi", "37", "nat"])).toBe(false);
24
24
  expect(isRisky("network", ["unifi", "mira", "app-policy-delete", "0123456789abcdef01234567"])).toBe(true);
25
+ expect(isRisky("network", ["unifi", "mira", "client-fixed-ip", "0123456789abcdef01234567", "{}"])).toBe(true);
25
26
  expect(isRisky("network", ["unifi", "mira", "device-network", "0123456789abcdef01234567", "{}"])).toBe(true);
26
27
  expect(isRisky("network", ["unifi", "mira", "app-get", "/api/s/default/stat/device"])).toBe(false);
27
28
  expect(isRisky("arcane", ["projects", "list"])).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|device-network|app-policy-delete)\b/],
36
+ network: [/^unifi\s+\S+\s+(write|nat-write|device-network|app-policy-delete|client-fixed-ip)\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.29",
3
+ "version": "0.40.31",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -8,7 +8,7 @@ description: How the network specialist reads and changes the UniFi consoles of
8
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` (Cortex reaches its console at `10.1.60.1` over Site Magic): the second location, `10.1.0.0/16`, with the same zone model as 37 (Management 10, Services 40, Trusted 60, IoT 70, Guest 80). 37 and Mira are run as one network.
11
+ - `mira` (Cortex reaches its console at `10.1.60.1` over Site Magic): the second location, `10.1.0.0/16`, with the same zone model as 37 (Management 10, Services 40, Storage 50, Trusted 60, IoT 70, Guest 80). 37 and Mira are run as one network.
12
12
 
13
13
  The consoles are joined by Site Magic (SD-WAN). Never call either site "home". The `network` tool has three families.
14
14
 
@@ -83,17 +83,20 @@ The cloud connector forwards any path under `/proxy/` of a console, and the acco
83
83
  Behavior learned on the live consoles:
84
84
 
85
85
  - A GET omits an optional field that is unset. A missing field is not proof that the API lacks it: `ipv4Configuration.dhcpConfiguration.dnsServerIpAddressesOverride` (the DHCP DNS servers) appears only once set. Check the schema.
86
+ - Creating a network needs its `zoneId`: create a new zone first with `networkIds: []`, then the network in it (Mira Storage, 2026-11-01).
86
87
  - PUT replaces the whole object: send the full GET body without `id`, `metadata`, `default`, and `index`. To set DHCP DNS on a network, PUT it with `dnsServerIpAddressesOverride: ["<dns1>", "<dns2>"]`; remove the field to return to automatic.
87
88
  - `like` uses `*` for any characters and `.` for one character; escape them with `\`. SQL `%` matches nothing and still returns `totalCount: 0` without an error.
88
89
  - Lists return 25 items by default. 37 has about 390 firewall policies, mostly `SYSTEM_DEFINED` zone defaults and `DERIVED` return rules: page with `--offset`, or filter `metadata.origin.eq('USER_DEFINED')` (69 on 37 on 2026-10-31).
89
90
  - Protocol filters: one protocol is `{"type":"NAMED_PROTOCOL","protocol":{"name":"TCP"},"matchOpposite":false}`; TCP and UDP together is `{"type":"PRESET","preset":{"name":"TCP_UDP"}}` with no `matchOpposite`. Omit `protocolFilter` to match every protocol.
90
91
  - 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
- - 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
+ - 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, DMZ, and Storage; Mira shares Trusted, IoT, Services, Management, and Storage.
92
93
 
93
94
  ## `unifi <37|mira> app-get <path>` and `unifi <37|mira> device-network <deviceId> <json>`
94
95
 
95
96
  `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
 
98
+ `client-fixed-ip <clientId> <json>` sets a DHCP reservation: a PUT of `/api/s/default/rest/user/<clientId>` whose body may hold only `use_fixedip`, `fixed_ip`, and `network_id` (the 24-hex network id from `rest/networkconf`). Find the client id with `app-get /api/s/default/rest/user`; a device keeps its old lease until it renews or reconnects.
99
+
97
100
  `app-policy-delete <policyId>` deletes a firewall policy that the official API lists with `id: null`, such as rules converted from the old firewall (Mira's `BLOCK INTERNET` rows on 2026-10-31). Find its 24-hex `_id` with `app-get /v2/api/site/default/firewall-policies`; every other policy change goes through `write`.
98
101
 
99
102
  `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.
@@ -80,6 +80,8 @@ ${Object.values(UNIFI_READS)
80
80
  unifi <37|mira> app-get <path> [--local] any GET of the Network application under /api/s/default/ or /v2/api/site/default/
81
81
  unifi <37|mira> device-network <deviceId> <json> [--local]
82
82
  set a device's management network and IP (keys mgmt_network_id, config_network)
83
+ unifi <37|mira> client-fixed-ip <clientId> <json> [--local]
84
+ set or clear a client's DHCP reservation (keys use_fixedip, fixed_ip, network_id)
83
85
  unifi <37|mira> app-policy-delete <policyId> [--local]
84
86
  delete a firewall policy the official API lists without an id
85
87
  unifi <37|mira> nat [--local] the console's NAT rules (Policy Table; not in the official API)
@@ -225,6 +227,18 @@ export function deviceNetworkWrite(args: string[]): UnifiWrite {
225
227
  return { method: "PUT", path: `/api/s/default/rest/device/${id}`, body };
226
228
  }
227
229
 
230
+ const CLIENT_FIXED_IP_KEYS = new Set(["use_fixedip", "fixed_ip", "network_id"]);
231
+
232
+ /** `client-fixed-ip <clientId> <json>`: only a known client's DHCP reservation, through the application's client records. */
233
+ export function clientFixedIpWrite(args: string[]): UnifiWrite {
234
+ const [id, json, ...extra] = args;
235
+ if (id === undefined || !NAT_ID.test(id) || json === undefined || extra.length > 0) throw new UsageError("client-fixed-ip <clientId> <json>");
236
+ const body = jsonBody(json);
237
+ const keys = Object.keys(JSON.parse(body) as Record<string, unknown>);
238
+ if (keys.length === 0 || keys.some((k) => !CLIENT_FIXED_IP_KEYS.has(k))) throw new UsageError(`client-fixed-ip body keys: ${[...CLIENT_FIXED_IP_KEYS].join(", ")}`);
239
+ return { method: "PUT", path: `/api/s/default/rest/user/${id}`, body };
240
+ }
241
+
228
242
  /** `app-policy-delete <policyId>`: a firewall policy that the official API returns with `id: null` (rules converted from the old firewall). */
229
243
  export function appPolicyDelete(args: string[]): UnifiWrite {
230
244
  const [id, ...extra] = args;
@@ -339,6 +353,10 @@ async function unifi(args: string[]): Promise<number> {
339
353
  return 0;
340
354
  }
341
355
  if (rest[0] === "app-get") return printAnswer(await siteRequest(site, readSite(site), local, appGetPath(rest.slice(1)), "GET", undefined, "app"), `UniFi ${site} application`);
356
+ if (rest[0] === "client-fixed-ip") {
357
+ const call = clientFixedIpWrite(rest.slice(1));
358
+ return printAnswer(await siteRequest(site, readSite(site), local, call.path, call.method, call.body, "app"), `UniFi ${site} client`);
359
+ }
342
360
  if (rest[0] === "app-policy-delete") {
343
361
  const call = appPolicyDelete(rest.slice(1));
344
362
  return printAnswer(await siteRequest(site, readSite(site), local, call.path, call.method, undefined, "app"), `UniFi ${site} policy`);
@@ -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 { appGetPath, appPolicyDelete, buildPulsarRemote, cloudPath, deviceNetworkWrite, NAT_PATH, natWrite, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
14
+ import { appGetPath, appPolicyDelete, clientFixedIpWrite, buildPulsarRemote, cloudPath, deviceNetworkWrite, NAT_PATH, natWrite, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
15
15
  import { buildHostRemote, splitHost, 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
 
@@ -120,6 +120,9 @@ describe("network wrapper", () => {
120
120
  expect(appGetPath(["/api/s/default/stat/device"])).toBe("/api/s/default/stat/device");
121
121
  expect(appPolicyDelete(["0123456789abcdef01234567"])).toEqual({ method: "DELETE", path: "/v2/api/site/default/firewall-policies/0123456789abcdef01234567" });
122
122
  expect(() => appPolicyDelete(["611cef69-df2e-4498-9845-8685daee84f3"])).toThrow(UsageError);
123
+ const fixed = JSON.stringify({ use_fixedip: true, fixed_ip: "10.1.50.50", network_id: "0123456789abcdef01234567" });
124
+ expect(clientFixedIpWrite(["0123456789abcdef01234567", fixed])).toEqual({ method: "PUT", path: "/api/s/default/rest/user/0123456789abcdef01234567", body: fixed });
125
+ expect(() => clientFixedIpWrite(["0123456789abcdef01234567", JSON.stringify({ name: "x" })])).toThrow(/body keys/);
123
126
  expect(appGetPath(["/v2/api/site/default/nat"])).toBe("/v2/api/site/default/nat");
124
127
  expect(() => appGetPath(["/api/s/other/stat/device"])).toThrow(UsageError);
125
128
  expect(() => appGetPath(["/api/s/default/../../x"])).toThrow(UsageError);