@astrofoundry/pi-astro 0.40.15 → 0.40.17

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.
@@ -12,6 +12,7 @@ describe("approvals", () => {
12
12
  expect(isRisky("dns", ["technitium", "primary", "cluster-init", "dns.home.arpa", "10.0.40.53"])).toBe(true);
13
13
  expect(isRisky("dns", ["technitium", "node", "technitium2.dns.home.arpa", "server-domain", "technitium2"])).toBe(true);
14
14
  expect(isRisky("dns", ["technitium", "node", "technitium2.dns.home.arpa", "cluster-state"])).toBe(false);
15
+ expect(isRisky("dns", ["technitium", "join", "http://10.1.40.53:5380", "10.1.40.53"])).toBe(true);
15
16
  expect(isRisky("identity", ["zitadel", "GET", "/v2/users"])).toBe(false);
16
17
  expect(isRisky("identity", ["zitadel", "DELETE", "/v2/users/1"])).toBe(true);
17
18
  expect(isRisky("identity", ["dmz", "deploy-config"])).toBe(true);
@@ -37,6 +37,7 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
37
37
  dns: [
38
38
  /^technitium\s+primary\s+(zone-create|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\b/,
40
+ /^technitium\s+join\b/,
40
41
  /^cloudflare\s+record-(add|update|delete)\b/,
41
42
  ],
42
43
  edge: [/^vps\s+deploy-nginx\b/],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.15",
3
+ "version": "0.40.17",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -39,7 +39,13 @@ Record parameters by type (the API's names): `A`/`AAAA` `ipAddress` (update: `ne
39
39
 
40
40
  Every internal service name is its own Primary zone (`auth.37pla.net`, `kuma.37pla.net`, ...; 33 zones including `catalog.invalid` and the `orange.es` forwarder). There is no internal `37pla.net` zone: run `zones` first, then use the exact zone name, and create a new zone with `zone-create <fqdn>` before adding its records.
41
41
 
42
- Zone, record, and cluster writes are refused with `node`. Replication is near-immediate; if a node still answers the old value after a minute, report it as a replication problem. Joining a node to the cluster needs that node's own admin login and stays an owner task in its web console.
42
+ Zone, record, and cluster writes are refused with `node`. Replication is near-immediate; if a node still answers the old value after a minute, report it as a replication problem.
43
+
44
+ `technitium join <nodeUrl> <nodeIp>` adds a fresh node as a Secondary node: it refuses a node whose default `admin`/`admin` login was already changed, creates a one-time admin with a random password on the primary for the join, and deletes it afterwards. The join replaces the node's settings, blocklists, apps, and users with the primary's. Check `cluster-state` afterwards.
45
+
46
+ ```json
47
+ { "args": ["technitium", "join", "http://10.1.40.53:5380", "10.1.40.53"] }
48
+ ```
43
49
 
44
50
  Internal split DNS: public hostnames such as `auth.37pla.net` resolve to the DMZ (`10.0.20.10`) inside the homelab and to the VPS (`35.237.66.101`) outside.
45
51
 
@@ -43,7 +43,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
43
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
- - `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. Every call goes to the cluster primary with one token; `node <fqdn>` adds Technitium's `node` parameter so the primary runs a read or `server-domain` on that node. Zone, record, and cluster writes are refused with `node` in code: the catalog zone and the cluster are the only replication paths. Joining a node needs that node's own admin login, so it stays an owner task.
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. Every call goes to the cluster primary with one token; `node <fqdn>` adds Technitium's `node` parameter so the primary runs a read or `server-domain` on that node. Zone, record, and cluster writes are refused with `node` in code: the catalog zone and the cluster are the only replication paths. `technitium join` joins a fresh node: it logs in with Technitium's default login (refused once changed), creates a one-time admin with a random password on the primary for `initJoin`, and deletes it in `finally`; no password is stored or printed.
47
47
  - `security` parses Wazuh alert lines locally (`summariseWazuh`, `summariseVulns`) so the guest never needs `jq`; `wazuh-vulns`, `wazuh-events` (every non-vulnerability alert of the last N minutes at or above a level, with the alert id and the FIM path, change, and `sha256_after`; at most the newest 1000), and `wazuh-vuln-events` (every vulnerability finding, compact) are local views over the same `wazuh-alerts` dump, not guest commands. `alerts` adds each ban's whole length (time left plus the alert's age, to the hour), the escalated bans (longer than CrowdSec's default 4 hours), and the top countries and networks. The Discord bridge's security checks use these through the entry point (`extensions/astro-discord/security-monitor.ts`).
48
48
  - `arcane change-origin <path> <sha256|-> <utc>` (`lib/change-origin.ts`) fetches origin, hashes the file in the newest 30 commits touching `<project>/<file>` up to 15 minutes after the change, and reads the last 16 MiB of the audit log for our `stack-update`, `manager-upgrade`, `manager-rollback`, or `host db-restore` on that stack (from a minute before its start to ten minutes after its end). It takes no checkout lock: like `update-report`'s holds read, it only fetches and reads objects, never the working tree. On 2026-10-21 the "Old md5sum" values of the live 100020 alerts matched the repository's previous Grimoire commits, which confirms that Arcane syncs these files verbatim.
49
49
  - TLS pinning for self-signed consoles is `lib/pinned.ts` (`pinnedRequest`); `network` and `proxmox` use it with a `*CertSha256` config value obtained once through the wrapper's `fingerprint` command.
@@ -7,7 +7,7 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
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
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
- | `astro.dns` | Technitium cluster `dns.home.arpa` (primary `technitium1` on Synapse, `technitium2` in LXC 107, `technitium3` at Mira); Cloudflare zones `37pla.net`, `monadeo.com` | Read zones, records, settings, and cluster state on every node through the primary, resolve, stats; create and delete zones, add, update, delete records, initialize and delete the cluster, remove a node, set a node's server domain; Cloudflare zones and record add, update, delete |
10
+ | `astro.dns` | Technitium cluster `dns.home.arpa` (primary `technitium1` on Synapse, `technitium2` in LXC 107, `technitium3` at Mira); Cloudflare zones `37pla.net`, `monadeo.com` | Read zones, records, settings, and cluster state on every node through the primary, resolve, stats; create and delete zones, add, update, delete records, initialize and delete the cluster, join a fresh node, remove a node, set a node's server domain; 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` |
13
13
  | `astro.backup` | vzdump, the shared Restic repository (Pulsar host config, Arcane app backups), GCS offsite from LXC 102 | Status, journals, and manual runs of every layer; `restic-snapshots|stats|ls`, `restic-restore` into `/var/tmp/spc-restore` on Pulsar, `restore-clean` |
@@ -1,3 +1,4 @@
1
+ import { randomBytes } from "node:crypto";
1
2
  import { readConfig } from "../lib/config.ts";
2
3
  import { ServiceError, UsageError } from "../lib/errors.ts";
3
4
  import { main } from "../lib/main.ts";
@@ -18,6 +19,12 @@ const SHAPE = { technitiumPrimaryUrl: "string", technitiumCatalog: "string" } as
18
19
 
19
20
  const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
20
21
  const TIMEOUT_MS = 30_000;
22
+ /** Below the gate's 60 s limit for the dns tool; a join transfers the primary's whole configuration. */
23
+ const JOIN_TIMEOUT_MS = 55_000;
24
+ /** Technitium's documented default login on a fresh install; a join replaces it with the primary's users. */
25
+ const DEFAULT_LOGIN = { user: "admin", pass: "admin" } as const;
26
+ const NODE_URL = /^https?:\/\/[0-9.]+:[0-9]{1,5}\/?$/;
27
+ const IPV4 = /^[0-9]{1,3}(\.[0-9]{1,3}){3}$/;
21
28
 
22
29
  const NAME = /^[A-Za-z0-9_.-]{1,253}$/;
23
30
  const RECORD_TYPE = /^[A-Z0-9]{1,10}$/;
@@ -55,6 +62,7 @@ const HELP = `dns specialist
55
62
 
56
63
  technitium primary <command> [args] the cluster primary
57
64
  technitium node <fqdn> <command> [args] another cluster node, through the primary (reads and server-domain)
65
+ technitium join <nodeUrl> <nodeIp> join a fresh node (default login) as a Secondary node, e.g. http://10.1.40.53:5380 10.1.40.53
58
66
  reads:
59
67
  ${Object.values(TECHNITIUM_READS)
60
68
  .map((r) => ` ${r.help}`)
@@ -167,6 +175,84 @@ interface TechnitiumResponse {
167
175
  status?: string;
168
176
  errorMessage?: string;
169
177
  response?: unknown;
178
+ /** Set by the login call only. */
179
+ token?: string;
180
+ }
181
+
182
+ interface ClusterNode {
183
+ url: string;
184
+ ipAddresses?: string[];
185
+ type: string;
186
+ }
187
+
188
+ /** POSTs a form to a Technitium API and returns the parsed body; `what` names the server in errors. */
189
+ async function technitiumCall(base: string, path: string, params: Record<string, string>, token: string | undefined, what: string, timeoutMs = TIMEOUT_MS): Promise<TechnitiumResponse> {
190
+ const headers: Record<string, string> = { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" };
191
+ if (token !== undefined) headers.Authorization = `Bearer ${token}`;
192
+ const response = await fetch(new URL(path, base), { method: "POST", headers, body: new URLSearchParams(params), signal: AbortSignal.timeout(timeoutMs) });
193
+ const text = await response.text();
194
+ let parsed: TechnitiumResponse;
195
+ try {
196
+ parsed = JSON.parse(text) as TechnitiumResponse;
197
+ } catch {
198
+ throw new ServiceError(`Technitium ${what} answered ${response.status} with a non-JSON body`);
199
+ }
200
+ if (parsed.status !== "ok") {
201
+ throw new ServiceError(`Technitium ${what}: ${parsed.status ?? response.status}${parsed.errorMessage ? `: ${parsed.errorMessage}` : ""}`);
202
+ }
203
+ return parsed;
204
+ }
205
+
206
+ export function parseJoinArgs(args: string[]): { nodeUrl: string; nodeIp: string } {
207
+ if (args.length !== 2 || !NODE_URL.test(args[0]) || !IPV4.test(args[1])) {
208
+ throw new UsageError("technitium join <nodeUrl> <nodeIp>, e.g. http://10.1.40.53:5380 10.1.40.53");
209
+ }
210
+ return { nodeUrl: args[0], nodeIp: args[1] };
211
+ }
212
+
213
+ /**
214
+ * Joins a fresh node to the cluster. Technitium's join runs on the joining node and needs an admin session there plus an admin
215
+ * username and password of the primary, so a one-time admin with a random password exists on the primary only during the call.
216
+ */
217
+ async function join(config: DnsConfig, args: string[]): Promise<number> {
218
+ const { nodeUrl, nodeIp } = parseJoinArgs(args);
219
+ const status = await fetch(new URL("/api/status", nodeUrl), { signal: AbortSignal.timeout(TIMEOUT_MS) }).then((r) => r.json() as Promise<{ hasDefaultCredentials?: boolean }>);
220
+ if (status.hasDefaultCredentials !== true) throw new UsageError(`${nodeUrl} no longer has the default login; joining a configured node stays an owner task`);
221
+ const session = await technitiumCall(nodeUrl, "/api/user/login", DEFAULT_LOGIN, undefined, "joining node");
222
+ if (session.token === undefined) throw new ServiceError("joining node returned no session token");
223
+
224
+ const token = readSecret(SERVICE, "TECHNITIUM_TOKEN");
225
+ const state = await technitiumCall(config.technitiumPrimaryUrl, "/api/admin/cluster/state", {}, token, "primary");
226
+ // Technitium 15.6 returns `clusterNodes`; the API documentation still shows `nodes`.
227
+ const primary = ((state.response as { clusterNodes?: ClusterNode[] } | undefined)?.clusterNodes ?? []).find((n) => n.type === "Primary");
228
+ const primaryIp = primary?.ipAddresses?.[0];
229
+ if (primary === undefined || primaryIp === undefined) throw new ServiceError("the primary reports no initialized cluster");
230
+
231
+ const user = `spc-join-${randomBytes(4).toString("hex")}`;
232
+ const pass = randomBytes(24).toString("base64url");
233
+ await technitiumCall(config.technitiumPrimaryUrl, "/api/admin/users/create", { user, pass, displayName: "one-time cluster join" }, token, "primary");
234
+ try {
235
+ await technitiumCall(config.technitiumPrimaryUrl, "/api/admin/users/set", { user, memberOfGroups: "Administrators" }, token, "primary");
236
+ const joined = await technitiumCall(
237
+ nodeUrl,
238
+ "/api/admin/cluster/initJoin",
239
+ {
240
+ secondaryNodeIpAddresses: nodeIp,
241
+ primaryNodeUrl: primary.url,
242
+ primaryNodeIpAddress: primaryIp,
243
+ ignoreCertificateErrors: "true",
244
+ primaryNodeUsername: user,
245
+ primaryNodePassword: pass,
246
+ },
247
+ session.token,
248
+ "joining node",
249
+ JOIN_TIMEOUT_MS,
250
+ );
251
+ printJson({ node: nodeUrl, status: joined.status, response: redactSecrets(joined.response ?? null) });
252
+ } finally {
253
+ await technitiumCall(config.technitiumPrimaryUrl, "/api/admin/users/delete", { user }, token, "primary");
254
+ }
255
+ return 0;
170
256
  }
171
257
 
172
258
  /** Splits `primary <command>` or `node <fqdn> <command>` into the target node (undefined for the primary) and the command. */
@@ -181,28 +267,13 @@ export function technitiumTarget(args: string[]): { node: string | undefined; re
181
267
  }
182
268
 
183
269
  async function technitium(config: DnsConfig, args: string[]): Promise<number> {
270
+ if (args[0] === "join") return join(config, args.slice(1));
184
271
  const { node, rest } = technitiumTarget(args);
185
272
  const request = technitiumRequest(config.technitiumCatalog, rest);
186
273
  if (node !== undefined && request.primaryOnly) throw new UsageError("zone and cluster writes go to the primary; the other nodes follow through the catalog zone and the cluster");
187
274
  const params = node === undefined ? request.params : { ...request.params, node };
188
- const token = readSecret(SERVICE, "TECHNITIUM_TOKEN");
189
275
  const target = node ?? "primary";
190
- const response = await fetch(new URL(request.path, config.technitiumPrimaryUrl), {
191
- method: "POST",
192
- headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
193
- body: new URLSearchParams(params),
194
- signal: AbortSignal.timeout(TIMEOUT_MS),
195
- });
196
- const text = await response.text();
197
- let parsed: TechnitiumResponse;
198
- try {
199
- parsed = JSON.parse(text) as TechnitiumResponse;
200
- } catch {
201
- throw new ServiceError(`Technitium ${target} answered ${response.status} with a non-JSON body`);
202
- }
203
- if (parsed.status !== "ok") {
204
- throw new ServiceError(`Technitium ${target}: ${parsed.status ?? response.status}${parsed.errorMessage ? `: ${parsed.errorMessage}` : ""}`);
205
- }
276
+ const parsed = await technitiumCall(config.technitiumPrimaryUrl, request.path, params, readSecret(SERVICE, "TECHNITIUM_TOKEN"), target);
206
277
  printJson({ node: target, status: parsed.status, response: redactSecrets(parsed.response ?? null) });
207
278
  return 0;
208
279
  }
@@ -4,7 +4,7 @@ import { join } from "node:path";
4
4
  import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
5
5
  import { refusedPrefix, command as arcaneCommand } from "./arcane/run.ts";
6
6
  import { buildBackupRemote, command as backupCommand } from "./backup/run.ts";
7
- import { parseParams, parseRecordFilters, technitiumRequest, technitiumTarget, command as dnsCommand } from "./dns/run.ts";
7
+ import { parseJoinArgs, parseParams, parseRecordFilters, technitiumRequest, technitiumTarget, command as dnsCommand } from "./dns/run.ts";
8
8
  import { buildVpsRemote, command as edgeCommand, isTransientSshFailure, PUBLIC_ROUTES, routeProbe } from "./edge/run.ts";
9
9
  import { API_PREFIXES, buildDmzRemote, validateApiPath, command as identityCommand } from "./identity/run.ts";
10
10
  import { buildInferenceRemote, command as inferenceCommand } from "./inference/run.ts";
@@ -206,6 +206,13 @@ describe("dns wrapper", () => {
206
206
  expect(() => technitiumTarget(["node", "technitium2", "zones"])).toThrow(/domain name/);
207
207
  });
208
208
 
209
+ it("validates join arguments", () => {
210
+ expect(parseJoinArgs(["http://10.1.40.53:5380", "10.1.40.53"])).toEqual({ nodeUrl: "http://10.1.40.53:5380", nodeIp: "10.1.40.53" });
211
+ expect(() => parseJoinArgs(["http://evil.example:5380", "10.1.40.53"])).toThrow(UsageError);
212
+ expect(() => parseJoinArgs(["http://10.1.40.53:5380", "10.1.40.53,10.0.40.1"])).toThrow(UsageError);
213
+ expect(() => parseJoinArgs(["http://10.1.40.53:5380"])).toThrow(UsageError);
214
+ });
215
+
209
216
  it("rejects malformed names, types, and parameters", () => {
210
217
  expect(() => technitiumRequest("c", ["records", "bad zone"])).toThrow(/DNS name/);
211
218
  expect(() => technitiumRequest("c", ["record-add", "z.test", "a.z.test", "a", "ipAddress=1.2.3.4"])).toThrow(/record type/);