@astrofoundry/pi-astro 0.40.21 → 0.40.23

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.
@@ -19,6 +19,8 @@ describe("approvals", () => {
19
19
  expect(isRisky("network", ["unifi", "mira", "networks", "x"])).toBe(false);
20
20
  expect(isRisky("network", ["unifi", "37", "write", "DELETE", "/v1/sites/x/acl-rules/y"])).toBe(true);
21
21
  expect(isRisky("network", ["unifi", "mira", "--local", "write", "PUT", "/v1/sites/x/networks/y", "{}"])).toBe(true);
22
+ expect(isRisky("network", ["unifi", "mira", "nat-write", "POST", "{}"])).toBe(true);
23
+ expect(isRisky("network", ["unifi", "37", "nat"])).toBe(false);
22
24
  expect(isRisky("arcane", ["projects", "list"])).toBe(false);
23
25
  expect(isRisky("arcane", ["projects", "redeploy", "mealie"])).toBe(false);
24
26
  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\b/],
36
+ network: [/^unifi\s+\S+\s+(write|nat-write)\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.21",
3
+ "version": "0.40.23",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -76,7 +76,9 @@ Both consoles run Network `10.6.109`. The console serves no `openapi.json` (404)
76
76
  | `clients` | GET | `clients/{id}/actions`: `AUTHORIZE_GUEST_ACCESS`, `UNAUTHORIZE_GUEST_ACCESS` |
77
77
  | `wans`, `vpn/servers`, `vpn/site-to-site-tunnels`, `radius/profiles`, `switching/*`, `device-tags` | GET | read only |
78
78
 
79
- No endpoint exists for these, so they stay owner tasks in the UniFi UI: Site Magic (read it with `unifi cloud`), switch port profiles and per-port settings (only power cycle), device settings (name, LEDs, uplink, management VLAN), client fixed IPs and names, port forwarding and NAT, static and traffic routes, VPN server and Teleport settings, admins, and console settings.
79
+ The official API has no endpoint for these: Site Magic (read it with `unifi cloud`), NAT, switch port profiles and per-port settings (only power cycle), device settings (name, LEDs, uplink, management VLAN), client fixed IPs and names, port forwarding, static and traffic routes, VPN server and Teleport settings, admins, and console settings.
80
+
81
+ The cloud connector forwards any path under `/proxy/` of a console, and the account key `UNIFI_API_KEY` is accepted on the Network application's own paths: `unifi <site> nat` proves it for `/proxy/network/v2/api/site/default/nat` (2026-10-31). So "the official API lacks it" is not "impossible": before reporting a change as UI only, find the application path that the UniFi UI uses for it and add a narrow wrapper command, as `nat` was added. Only `nat` is wired today; the other items above stay owner tasks until a command exists. The local console keys were not tested on application paths. Never drive a browser for these changes.
80
82
 
81
83
  Behavior learned on the live consoles:
82
84
 
@@ -88,6 +90,31 @@ Behavior learned on the live consoles:
88
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).
89
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.
90
92
 
93
+ ## `unifi <37|mira> nat` and `unifi <37|mira> nat-write ...`
94
+
95
+ 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.
96
+
97
+ | Command | Effect |
98
+ |---|---|
99
+ | `nat` | list the rules |
100
+ | `nat-write POST <json>` | create a rule |
101
+ | `nat-write PUT <ruleId> <json>` | replace a rule (send the full object) |
102
+ | `nat-write DELETE <ruleId>` | delete a rule |
103
+
104
+ Rule ids and network ids here are the application's 24-hex ids, not the official API's UUIDs. Take a network's id from an existing rule's `in_interface`, or from `unifi cloud /v1/sd-wan-configs/<id>` (`networkId`). Every rule needs a unique `rule_index`: set it explicitly, lowest first; a second rule without one fails with `duplicate rule_index`. An `exclude: true` rule at a lower index exempts its match from the rules after it.
105
+
106
+ Both sites redirect IoT DNS with two DNAT rules on the IoT network (`in_interface` and `source_filter.network_conf_id`), TCP and UDP port 53:
107
+
108
+ | Site | Index 0 (`exclude: true`) | Index 1 |
109
+ |---|---|---|
110
+ | 37 | `IoT DNS redirect - ex. secondary`: leaves `10.0.40.54:53` alone | `IoT DNS redirect`: every other port-53 query to `10.0.40.53` |
111
+ | mira | `IoT DNS redirect - ex. secondary`: leaves `10.0.40.54:53` alone | `IoT DNS redirect`: every other port-53 query to `10.1.40.53` |
112
+
113
+ ```json
114
+ { "args": ["unifi", "37", "nat"] }
115
+ { "args": ["unifi", "mira", "nat-write", "POST", "{\"type\":\"DNAT\",\"description\":\"IoT DNS redirect\",\"rule_index\":1,...}"] }
116
+ ```
117
+
91
118
  ## `unifi cloud <path>`
92
119
 
93
120
  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.
@@ -77,6 +77,8 @@ ${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> nat [--local] the console's NAT rules (Policy Table; not in the official API)
81
+ unifi <37|mira> nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId> [--local]
80
82
  unifi <37|mira> fingerprint the local console's certificate fingerprint (for the pin)
81
83
  unifi cloud <path> any GET of the Site Manager API (/v1/ or /ea/, not /v1/connector/)
82
84
  pulsar <command> [args] fixed operations through a forced-command SSH key
@@ -166,6 +168,17 @@ export interface UnifiWrite {
166
168
  body?: string;
167
169
  }
168
170
 
171
+ function jsonBody(json: string): string {
172
+ let parsed: unknown;
173
+ try {
174
+ parsed = JSON.parse(json);
175
+ } catch {
176
+ throw new UsageError("body must be JSON");
177
+ }
178
+ if (typeof parsed !== "object" || parsed === null) throw new UsageError("body must be a JSON object or array");
179
+ return JSON.stringify(parsed);
180
+ }
181
+
169
182
  /** `write <method> <path> [json]`: any write under one site of the Network API; the console validates the body. */
170
183
  export function unifiWrite(args: string[]): UnifiWrite {
171
184
  const [method, path, json, ...extra] = args;
@@ -177,14 +190,23 @@ export function unifiWrite(args: string[]): UnifiWrite {
177
190
  return { method, path };
178
191
  }
179
192
  if (json === undefined) throw new UsageError(`${method} needs a JSON body`);
180
- let parsed: unknown;
181
- try {
182
- parsed = JSON.parse(json);
183
- } catch {
184
- throw new UsageError("body must be JSON");
193
+ return { method: method as WriteMethod, path, body: jsonBody(json) };
194
+ }
195
+
196
+ /** The Network application's own NAT rules (Policy Table, type NAT). The official API has no NAT endpoint. */
197
+ export const NAT_PATH = "/v2/api/site/default/nat";
198
+ const NAT_ID = /^[0-9a-f]{24}$/;
199
+
200
+ /** `nat-write POST <json>`, `nat-write PUT <ruleId> <json>`, or `nat-write DELETE <ruleId>`. */
201
+ export function natWrite(args: string[]): UnifiWrite {
202
+ const [method, first, second, ...extra] = args;
203
+ if (method === "POST" && first !== undefined && second === undefined) return { method, path: NAT_PATH, body: jsonBody(first) };
204
+ if ((method === "PUT" || method === "DELETE") && first !== undefined && NAT_ID.test(first) && extra.length === 0) {
205
+ const path = `${NAT_PATH}/${first}`;
206
+ if (method === "DELETE" && second === undefined) return { method, path };
207
+ if (method === "PUT" && second !== undefined) return { method, path, body: jsonBody(second) };
185
208
  }
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) };
209
+ throw new UsageError("nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId>");
188
210
  }
189
211
 
190
212
  /** `cloud <path>`: a Site Manager read; the connector is reached through the site commands. */
@@ -228,9 +250,13 @@ async function cloudRequest(path: string, method: string, body?: string): Promis
228
250
  return { status: response.status, body: await response.text() };
229
251
  }
