@astrofoundry/pi-astro 0.40.32 → 0.40.33
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/package.json
CHANGED
package/skills/network/SKILL.md
CHANGED
|
@@ -97,7 +97,7 @@ Behavior learned on the live consoles:
|
|
|
97
97
|
|
|
98
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
99
|
|
|
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`;
|
|
100
|
+
`app-policy-delete <policyId> <name>` 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` and exact `name` with `app-get /v2/api/site/default/firewall-policies`; the name shows in the approval, and the wrapper deletes nothing unless the live policy carries that name. Every other policy change goes through `write`.
|
|
101
101
|
|
|
102
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.
|
|
103
103
|
|
|
@@ -116,7 +116,7 @@ The gateway's NAT rules (Policy Table, type NAT), which the official API lacks.
|
|
|
116
116
|
| `nat` | list the rules |
|
|
117
117
|
| `nat-write POST <json>` | create a rule |
|
|
118
118
|
| `nat-write PUT <ruleId> <json>` | replace a rule (send the full object) |
|
|
119
|
-
| `nat-write DELETE <ruleId>` | delete a rule |
|
|
119
|
+
| `nat-write DELETE <ruleId> <description>` | delete a rule; the wrapper deletes nothing unless the live rule carries that exact `description` |
|
|
120
120
|
|
|
121
121
|
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.
|
|
122
122
|
|
|
@@ -85,10 +85,10 @@ ${Object.values(UNIFI_READS)
|
|
|
85
85
|
set a device's management network and IP (keys mgmt_network_id, config_network)
|
|
86
86
|
unifi <37|mira> client-fixed-ip <clientId> <json> [--local]
|
|
87
87
|
set or clear a client's DHCP reservation (keys use_fixedip, fixed_ip, network_id)
|
|
88
|
-
unifi <37|mira> app-policy-delete <policyId> [--local]
|
|
88
|
+
unifi <37|mira> app-policy-delete <policyId> <name> [--local]
|
|
89
89
|
delete a firewall policy the official API lists without an id
|
|
90
90
|
unifi <37|mira> nat [--local] the console's NAT rules (Policy Table; not in the official API)
|
|
91
|
-
unifi <37|mira> nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId> [--local]
|
|
91
|
+
unifi <37|mira> nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId> <description> [--local]
|
|
92
92
|
unifi <37|mira> fingerprint the local console's certificate fingerprint (for the pin)
|
|
93
93
|
unifi cloud <path> any GET of the Site Manager API (/v1/ or /ea/, not /v1/connector/)
|
|
94
94
|
pulsar <command> [args] fixed operations through a forced-command SSH key
|
|
@@ -97,7 +97,8 @@ ${Object.entries(PULSAR_COMMANDS)
|
|
|
97
97
|
.join("\n")}
|
|
98
98
|
|
|
99
99
|
Calls go through the cloud connector; a read the cloud cannot serve retries on
|
|
100
|
-
the local console, a write never does. --local skips the cloud
|
|
100
|
+
the local console, a write never does. --local skips the cloud. A delete names
|
|
101
|
+
its target and runs only when the live object carries that name.`;
|
|
101
102
|
|
|
102
103
|
export interface Query {
|
|
103
104
|
limit?: number;
|
|
@@ -182,6 +183,8 @@ export interface UnifiWrite {
|
|
|
182
183
|
method: WriteMethod;
|
|
183
184
|
path: string;
|
|
184
185
|
body?: string;
|
|
186
|
+
/** A delete names its target, so the approval shows what goes; the live object must carry that name. */
|
|
187
|
+
target?: { id: string; name: string };
|
|
185
188
|
}
|
|
186
189
|
|
|
187
190
|
function jsonBody(json: string): string {
|
|
@@ -250,23 +253,27 @@ export function clientFixedIpWrite(args: string[]): UnifiWrite {
|
|
|
250
253
|
return { method: "PUT", path: `/api/s/default/rest/user/${id}`, body };
|
|
251
254
|
}
|
|
252
255
|
|
|
253
|
-
|
|
256
|
+
export const POLICIES_PATH = "/v2/api/site/default/firewall-policies";
|
|
257
|
+
|
|
258
|
+
/** `app-policy-delete <policyId> <name>`: a firewall policy that the official API returns with `id: null` (rules converted from the old firewall). */
|
|
254
259
|
export function appPolicyDelete(args: string[]): UnifiWrite {
|
|
255
|
-
const [id, ...extra] = args;
|
|
256
|
-
if (id === undefined || !NAT_ID.test(id) ||
|
|
257
|
-
|
|
260
|
+
const [id, name, ...extra] = args;
|
|
261
|
+
if (id === undefined || !NAT_ID.test(id) || name === undefined || name.trim() === "" || extra.length > 0) {
|
|
262
|
+
throw new UsageError(`app-policy-delete <24-hex policyId> <name>, both from app-get ${POLICIES_PATH}`);
|
|
263
|
+
}
|
|
264
|
+
return { method: "DELETE", path: `${POLICIES_PATH}/${id}`, target: { id, name } };
|
|
258
265
|
}
|
|
259
266
|
|
|
260
|
-
/** `nat-write POST <json>`, `nat-write PUT <ruleId> <json>`, or `nat-write DELETE <ruleId>`. */
|
|
267
|
+
/** `nat-write POST <json>`, `nat-write PUT <ruleId> <json>`, or `nat-write DELETE <ruleId> <description>`. */
|
|
261
268
|
export function natWrite(args: string[]): UnifiWrite {
|
|
262
269
|
const [method, first, second, ...extra] = args;
|
|
263
270
|
if (method === "POST" && first !== undefined && second === undefined) return { method, path: NAT_PATH, body: jsonBody(first) };
|
|
264
|
-
if ((method === "PUT" || method === "DELETE") && first !== undefined && NAT_ID.test(first) && extra.length === 0) {
|
|
271
|
+
if ((method === "PUT" || method === "DELETE") && first !== undefined && NAT_ID.test(first) && second !== undefined && extra.length === 0) {
|
|
265
272
|
const path = `${NAT_PATH}/${first}`;
|
|
266
|
-
if (method === "DELETE" && second
|
|
267
|
-
if (method === "PUT"
|
|
273
|
+
if (method === "DELETE" && second.trim() !== "") return { method, path, target: { id: first, name: second } };
|
|
274
|
+
if (method === "PUT") return { method, path, body: jsonBody(second) };
|
|
268
275
|
}
|
|
269
|
-
throw new UsageError("nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId>");
|
|
276
|
+
throw new UsageError("nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId> <description>");
|
|
270
277
|
}
|
|
271
278
|
|
|
272
279
|
/** `cloud <path>`: a Site Manager read; the connector is reached through the site commands. */
|
|
@@ -363,6 +370,21 @@ export function redactUnifi(value: unknown): unknown {
|
|
|
363
370
|
return value;
|
|
364
371
|
}
|
|
365
372
|
|
|
373
|
+
/** Reads the list a delete's target lives in and refuses unless the target is there under the name the caller gave. */
|
|
374
|
+
async function requireLiveName(site: Site, config: SiteConfig, local: boolean, listPath: string, field: "name" | "description", target: { id: string; name: string }): Promise<void> {
|
|
375
|
+
const answer = await siteRequest(site, config, local, listPath, "GET", undefined, "app");
|
|
376
|
+
if (answer.status < 200 || answer.status >= 300) throw new ServiceError(`reading ${listPath} answered ${answer.status}; nothing deleted`);
|
|
377
|
+
let list: unknown;
|
|
378
|
+
try {
|
|
379
|
+
list = JSON.parse(answer.body);
|
|
380
|
+
} catch {
|
|
381
|
+
throw new ServiceError(`${listPath} did not answer JSON; nothing deleted`);
|
|
382
|
+
}
|
|
383
|
+
const live = Array.isArray(list) ? (list as Record<string, unknown>[]).find((o) => o._id === target.id) : undefined;
|
|
384
|
+
if (live === undefined) throw new ServiceError(`${target.id} is not in ${listPath} on ${site}; nothing deleted`);
|
|
385
|
+
if (live[field] !== target.name) throw new ServiceError(`${target.id} has ${field} ${JSON.stringify(live[field])}, not ${JSON.stringify(target.name)}; nothing deleted`);
|
|
386
|
+
}
|
|
387
|
+
|
|
366
388
|
/** The application's classic `/api/s/` paths can report a failure as `meta.rc: "error"`. */
|
|
367
389
|
function failedMeta(parsed: unknown): boolean {
|
|
368
390
|
return (parsed as { meta?: { rc?: unknown } } | null)?.meta?.rc === "error";
|
|
@@ -399,16 +421,23 @@ async function unifi(args: string[]): Promise<number> {
|
|
|
399
421
|
}
|
|
400
422
|
if (rest[0] === "app-policy-delete") {
|
|
401
423
|
const call = appPolicyDelete(rest.slice(1));
|
|
402
|
-
|
|
424
|
+
const config = readSite(site);
|
|
425
|
+
if (call.target) await requireLiveName(site, config, local, POLICIES_PATH, "name", call.target);
|
|
426
|
+
return printAnswer(await siteRequest(site, config, local, call.path, call.method, undefined, "app"), `UniFi ${site} policy`);
|
|
403
427
|
}
|
|
404
428
|
if (rest[0] === "device-network") {
|
|
405
429
|
const call = deviceNetworkWrite(rest.slice(1));
|
|
406
430
|
return printAnswer(await siteRequest(site, readSite(site), local, call.path, call.method, call.body, "app"), `UniFi ${site} device`);
|
|
407
431
|
}
|
|
408
|
-
if (rest[0] === "nat"
|
|
409
|
-
if (rest
|
|
410
|
-
|
|
411
|
-
|
|
432
|
+
if (rest[0] === "nat") {
|
|
433
|
+
if (rest.length > 1) throw new UsageError("unifi <37|mira> nat takes no arguments");
|
|
434
|
+
return printAnswer(await siteRequest(site, readSite(site), local, NAT_PATH, "GET", undefined, "app"), `UniFi ${site} NAT`);
|
|
435
|
+
}
|
|
436
|
+
if (rest[0] === "nat-write") {
|
|
437
|
+
const call = natWrite(rest.slice(1));
|
|
438
|
+
const config = readSite(site);
|
|
439
|
+
if (call.target) await requireLiveName(site, config, local, NAT_PATH, "description", call.target);
|
|
440
|
+
return printAnswer(await siteRequest(site, config, local, call.path, call.method, call.body, "app"), `UniFi ${site} NAT`);
|
|
412
441
|
}
|
|
413
442
|
const write = rest[0] === "write" ? unifiWrite(rest.slice(1)) : null;
|
|
414
443
|
const path = write ? write.path : unifiPath(rest);
|
|
@@ -122,8 +122,10 @@ describe("network wrapper", () => {
|
|
|
122
122
|
it("limits application reads and device network writes", () => {
|
|
123
123
|
const id = "0123456789abcdef01234567";
|
|
124
124
|
expect(appGetPath(["/api/s/default/stat/device"])).toBe("/api/s/default/stat/device");
|
|
125
|
-
expect(appPolicyDelete(["
|
|
126
|
-
expect(() => appPolicyDelete([
|
|
125
|
+
expect(appPolicyDelete([id, "BLOCK INTERNET"])).toEqual({ method: "DELETE", path: `/v2/api/site/default/firewall-policies/${id}`, target: { id, name: "BLOCK INTERNET" } });
|
|
126
|
+
expect(() => appPolicyDelete([id])).toThrow(UsageError);
|
|
127
|
+
expect(() => appPolicyDelete([id, " "])).toThrow(UsageError);
|
|
128
|
+
expect(() => appPolicyDelete(["611cef69-df2e-4498-9845-8685daee84f3", "BLOCK INTERNET"])).toThrow(UsageError);
|
|
127
129
|
const fixed = JSON.stringify({ use_fixedip: true, fixed_ip: "10.1.50.50", network_id: "0123456789abcdef01234567" });
|
|
128
130
|
expect(clientFixedIpWrite(["0123456789abcdef01234567", fixed])).toEqual({ method: "PUT", path: "/api/s/default/rest/user/0123456789abcdef01234567", body: fixed });
|
|
129
131
|
expect(() => clientFixedIpWrite(["0123456789abcdef01234567", JSON.stringify({ name: "x" })])).toThrow(/body keys/);
|
|
@@ -142,8 +144,10 @@ describe("network wrapper", () => {
|
|
|
142
144
|
const id = "0123456789abcdef01234567";
|
|
143
145
|
expect(natWrite(["POST", '{"type":"DNAT"}'])).toEqual({ method: "POST", path: NAT_PATH, body: '{"type":"DNAT"}' });
|
|
144
146
|
expect(natWrite(["PUT", id, "{}"])).toEqual({ method: "PUT", path: `${NAT_PATH}/${id}`, body: "{}" });
|
|
145
|
-
expect(natWrite(["DELETE", id])).toEqual({ method: "DELETE", path: `${NAT_PATH}/${id}
|
|
146
|
-
expect(() => natWrite(["DELETE", id
|
|
147
|
+
expect(natWrite(["DELETE", id, "IoT DNS redirect"])).toEqual({ method: "DELETE", path: `${NAT_PATH}/${id}`, target: { id, name: "IoT DNS redirect" } });
|
|
148
|
+
expect(() => natWrite(["DELETE", id])).toThrow(UsageError);
|
|
149
|
+
expect(() => natWrite(["DELETE", id, ""])).toThrow(UsageError);
|
|
150
|
+
expect(() => natWrite(["DELETE", id, "IoT DNS redirect", "extra"])).toThrow(UsageError);
|
|
147
151
|
expect(() => natWrite(["PUT", "not-an-id", "{}"])).toThrow(UsageError);
|
|
148
152
|
expect(() => natWrite(["POST"])).toThrow(UsageError);
|
|
149
153
|
expect(() => natWrite(["POST", "{"])).toThrow(/JSON/);
|
|
@@ -834,3 +838,78 @@ describe("media wrapper", () => {
|
|
|
834
838
|
});
|
|
835
839
|
});
|
|
836
840
|
});
|
|
841
|
+
|
|
842
|
+
describe("dns stale-zone-delete", () => {
|
|
843
|
+
let home: string;
|
|
844
|
+
const originalHome = process.env.HOME;
|
|
845
|
+
|
|
846
|
+
beforeEach(() => {
|
|
847
|
+
home = mkdtempSync(join(tmpdir(), "spec-home-"));
|
|
848
|
+
process.env.HOME = home;
|
|
849
|
+
mkdirSync(join(home, ".specialists", "config"), { recursive: true });
|
|
850
|
+
writeFileSync(join(home, ".specialists", "config", "dns.json"), JSON.stringify({ technitiumPrimaryUrl: "http://10.0.40.53:5380" }));
|
|
851
|
+
mkdirSync(join(home, ".specialists", "secrets", "dns"), { recursive: true });
|
|
852
|
+
writeFileSync(join(home, ".specialists", "secrets", "dns", "TECHNITIUM_TOKEN"), "token", { mode: 0o600 });
|
|
853
|
+
});
|
|
854
|
+
|
|
855
|
+
afterEach(() => {
|
|
856
|
+
vi.unstubAllGlobals();
|
|
857
|
+
process.env.HOME = originalHome;
|
|
858
|
+
rmSync(home, { recursive: true, force: true });
|
|
859
|
+
});
|
|
860
|
+
|
|
861
|
+
it("never deletes the cluster catalog, which a Secondary node holds outside any catalog", async () => {
|
|
862
|
+
const paths: string[] = [];
|
|
863
|
+
vi.stubGlobal("fetch", async (url: URL) => {
|
|
864
|
+
paths.push(url.pathname);
|
|
865
|
+
const response = url.pathname === "/api/admin/cluster/state" ? { clusterDomain: "dns.home.arpa" } : { type: "SecondaryCatalog", catalog: null };
|
|
866
|
+
return new Response(JSON.stringify({ status: "ok", response }));
|
|
867
|
+
});
|
|
868
|
+
await expect(dnsCommand(["technitium", "node", "technitium2.dns.home.arpa", "stale-zone-delete", "Cluster-Catalog.dns.home.arpa."])).rejects.toThrow(/cluster catalog/);
|
|
869
|
+
expect(paths).not.toContain("/api/zones/delete");
|
|
870
|
+
});
|
|
871
|
+
});
|
|
872
|
+
|
|
873
|
+
describe("network deletes check the live name", () => {
|
|
874
|
+
let home: string;
|
|
875
|
+
const originalHome = process.env.HOME;
|
|
876
|
+
const id = "0123456789abcdef01234567";
|
|
877
|
+
|
|
878
|
+
beforeEach(() => {
|
|
879
|
+
home = mkdtempSync(join(tmpdir(), "spec-home-"));
|
|
880
|
+
process.env.HOME = home;
|
|
881
|
+
mkdirSync(join(home, ".specialists", "config"), { recursive: true });
|
|
882
|
+
writeFileSync(join(home, ".specialists", "config", "network.json"), JSON.stringify({ unifiMiraHostId: "ABC123:456", unifiMiraLocalUrl: "https://10.1.60.1/proxy/network/integration", unifiMiraCertSha256: "AA" }));
|
|
883
|
+
mkdirSync(join(home, ".specialists", "secrets", "network"), { recursive: true });
|
|
884
|
+
writeFileSync(join(home, ".specialists", "secrets", "network", "UNIFI_API_KEY"), "key", { mode: 0o600 });
|
|
885
|
+
});
|
|
886
|
+
|
|
887
|
+
afterEach(() => {
|
|
888
|
+
vi.unstubAllGlobals();
|
|
889
|
+
process.env.HOME = originalHome;
|
|
890
|
+
rmSync(home, { recursive: true, force: true });
|
|
891
|
+
});
|
|
892
|
+
|
|
893
|
+
function stubConsole(list: unknown[]): string[] {
|
|
894
|
+
const calls: string[] = [];
|
|
895
|
+
vi.stubGlobal("fetch", async (url: string, init?: RequestInit) => {
|
|
896
|
+
calls.push(`${init?.method ?? "GET"} ${new URL(url).pathname}`);
|
|
897
|
+
return new Response(init?.method === "DELETE" ? "{}" : JSON.stringify(list));
|
|
898
|
+
});
|
|
899
|
+
return calls;
|
|
900
|
+
}
|
|
901
|
+
|
|
902
|
+
it("deletes a policy only under its live name", async () => {
|
|
903
|
+
const calls = stubConsole([{ _id: id, name: "BLOCK INTERNET" }]);
|
|
904
|
+
await expect(networkCommand(["unifi", "mira", "app-policy-delete", id, "Allow All"])).rejects.toThrow(/"BLOCK INTERNET", not "Allow All"; nothing deleted/);
|
|
905
|
+
expect(calls.some((c) => c.startsWith("DELETE"))).toBe(false);
|
|
906
|
+
await networkCommand(["unifi", "mira", "app-policy-delete", id, "BLOCK INTERNET"]);
|
|
907
|
+
expect(calls.filter((c) => c.startsWith("DELETE"))).toHaveLength(1);
|
|
908
|
+
});
|
|
909
|
+
|
|
910
|
+
it("refuses a NAT delete of a rule that is not there", async () => {
|
|
911
|
+
const calls = stubConsole([{ _id: "fedcba9876543210fedcba98", description: "IoT DNS redirect" }]);
|
|
912
|
+
await expect(networkCommand(["unifi", "mira", "nat-write", "DELETE", id, "IoT DNS redirect"])).rejects.toThrow(/is not in .*nothing deleted/);
|
|
913
|
+
expect(calls.some((c) => c.startsWith("DELETE"))).toBe(false);
|
|
914
|
+
});
|
|
915
|
+
});
|