@astrofoundry/pi-astro 0.40.13 → 0.40.15

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/agents/dns.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: dns
3
- description: Operates internal DNS (Technitium primary and secondary) and public DNS (Cloudflare zones 37pla.net and monadeo.com) through the dns tool. Use for zone and record questions, record changes, split-DNS checks, and resolver health.
3
+ description: Operates internal DNS (the Technitium cluster at 37 and Mira) and public DNS (Cloudflare zones 37pla.net and monadeo.com) through the dns tool. Use for zone and record questions, record changes, split-DNS checks, cluster state, and resolver health.
4
4
  tools: read, dns, subagent
5
5
  skills: dns
6
6
  systemPromptMode: replace
@@ -15,7 +15,7 @@ You are the DNS specialist. The `dns` tool is your only way to reach Technitium
15
15
  Rules:
16
16
 
17
17
  - Read before you write: list the zone's records, then add, update, or delete exactly the record the task names. Never create duplicates.
18
- - Internal changes go to the Technitium primary only; the secondary follows through the catalog zone. After a write, read the same zone from the secondary and report whether it has caught up.
18
+ - Internal changes go to the Technitium primary only; the other nodes follow through the catalog zone and the cluster. After a write, read the same zone from every node with `node <fqdn>` and report whether each has caught up.
19
19
  - New internal zones are Primary zones in the configured catalog; confirm with `zone-options` afterwards.
20
20
  - Public records for the front door point at the VPS address with TTL 300 and `proxied: false`. Add the hostname to the VPS nginx allowlist (edge specialist) before the public record exists.
21
21
  - Deleting a zone or a record is only for tasks that name it explicitly; state what would disappear before you do it.