230
252
 
231
- async function localRequest(site: Site, config: SiteConfig, path: string, method: string, body?: string): Promise<Answer> {
253
+ /** `integration` is the official API under /proxy/network/integration; `app` is the Network application's own paths under /proxy/network. */
254
+ type Api = "integration" | "app";
255
+
256
+ async function localRequest(site: Site, config: SiteConfig, path: string, method: string, body: string | undefined, api: Api): Promise<Answer> {
232
257
  const base = new URL(config.localUrl);
233
- const url = new URL(`${base.pathname.replace(/\/$/, "")}${path}`, base);
258
+ const prefix = base.pathname.replace(/\/$/, "");
259
+ const url = new URL(`${api === "app" ? prefix.replace(/\/integration$/, "") : prefix}${path}`, base);
234
260
  return pinnedGet(url, readSecret(SERVICE, SITE_ACCESS[site].localKey), config.certSha256, method, body);
235
261
  }
236
262
 
@@ -239,9 +265,9 @@ async function localRequest(site: Site, config: SiteConfig, path: string, method
239
265
  * `local`; a read the cloud cannot serve retries on the console itself. A
240
266
  * write never retries, because the cloud may have applied it before failing.
241
267
  */
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}`;
268
+ async function siteRequest(site: Site, config: SiteConfig, local: boolean, path: string, method = "GET", body?: string, api: Api = "integration"): Promise<Answer> {
269
+ if (local) return localRequest(site, config, path, method, body, api);
270
+ const connector = `/v1/connector/consoles/${config.hostId}/network${api === "integration" ? "/integration" : ""}${path}`;
245
271
  let reason: string;
246
272
  try {
247
273
  const answer = await cloudRequest(connector, method, body);
@@ -252,7 +278,7 @@ async function siteRequest(site: Site, config: SiteConfig, local: boolean, path:
252
278
  reason = err instanceof Error ? err.message : String(err);
253
279
  }
254
280
  process.stderr.write(`network: ${reason}; reading from the ${site} console directly\n`);
255
- return localRequest(site, config, path, method, body);
281
+ return localRequest(site, config, path, method, body, api);
256
282
  }
257
283
 
258
284
  function printAnswer(answer: Answer, source: string): number {
@@ -277,6 +303,11 @@ async function unifi(args: string[]): Promise<number> {
277
303
  printJson({ site, host: base.host, fingerprint256: probe.fingerprint });
278
304
  return 0;
279
305
  }
306
+ if (rest[0] === "nat" || rest[0] === "nat-write") {
307
+ if (rest[0] === "nat" && rest.length > 1) throw new UsageError("unifi <37|mira> nat takes no arguments");
308
+ const call = rest[0] === "nat" ? { method: "GET", path: NAT_PATH, body: undefined } : natWrite(rest.slice(1));
309
+ return printAnswer(await siteRequest(site, readSite(site), local, call.path, call.method, call.body, "app"), `UniFi ${site} NAT`);
310
+ }
280
311
  const write = rest[0] === "write" ? unifiWrite(rest.slice(1)) : null;
281
312
  const path = write ? write.path : unifiPath(rest);
282
313
  return printAnswer(await siteRequest(site, readSite(site), local, path, write?.method, write?.body), `UniFi ${site}`);
@@ -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, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
14
+ import { buildPulsarRemote, cloudPath, 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,18 @@ describe("network wrapper", () => {
115
115
  expect(() => unifiPath(["reboot"])).toThrow(/unknown unifi read/);
116
116
  });
117
117
 
118
+ it("maps NAT rule writes to the application path", () => {
119
+ const id = "0123456789abcdef01234567";
120
+ expect(natWrite(["POST", '{"type":"DNAT"}'])).toEqual({ method: "POST", path: NAT_PATH, body: '{"type":"DNAT"}' });
121
+ expect(natWrite(["PUT", id, "{}"])).toEqual({ method: "PUT", path: `${NAT_PATH}/${id}`, body: "{}" });
122
+ expect(natWrite(["DELETE", id])).toEqual({ method: "DELETE", path: `${NAT_PATH}/${id}` });
123
+ expect(() => natWrite(["DELETE", id, "{}"])).toThrow(UsageError);
124
+ expect(() => natWrite(["PUT", "not-an-id", "{}"])).toThrow(UsageError);
125
+ expect(() => natWrite(["POST"])).toThrow(UsageError);
126
+ expect(() => natWrite(["POST", "{"])).toThrow(/JSON/);
127
+ expect(() => natWrite(["PATCH", id, "{}"])).toThrow(UsageError);
128
+ });
129
+
118
130
  it("maps writes under one site and checks the body", () => {
119
131
  const body = JSON.stringify({ name: "x", enabled: true });
120
132
  expect(unifiWrite(["POST", `/v1/sites/${site}/firewall/policies`, body])).toEqual({ method: "POST", path: `/v1/sites/${site}/firewall/policies`, body });