@@ -9,6 +9,9 @@ describe("approvals", () => {
9
9
  expect(isRisky("dns", ["technitium", "primary", "zones"])).toBe(false);
10
10
  expect(isRisky("dns", ["technitium", "primary", "record-delete", "z", "d", "A", "ipAddress=1.1.1.1"])).toBe(true);
11
11
  expect(isRisky("dns", ["cloudflare", "record-add", "37pla.net", "{}"])).toBe(true);
12
+ expect(isRisky("dns", ["technitium", "primary", "cluster-init", "dns.home.arpa", "10.0.40.53"])).toBe(true);
13
+ expect(isRisky("dns", ["technitium", "node", "technitium2.dns.home.arpa", "server-domain", "technitium2"])).toBe(true);
14
+ expect(isRisky("dns", ["technitium", "node", "technitium2.dns.home.arpa", "cluster-state"])).toBe(false);
12
15
  expect(isRisky("identity", ["zitadel", "GET", "/v2/users"])).toBe(false);
13
16
  expect(isRisky("identity", ["zitadel", "DELETE", "/v2/users/1"])).toBe(true);
14
17
  expect(isRisky("identity", ["dmz", "deploy-config"])).toBe(true);
@@ -34,7 +34,11 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
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
36
  network: [/^unifi\s+\S+\s+write\b/],
37
- dns: [/^technitium\s+primary\s+(zone-create|zone-delete|record-add|record-update|record-delete)\b/, /^cloudflare\s+record-(add|update|delete)\b/],
37
+ dns: [
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
+ /^technitium\s+node\s+\S+\s+server-domain\b/,
40
+ /^cloudflare\s+record-(add|update|delete)\b/,
41
+ ],
38
42
  edge: [/^vps\s+deploy-nginx\b/],
39
43
  backup: [/^(vzdump-run|host-backup-run|arcane-backup-run|gcs-run|restic-check-run|restic-restore|restore-clean)\b/],
40
44
  proxmox: [/^(set|snapshot-create|start)\b/],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.13",
3
+ "version": "0.40.15",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: dns
3
- description: How the dns specialist operates Technitium (internal resolvers) and Cloudflare (public zones) through the dns tool.
3
+ description: How the dns specialist operates the Technitium cluster (internal resolvers at 37 and Mira) and Cloudflare (public zones) through the dns tool.
4
4
  ---
5
5
 
6
6
  # DNS specialist
7
7
 
8
- Two resolvers serve the homelab: Technitium primary on Synapse (`10.0.40.53`) and secondary in LXC 107 (`10.0.40.54`). The primary owns every zone; the `catalog.invalid` catalog zone replicates them to the secondary, which also mirrors the blocklists. Public names live in Cloudflare zones `37pla.net` and `monadeo.com`. The `dns` tool has two families; `["--help"]` lists everything.
8
+ The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary node `technitium1` on Synapse (`10.0.40.53`), and the Secondary nodes `technitium2` (LXC 107 on Pulsar, `10.0.40.54`) and `technitium3` (LXC 100 on SPACE-X at Mira, `10.1.40.53`). The primary owns every zone; the configured catalog zone replicates them, and the cluster syncs settings, blocklists, allowed and blocked zones, apps, and users to the other nodes. Every call goes to the primary; `node <fqdn>` makes the primary run it on another node. Public names live in Cloudflare zones `37pla.net` and `monadeo.com`. The `dns` tool has two families; `["--help"]` lists everything.
9
9
 
10
- ## `technitium <primary|secondary> <command>`
10
+ ## `technitium primary <command>` and `technitium node <fqdn> <command>`
11
11
 
12
12
  | Command | Effect |
13
13
  |---|---|
@@ -16,23 +16,30 @@ Two resolvers serve the homelab: Technitium primary on Synapse (`10.0.40.53`) an
16
16
  | `zone-options <zone>` | zone settings, including its catalog membership |
17
17
  | `resolve <domain> [type]` | ask that resolver (default type `A`) |
18
18
  | `stats [LastHour\|LastDay\|LastWeek\|LastMonth\|LastYear]` | dashboard counters |
19
+ | `cluster-state` | cluster domain, nodes with id, type, state, and last seen, and the server's addresses |
20
+ | `settings` | all server settings; secrets are redacted |
19
21
  | `zone-create <zone>` (primary) | Primary zone in the catalog |
20
22
  | `zone-delete <zone>` (primary) | deletes the zone and every record |
21
23
  | `record-add <zone> <domain> <type> key=value...` (primary) | `/api/zones/records/add` |
22
24
  | `record-update <zone> <domain> <type> key=value...` (primary) | `/api/zones/records/update` |
23
25
  | `record-delete <zone> <domain> <type> key=value...` (primary) | `/api/zones/records/delete` |
26
+ | `cluster-init <clusterDomain> <ip[,ip]>` (primary) | make the primary the Primary node of a new cluster |
27
+ | `cluster-delete` (primary) | remove the cluster from the primary; refused while Secondary nodes exist |
28
+ | `cluster-remove <secondaryNodeId>` (primary) | ask a Secondary node (id from `cluster-state`) to leave |
29
+ | `server-domain <name>` (primary or node) | set that node's DNS Server Domain |
24
30
 
25
31
  Record parameters by type (the API's names): `A`/`AAAA` `ipAddress` (update: `newIpAddress`); `CNAME` `cname`; `TXT` `text`; `MX` `exchange`, `preference`; `SRV` `priority`, `weight`, `port`, `target`; `NS` `nameServer`; `PTR` `ptrName`. `ttl=<seconds>` and `comments=<text>` apply to all; `overwrite=true` replaces the record set on add.
26
32
 
27
33
  ```json
28
34
  { "args": ["technitium", "primary", "records", "auth.37pla.net"] }
29
35
  { "args": ["technitium", "primary", "record-add", "kuma.37pla.net", "kuma.37pla.net", "A", "ipAddress=10.0.40.30", "ttl=300"] }
30
- { "args": ["technitium", "secondary", "resolve", "kuma.37pla.net"] }
36
+ { "args": ["technitium", "node", "technitium3.dns.home.arpa", "resolve", "kuma.37pla.net"] }
37
+ { "args": ["technitium", "primary", "cluster-state"] }
31
38
  ```
32
39
 
33
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.
34
41
 
35
- Writes are refused on the secondary. Replication is near-immediate; if the secondary still answers the old value after a minute, report it as a replication problem.
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.
36
43
 
37
44
  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.
38
45
 
@@ -48,7 +48,7 @@ Any write of the Network API under `/v1/sites/<siteId>/`: networks, Wi-Fi broadc
48
48
 
49
49
  Procedure for every write:
50
50
 
51
- 1. Read the current object (or, for a create, an existing object of the same kind) with `get` and copy its structure. When the site has none of that kind yet, use exactly the fields the task gives; never invent a field name. A PUT sends the complete object without `id` and `metadata`.
51
+ 1. Read the current object (or, for a create, an existing object of the same kind) with `get` and copy its structure. When the site has none of that kind yet, use exactly the fields the task gives; never invent a field name. A PUT sends the complete object; every write body leaves out the read-only fields `id`, `metadata`, `default`, and `index`, which UniFi rejects with 400 `Unknown request body property`.
52
52
  2. For a firewall policy, read `firewall-zones` for the zone ids; names follow `<what> - from <source>` (the `from Cortex` family on 37: source zone plus source IP filter, destination zone plus IP and port filter, TCP, IPv4, return traffic allowed, logging off).
53
53
  3. Write, then read the object back and report its id, name, and the fields that changed.
54
54
 
@@ -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. Writes are refused on the secondary in code: the catalog zone is the only replication path.
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.
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 primary (Synapse) and secondary (LXC 107); Cloudflare zones `37pla.net`, `monadeo.com` | Read zones and records on both resolvers, resolve, stats; create and delete zones, add, update, delete records on the primary; 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, 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` |
@@ -36,14 +36,14 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
36
36
  - `arcane`: `ZITADEL_KEY_JSON`, `GITOPS_DEPLOY_KEY_B64`, `ZITADEL_USER_ID` (plain), `SSH_KEY_ARCANE_HOST_B64` (user `spc-arcane` on VM 100, for `host`, `manager-*`), and optionally `MEALIE_API_KEY` (only `host mealie-api` reads it).
37
37
  - `identity`: `ZITADEL_PAT`, `SSH_KEY_DMZ_B64`, `HOMELAB_DEPLOY_KEY_B64`.
38
38
  - `network`: `UNIFI_API_KEY` (account key: unifi.ui.com, Settings, API Keys), `UNIFI_LOCAL_37_API_KEY` and `UNIFI_LOCAL_MIRA_API_KEY` (each console: Network, Settings, Integrations), `SSH_KEY_PULSAR_B64`.
39
- - `dns`: `TECHNITIUM_TOKEN`, `TECHNITIUM2_TOKEN` (Technitium API tokens of the primary and the secondary), `CLOUDFLARE_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`.
39
+ - `dns`: `TECHNITIUM_TOKEN` (API token of user `spc-dns` on the cluster primary), `CLOUDFLARE_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`.
40
40
  - `edge`: `GCP_SA_KEY_JSON` (service account key), `SSH_KEY_FRONTDOOR_B64`, `HOMELAB_DEPLOY_KEY_B64`.
41
41
  - `security`: `SSH_KEY_OBS_B64`.
42
42
  - `backup`: `SSH_KEY_PULSAR_B64`, `SSH_KEY_ARCANE_B64`.
43
43
  - `proxmox`: `PVE_TOKEN_ID` (plain, `spc-proxmox@pve!cortex`), `PVE_TOKEN_SECRET`, `SSH_KEY_PULSAR_B64`.
44
44
  - `inference`: `SSH_KEY_NEXUS_B64`.
45
45
  - `media`: `TMDB_ACCESS_TOKEN` (TMDB API Read Access Token), `OMDB_API_KEY`, `RADARR_API_KEY`, `SONARR_API_KEY` (Settings, General, Security; each app has one), `SABNZBD_API_KEY` (the API key, not the NZB key, which can only add NZBs and cannot read or pause the queue).
46
- 2. **Identities.** Zitadel (`https://auth.37pla.net/ui/console`): service user `spc-arcane` with Access Token Type JWT and a JSON key; service user `spc-identity` with a Personal Access Token and the Instance Owner role. Technitium (both resolvers): a user with Zones View/Modify/Delete, Dashboard View, DNS Client View, and an API token each. Cloudflare: an account-owned API token with `Zone:Read` and `DNS:Edit` on both zones. GCP project `frontdoor-1337`: service account `spc-edge` with `roles/iap.tunnelResourceAccessor` and `roles/compute.viewer`, JSON key. Proxmox (`ssh pulsar`): user `spc-proxmox@pve`, role `SpecialistGuest` = `VM.Audit VM.PowerMgmt VM.Snapshot VM.Snapshot.Rollback VM.Config.CPU VM.Config.Memory VM.Config.Options VM.Config.Network VM.Config.CDROM VM.GuestAgent.Audit`, ACLs `PVEAuditor` on `/` and `SpecialistGuest` on `/vms` for both the user and the token `spc-proxmox@pve!cortex` (`-privsep 1`).
46
+ 2. **Identities.** Zitadel (`https://auth.37pla.net/ui/console`): service user `spc-arcane` with Access Token Type JWT and a JSON key; service user `spc-identity` with a Personal Access Token and the Instance Owner role. Technitium (cluster primary): user `spc-dns` in the Administrators group with an API token; the cluster syncs the user to every node. Cloudflare: an account-owned API token with `Zone:Read` and `DNS:Edit` on both zones. GCP project `frontdoor-1337`: service account `spc-edge` with `roles/iap.tunnelResourceAccessor` and `roles/compute.viewer`, JSON key. Proxmox (`ssh pulsar`): user `spc-proxmox@pve`, role `SpecialistGuest` = `VM.Audit VM.PowerMgmt VM.Snapshot VM.Snapshot.Rollback VM.Config.CPU VM.Config.Memory VM.Config.Options VM.Config.Network VM.Config.CDROM VM.GuestAgent.Audit`, ACLs `PVEAuditor` on `/` and `SpecialistGuest` on `/vms` for both the user and the token `spc-proxmox@pve!cortex` (`-privsep 1`).
47
47
  3. **Services.** Arcane (Settings, Authentication, Federated Credentials): Issuer `https://auth.37pla.net`, Audience `387825541182390275`, Subject exact = `spc-arcane` user ID, Role Admin, Global, lifetime 300. UniFi: the account key and a local key per console (fields above) and policies on 37 allowing Cortex `10.0.40.37` to TCP 22 on `10.0.20.10`, `10.0.10.37`, `10.0.90.10`, TCP 5380 on `10.0.40.53`, `10.0.40.54`, TCP 8006 on `10.0.10.37`, and TCP 8081 on `10.0.60.5`. GitHub: `spc-arcane-gitops` as a write deploy key on `astronaute77/arcane`, `spc-edge-homelab` and `spc-identity-homelab` as write deploy keys on `astronaute77/homelab`.
48
48
  4. **Sudo and user**, as an administrator:
49
49
  ```sh
@@ -73,7 +73,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
73
73
  "homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "02-pulsar-proxmox/dmz", "pomeriumConfig": "02-pulsar-proxmox/dmz/config.yaml" }
74
74
  { "unifi37HostId": "<from: specialist-cli network -- unifi cloud /v1/hosts>", "unifi37LocalUrl": "https://10.0.10.1/proxy/network/integration", "unifi37CertSha256": "<from: specialist-cli network -- unifi 37 fingerprint>",
75
75
  "unifiMiraHostId": "<the same>", "unifiMiraLocalUrl": "https://192.168.1.1/proxy/network/integration", "unifiMiraCertSha256": "<the same>", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
76
- { "technitiumPrimaryUrl": "http://10.0.40.53:5380", "technitiumSecondaryUrl": "http://10.0.40.54:5380", "technitiumCatalog": "catalog.invalid" }
76
+ { "technitiumPrimaryUrl": "http://10.0.40.53:5380", "technitiumCatalog": "cluster-catalog.dns.home.arpa" }
77
77
  { "gcloud": "/usr/local/libexec/specialist-gcloud/current/bin/gcloud", "gcloudPython": "/usr/local/libexec/specialist-python/current/bin/python3",
78
78
  "project": "frontdoor-1337", "zone": "us-east1-c", "instance": "frontdoor-1337", "serviceAccount": "spc-edge@frontdoor-1337.iam.gserviceaccount.com",
79
79
  "iapLocalPort": 22337, "sshUser": "spc-edge", "publicIp": "35.237.66.101", "probeHost": "auth.37pla.net",
@@ -8,25 +8,24 @@ import { readSecret } from "../lib/secrets.ts";
8
8
  const SERVICE = "dns";
9
9
 
10
10
  interface DnsConfig extends Record<string, string> {
11
+ /** API of the cluster primary; every other node is reached through it with the `node` parameter. */
11
12
  technitiumPrimaryUrl: string;
12
- technitiumSecondaryUrl: string;
13
- /** Catalog zone new primary zones join, so the secondary receives them. */
13
+ /** Catalog zone new primary zones join, so the other nodes receive them. */
14
14
  technitiumCatalog: string;
15
15
  }
16
16
 
17
- const SHAPE = { technitiumPrimaryUrl: "string", technitiumSecondaryUrl: "string", technitiumCatalog: "string" } as const;
17
+ const SHAPE = { technitiumPrimaryUrl: "string", technitiumCatalog: "string" } as const;
18
18
 
19
19
  const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
20
20
  const TIMEOUT_MS = 30_000;
21
21
 
22
- export const NODES = ["primary", "secondary"] as const;
23
- export type Node = (typeof NODES)[number];
24
-
25
22
  const NAME = /^[A-Za-z0-9_.-]{1,253}$/;
26
23
  const RECORD_TYPE = /^[A-Z0-9]{1,10}$/;
27
24
  const PARAM_KEY = /^[a-zA-Z]{1,40}$/;
28
25
  const STATS_TYPES = ["LastHour", "LastDay", "LastWeek", "LastMonth", "LastYear"];
29
26
  const HEX_ID = /^[0-9a-f]{32}$/;
27
+ const NODE_ID = /^[0-9]{1,10}$/;
28
+ const IP_LIST = /^[0-9A-Fa-f:.]+(,[0-9A-Fa-f:.]+)*$/;
30
29
 
31
30
  /** Technitium HTTP API reads, valid on both nodes. */
32
31
  export const TECHNITIUM_READS: Readonly<Record<string, { args: [number, number]; help: string }>> = {
@@ -35,24 +34,32 @@ export const TECHNITIUM_READS: Readonly<Record<string, { args: [number, number];
35
34
  "zone-options": { args: [1, 1], help: "zone-options <zone> zone settings, including its catalog" },
36
35
  resolve: { args: [1, 2], help: "resolve <domain> [type] query this server (type default A)" },
37
36
  stats: { args: [0, 1], help: `stats [${STATS_TYPES.join("|")}] dashboard counters` },
37
+ "cluster-state": { args: [0, 0], help: "cluster-state cluster nodes, their state, and this server's addresses" },
38
+ settings: { args: [0, 0], help: "settings all server settings (secrets redacted)" },
38
39
  };
39
40
 
40
- /** Technitium writes; the primary only, the secondary receives zones through the catalog. */
41
+ /** Technitium writes; zone and cluster writes on the primary only, the other nodes follow through the catalog and the cluster. */
41
42
  export const TECHNITIUM_WRITES: Readonly<Record<string, { args: [number, number]; help: string }>> = {
42
43
  "zone-create": { args: [1, 1], help: "zone-create <zone> Primary zone, member of the configured catalog" },
43
44
  "zone-delete": { args: [1, 1], help: "zone-delete <zone> delete a zone and every record in it" },
44
45
  "record-add": { args: [3, 40], help: "record-add <zone> <domain> <type> <key=value>... e.g. ipAddress=10.0.40.99 ttl=300" },
45
46
  "record-update": { args: [3, 40], help: "record-update <zone> <domain> <type> <key=value>... e.g. ipAddress=10.0.40.99 newIpAddress=10.0.40.98" },
46
47
  "record-delete": { args: [3, 40], help: "record-delete <zone> <domain> <type> <key=value>... e.g. ipAddress=10.0.40.99" },
48
+ "cluster-init": { args: [2, 2], help: "cluster-init <clusterDomain> <ip[,ip]> make the primary the Primary node of a new cluster" },
49
+ "cluster-delete": { args: [0, 0], help: "cluster-delete remove the cluster from the primary (only without Secondary nodes)" },
50
+ "cluster-remove": { args: [1, 1], help: "cluster-remove <secondaryNodeId> ask a Secondary node to leave the cluster" },
51
+ "server-domain": { args: [1, 1], help: "server-domain <name> DNS Server Domain of the target node (also with node)" },
47
52
  };
48
53
 
49
54
  const HELP = `dns specialist
50
55
 
51
- technitium <primary|secondary> <read> [args]
56
+ technitium primary <command> [args] the cluster primary
57
+ technitium node <fqdn> <command> [args] another cluster node, through the primary (reads and server-domain)
58
+ reads:
52
59
  ${Object.values(TECHNITIUM_READS)
53
60
  .map((r) => ` ${r.help}`)
54
61
  .join("\n")}
55
- technitium primary <write> [args] (the secondary follows through the catalog zone)
62
+ writes (primary; the other nodes follow through the catalog zone and the cluster):
56
63
  ${Object.values(TECHNITIUM_WRITES)
57
64
  .map((w) => ` ${w.help}`)
58
65
  .join("\n")}
@@ -67,7 +74,8 @@ ${Object.values(TECHNITIUM_WRITES)
67
74
  export interface TechnitiumRequest {
68
75
  path: string;
69
76
  params: Record<string, string>;
70
- write: boolean;
77
+ /** Refused when another node is targeted. */
78
+ primaryOnly: boolean;
71
79
  }
72
80
 
73
81
  export function assertName(value: string | undefined, what: string): string {
@@ -97,28 +105,28 @@ export function technitiumRequest(catalog: string, args: string[]): TechnitiumRe
97
105
  }
98
106
  switch (name) {
99
107
  case "zones":
100
- return { path: "/api/zones/list", params: rest[0] === undefined ? {} : { filterName: rest[0] }, write: false };
108
+ return { path: "/api/zones/list", params: rest[0] === undefined ? {} : { filterName: rest[0] }, primaryOnly: false };
101
109
  case "records": {
102
110
  const zone = assertName(rest[0], "zone");
103
111
  const domain = rest[1] === undefined ? zone : assertName(rest[1], "domain");
104
- return { path: "/api/zones/records/get", params: { domain, zone, listZone: rest[1] === undefined ? "true" : "false" }, write: false };
112
+ return { path: "/api/zones/records/get", params: { domain, zone, listZone: rest[1] === undefined ? "true" : "false" }, primaryOnly: false };
105
113
  }
106
114
  case "zone-options":
107
- return { path: "/api/zones/options/get", params: { zone: assertName(rest[0], "zone") }, write: false };
115
+ return { path: "/api/zones/options/get", params: { zone: assertName(rest[0], "zone") }, primaryOnly: false };
108
116
  case "resolve": {
109
117
  const type = rest[1] ?? "A";
110
118
  if (!RECORD_TYPE.test(type)) throw new UsageError("type must be a record type such as A, AAAA, CNAME, TXT");
111
- return { path: "/api/dnsClient/resolve", params: { server: "this-server", domain: assertName(rest[0], "domain"), type }, write: false };
119
+ return { path: "/api/dnsClient/resolve", params: { server: "this-server", domain: assertName(rest[0], "domain"), type }, primaryOnly: false };
112
120
  }
113
121
  case "stats": {
114
122
  const type = rest[0] ?? "LastHour";
115
123
  if (!STATS_TYPES.includes(type)) throw new UsageError(`stats type must be one of ${STATS_TYPES.join(", ")}`);
116
- return { path: "/api/dashboard/stats/get", params: { type }, write: false };
124
+ return { path: "/api/dashboard/stats/get", params: { type }, primaryOnly: false };
117
125
  }
118
126
  case "zone-create":
119
- return { path: "/api/zones/create", params: { zone: assertName(rest[0], "zone"), type: "Primary", catalog }, write: true };
127
+ return { path: "/api/zones/create", params: { zone: assertName(rest[0], "zone"), type: "Primary", catalog }, primaryOnly: true };
120
128
  case "zone-delete":
121
- return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, write: true };
129
+ return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, primaryOnly: true };
122
130
  case "record-add":
123
131
  case "record-update":
124
132
  case "record-delete": {
@@ -129,8 +137,27 @@ export function technitiumRequest(catalog: string, args: string[]): TechnitiumRe
129
137
  for (const fixed of ["zone", "domain", "type"]) {
130
138
  if (fixed in params) throw new UsageError(`${fixed} is a positional argument`);
131
139
  }
132
- return { path: `/api/zones/records/${name.slice("record-".length)}`, params: { ...params, zone, domain, type: rest[2] }, write: true };
140
+ return { path: `/api/zones/records/${name.slice("record-".length)}`, params: { ...params, zone, domain, type: rest[2] }, primaryOnly: true };
141
+ }
142
+ case "cluster-state":
143
+ return { path: "/api/admin/cluster/state", params: { includeServerIpAddresses: "true" }, primaryOnly: false };
144
+ case "settings":
145
+ return { path: "/api/settings/get", params: {}, primaryOnly: false };
146
+ case "cluster-init": {
147
+ if (!IP_LIST.test(rest[1])) throw new UsageError("cluster-init needs a comma separated list of IP addresses");
148
+ return {
149
+ path: "/api/admin/cluster/init",
150
+ params: { clusterDomain: assertName(rest[0], "clusterDomain"), primaryNodeIpAddresses: rest[1] },
151
+ primaryOnly: true,
152
+ };
133
153
  }
154
+ case "cluster-delete":
155
+ return { path: "/api/admin/cluster/primary/delete", params: { forceDelete: "false" }, primaryOnly: true };
156
+ case "cluster-remove":
157
+ if (!NODE_ID.test(rest[0])) throw new UsageError("cluster-remove needs the numeric Secondary node id from cluster-state");
158
+ return { path: "/api/admin/cluster/primary/removeSecondary", params: { secondaryNodeId: rest[0] }, primaryOnly: true };
159
+ case "server-domain":
160
+ return { path: "/api/settings/set", params: { dnsServerDomain: assertName(rest[0], "server domain") }, primaryOnly: false };
134
161
  default:
135
162
  throw new UsageError(`unknown technitium command: ${name}`);
136
163
  }
@@ -142,17 +169,28 @@ interface TechnitiumResponse {
142
169
  response?: unknown;
143
170
  }
144
171
 
172
+ /** Splits `primary <command>` or `node <fqdn> <command>` into the target node (undefined for the primary) and the command. */
173
+ export function technitiumTarget(args: string[]): { node: string | undefined; rest: string[] } {
174
+ if (args[0] === "primary") return { node: undefined, rest: args.slice(1) };
175
+ if (args[0] === "node") {
176
+ const node = assertName(args[1], "node");
177
+ if (!node.includes(".")) throw new UsageError("node must be the node's domain name, e.g. technitium2.dns.home.arpa");
178
+ return { node, rest: args.slice(2) };
179
+ }
180
+ throw new UsageError("technitium primary <command> [args] | technitium node <fqdn> <command> [args]");
181
+ }
182
+
145
183
  async function technitium(config: DnsConfig, args: string[]): Promise<number> {
146
- const node = args[0];
147
- if (!NODES.includes(node as Node)) throw new UsageError(`technitium <${NODES.join("|")}> <command> [args]`);
148
- const request = technitiumRequest(config.technitiumCatalog, args.slice(1));
149
- if (request.write && node !== "primary") throw new UsageError("writes go to the primary; the secondary follows through the catalog zone");
150
- const base = node === "primary" ? config.technitiumPrimaryUrl : config.technitiumSecondaryUrl;
151
- const token = readSecret(SERVICE, node === "primary" ? "TECHNITIUM_TOKEN" : "TECHNITIUM2_TOKEN");
152
- const response = await fetch(new URL(request.path, base), {
184
+ const { node, rest } = technitiumTarget(args);
185
+ const request = technitiumRequest(config.technitiumCatalog, rest);
186
+ 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
+ const params = node === undefined ? request.params : { ...request.params, node };
188
+ const token = readSecret(SERVICE, "TECHNITIUM_TOKEN");
189
+ const target = node ?? "primary";
190
+ const response = await fetch(new URL(request.path, config.technitiumPrimaryUrl), {
153
191
  method: "POST",
154
192
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
155
- body: new URLSearchParams(request.params),
193
+ body: new URLSearchParams(params),
156
194
  signal: AbortSignal.timeout(TIMEOUT_MS),
157
195
  });
158
196
  const text = await response.text();
@@ -160,12 +198,12 @@ async function technitium(config: DnsConfig, args: string[]): Promise<number> {
160
198
  try {
161
199
  parsed = JSON.parse(text) as TechnitiumResponse;
162
200
  } catch {
163
- throw new ServiceError(`Technitium ${node} answered ${response.status} with a non-JSON body`);
201
+ throw new ServiceError(`Technitium ${target} answered ${response.status} with a non-JSON body`);
164
202
  }
165
203
  if (parsed.status !== "ok") {
166
- throw new ServiceError(`Technitium ${node}: ${parsed.status ?? response.status}${parsed.errorMessage ? `: ${parsed.errorMessage}` : ""}`);
204
+ throw new ServiceError(`Technitium ${target}: ${parsed.status ?? response.status}${parsed.errorMessage ? `: ${parsed.errorMessage}` : ""}`);
167
205
  }
168
- printJson({ node, status: parsed.status, response: redactSecrets(parsed.response ?? null) });
206
+ printJson({ node: target, status: parsed.status, response: redactSecrets(parsed.response ?? null) });
169
207
  return 0;
170
208
  }
171
209
 
@@ -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, command as dnsCommand } from "./dns/run.ts";
7
+ import { 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";
@@ -163,12 +163,12 @@ describe("network wrapper", () => {
163
163
 
164
164
  describe("dns wrapper", () => {
165
165
  it("maps technitium commands to documented API paths", () => {
166
- expect(technitiumRequest("catalog.invalid", ["zones"])).toEqual({ path: "/api/zones/list", params: {}, write: false });
167
- expect(technitiumRequest("catalog.invalid", ["zones", "*.37pla.net"])).toEqual({ path: "/api/zones/list", params: { filterName: "*.37pla.net" }, write: false });
166
+ expect(technitiumRequest("catalog.invalid", ["zones"])).toEqual({ path: "/api/zones/list", params: {}, primaryOnly: false });
167
+ expect(technitiumRequest("catalog.invalid", ["zones", "*.37pla.net"])).toEqual({ path: "/api/zones/list", params: { filterName: "*.37pla.net" }, primaryOnly: false });
168
168
  expect(technitiumRequest("catalog.invalid", ["records", "37pla.net"])).toEqual({
169
169
  path: "/api/zones/records/get",
170
170
  params: { domain: "37pla.net", zone: "37pla.net", listZone: "true" },
171
- write: false,
171
+ primaryOnly: false,
172
172
  });
173
173
  expect(technitiumRequest("catalog.invalid", ["records", "37pla.net", "kuma.37pla.net"]).params.listZone).toBe("false");
174
174
  expect(technitiumRequest("catalog.invalid", ["resolve", "auth.37pla.net"]).params).toEqual({ server: "this-server", domain: "auth.37pla.net", type: "A" });
@@ -176,16 +176,36 @@ describe("dns wrapper", () => {
176
176
  expect(technitiumRequest("catalog.invalid", ["zone-create", "lab.test"])).toEqual({
177
177
  path: "/api/zones/create",
178
178
  params: { zone: "lab.test", type: "Primary", catalog: "catalog.invalid" },
179
- write: true,
179
+ primaryOnly: true,
180
180
  });
181
181
  expect(technitiumRequest("catalog.invalid", ["record-add", "37pla.net", "kuma.37pla.net", "A", "ipAddress=10.0.40.30", "ttl=300"])).toEqual({
182
182
  path: "/api/zones/records/add",
183
183
  params: { ipAddress: "10.0.40.30", ttl: "300", zone: "37pla.net", domain: "kuma.37pla.net", type: "A" },
184
- write: true,
184
+ primaryOnly: true,
185
185
  });
186
186
  expect(technitiumRequest("catalog.invalid", ["record-delete", "37pla.net", "kuma.37pla.net", "A", "ipAddress=10.0.40.30"]).path).toBe("/api/zones/records/delete");
187
187
  });
188
188
 
189
+ it("maps cluster and settings commands", () => {
190
+ expect(technitiumRequest("c", ["cluster-state"])).toEqual({ path: "/api/admin/cluster/state", params: { includeServerIpAddresses: "true" }, primaryOnly: false });
191
+ expect(technitiumRequest("c", ["settings"])).toEqual({ path: "/api/settings/get", params: {}, primaryOnly: false });
192
+ expect(technitiumRequest("c", ["cluster-init", "dns.home.arpa", "10.0.40.53"])).toEqual({
193
+ path: "/api/admin/cluster/init",
194
+ params: { clusterDomain: "dns.home.arpa", primaryNodeIpAddresses: "10.0.40.53" },
195
+ primaryOnly: true,
196
+ });
197
+ expect(technitiumRequest("c", ["cluster-delete"]).params).toEqual({ forceDelete: "false" });
198
+ expect(technitiumRequest("c", ["cluster-remove", "811905692"]).params).toEqual({ secondaryNodeId: "811905692" });
199
+ expect(technitiumRequest("c", ["server-domain", "technitium1"])).toEqual({ path: "/api/settings/set", params: { dnsServerDomain: "technitium1" }, primaryOnly: false });
200
+ });
201
+
202
+ it("targets the primary or another node by domain name", () => {
203
+ expect(technitiumTarget(["primary", "zones"])).toEqual({ node: undefined, rest: ["zones"] });
204
+ expect(technitiumTarget(["node", "technitium2.dns.home.arpa", "zones"])).toEqual({ node: "technitium2.dns.home.arpa", rest: ["zones"] });
205
+ expect(() => technitiumTarget(["secondary", "zones"])).toThrow(UsageError);
206
+ expect(() => technitiumTarget(["node", "technitium2", "zones"])).toThrow(/domain name/);
207
+ });
208
+
189
209
  it("rejects malformed names, types, and parameters", () => {
190
210
  expect(() => technitiumRequest("c", ["records", "bad zone"])).toThrow(/DNS name/);
191
211
  expect(() => technitiumRequest("c", ["record-add", "z.test", "a.z.test", "a", "ipAddress=1.2.3.4"])).toThrow(/record type/);
@@ -194,7 +214,9 @@ describe("dns wrapper", () => {
194
214
  expect(() => technitiumRequest("c", ["record-add", "z.test", "a.z.test", "A", "zone=other"])).toThrow(/positional/);
195
215
  expect(() => technitiumRequest("c", ["stats", "Forever"])).toThrow(/stats type/);
196
216
  expect(() => technitiumRequest("c", ["zone-delete"])).toThrow(/1 argument/);
197
- expect(() => technitiumRequest("c", ["settings"])).toThrow(/unknown technitium command/);
217
+ expect(() => technitiumRequest("c", ["flush"])).toThrow(/unknown technitium command/);
218
+ expect(() => technitiumRequest("c", ["cluster-init", "dns.home.arpa", "10.0.40.53;rm"])).toThrow(/IP addresses/);
219
+ expect(() => technitiumRequest("c", ["cluster-remove", "node2"])).toThrow(/numeric/);
198
220
  expect(parseParams(["comments=a=b"])).toEqual({ comments: "a=b" });
199
221
  });
200
222