home-assistant: a new MQTT entry says plain MQTT for its certificate choices

Home Assistant's MQTT user flow shows no value for set_ca_cert and set_client_cert (a reconfigure pre-fills them from the entry), and refuses a submit without them — found against the pinned 2026.9.3 in a throwaway instance.
home-assistant: its broker and its Sonarr, Radarr and Lidarr come from the mesh
2026-09-30 13:11:40 +02:00 · 2026-09-30 13:01:14 +02:00 · 2026-09-30 12:49:55 +02:00 · 2026-09-30 00:39:19 +02:00 · 2026-09-30 00:39:19 +02:00 · 2026-09-30 00:25:55 +02:00
42 changed files with 1984 additions and 1430 deletions
@@ -94,7 +94,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BAZARR_URL": "http://127.0.0.1:6767",
+        "MESH_BAZARR_URL": "http://127.0.0.1:${port:6767}",
        "MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
        "MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
        "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"
@@ -76,7 +76,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:${port:8787}",
        "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
      },
      "artifact": "runtime"
@@ -5,7 +5,7 @@
    "alert.firing"
  ],
  "own-secrets": {
-    "admin": "/var/lib/mesh/grafana/admin",
+    "admin": "/var/lib/grafana-module/admin.secret",
    "broker": "/var/lib/mesh/grafana/broker"
  },
  "capabilities": [
@@ -30,87 +30,45 @@
    {
      "id": "state",
      "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/grafana-module",
-      "place": "."
+      "mode": "0700"
    },
    {
      "id": "data",
      "type": "directory",
      "path": "/services/grafana/data",
      "mode": "0700",
      "owner": "472:472"
    },
    {
-      "id": "admin-secret",
+      "id": "server-env",
      "type": "file",
-      "path": "${dir:state}/admin.secret",
+      "path": "/var/lib/grafana-module/server.env",
-      "mode": "0400",
+      "mode": "0600",
-      "owner": "472:472",
+      "content": "GF_SECURITY_ADMIN_PASSWORD=${secret:admin}\n"
      "content": "${secret:admin}"
    },
    {
      "id": "oidc-secret",
      "type": "file",
      "path": "${dir:state}/oidc-client.secret",
      "mode": "0400",
      "owner": "472:472",
      "content": "${secret:oidc-client}"
    },
    {
      "id": "oidc-env",
      "type": "file",
      "path": "${dir:state}/oidc.env",
      "mode": "0644",
      "content": "GF_SERVER_ROOT_URL=https://${bound:route:name}\nGF_AUTH_GENERIC_OAUTH_ENABLED=true\nGF_AUTH_GENERIC_OAUTH_NAME=Keycloak\nGF_AUTH_GENERIC_OAUTH_CLIENT_ID=${bound:oidc-client:as}\nGF_AUTH_GENERIC_OAUTH_CLIENT_SECRET__FILE=/run/secrets/oidc-client\nGF_AUTH_GENERIC_OAUTH_SCOPES=openid email profile roles\nGF_AUTH_GENERIC_OAUTH_AUTH_URL=${bound:oidc-client:issuer}${bound:oidc-client:authorization-path}\nGF_AUTH_GENERIC_OAUTH_TOKEN_URL=${bound:oidc-client:issuer}${bound:oidc-client:token-path}\nGF_AUTH_GENERIC_OAUTH_API_URL=${bound:oidc-client:issuer}${bound:oidc-client:userinfo-path}\nGF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH=contains(roles[*], 'admin') && 'Admin' || contains(realm_access.roles[*], 'admin') && 'Admin' || 'Viewer'\nGF_AUTH_GENERIC_OAUTH_USE_PKCE=true\nGF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=true\nGF_AUTH_GENERIC_OAUTH_ALLOW_ASSIGN_GRAFANA_ADMIN=true\n"
    },
    {
      "id": "influxdb-secret",
      "type": "file",
      "path": "${dir:state}/influxdb-api.secret",
      "mode": "0400",
      "owner": "472:472",
      "content": "${secret:influxdb-api}"
    },
    {
      "id": "influxdb-datasource",
      "type": "file",
      "path": "${dir:state}/datasource-influxdb.yaml",
      "mode": "0644",
      "content": "apiVersion: 1\n# Written by the mesh from grafana's influxdb-api binding; grafana reads it at start. Its own name and\n# uid, so a data source somebody made in the UI is never overwritten, and read-only in the UI because\n# the mesh resets it. The password is read from the file the mesh delivers, never written here.\ndatasources:\n  - name: InfluxDB (mesh)\n    uid: mesh-influxdb-api\n    type: influxdb\n    access: proxy\n    url: ${bound:influxdb-api:scheme}://${bound:influxdb-api:at}:${bound:influxdb-api:port}\n    user: ${bound:influxdb-api:as}\n    isDefault: false\n    editable: false\n    jsonData:\n      dbName: ${bound:influxdb-api:bucket}\n      httpMode: POST\n    secureJsonData:\n      password: $__file{/run/secrets/influxdb-api}\n"
    },
    {
      "id": "server",
      "type": "container",
      "name": "grafana",
-      "image": "grafana/grafana@sha256:ac461fb352abc50da10a51c7d02462e9c05488f11f53f14b3ad79a8145f638a0",
+      "image": "grafana/grafana@sha256:f772d434e8fab0049deb2b1b30abd43342bcfca1537614aa8d36080232cf4283",
      "ports": [
        "3000"
      ],
      "volumes": [
-        "${dir:data}:/var/lib/grafana",
+        "/services/grafana/data:/var/lib/grafana"
        "${dir:state}/admin.secret:/run/secrets/admin:ro",
        "${dir:state}/oidc-client.secret:/run/secrets/oidc-client:ro",
        "${dir:state}/influxdb-api.secret:/run/secrets/influxdb-api:ro",
        "${dir:state}/datasource-influxdb.yaml:/etc/grafana/provisioning/datasources/mesh-influxdb.yaml:ro"
      ],
      "env": {
        "GF_SECURITY_ADMIN_PASSWORD__FILE": "/run/secrets/admin"
      },
      "env-file": [
-        "${dir:state}/oidc.env"
+        "/var/lib/grafana-module/server.env"
      ],
-      "restart-on": [
+      "secrets-in-environment": "grafana honours GF_SECURITY_ADMIN_PASSWORD__FILE; convertible, awaiting a bed that exercises the admin password (assigned-grafana serves tools only)"
        "oidc-env",
        "oidc-secret",
        "influxdb-datasource",
        "influxdb-secret"
      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
      "path": "/var/lib/mesh/grafana/config.json",
      "mode": "0600",
-      "content": "{\n  \"user\": \"admin\",\n  \"password\": \"${secret:admin}\"\n}\n",
+      "content": "{}\n",
      "merge": "json"
    },
    {
@@ -124,7 +82,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
+        "MESH_GRAFANA_URL": "http://127.0.0.1:3000",
        "MESH_GRAFANA_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
@@ -134,32 +92,16 @@
    }
  ],
  "requires": [
-    "route",
+    "route"
    "oidc-client",
    "influxdb-api"
  ],
  "contributes": {
    "route": {
      "label": "grafana",
      "endpoint": "web"
    },
    "oidc-client": {
      "label": "grafana",
      "endpoint": "web",
      "callback": "/login/generic_oauth"
    },
    "influxdb-api": {
      "access": "read"
    }
  },
  "binds": {
-    "route": "${dir:state}/route.json",
+    "route": "/var/lib/mesh/grafana/route.json"
    "oidc-client": "${dir:state}/oidc.json",
    "influxdb-api": "${dir:state}/influxdb.json"
  },
  "secrets": {
    "oidc-client": "/var/lib/mesh/grafana/oidc-client",
    "influxdb-api": "/var/lib/mesh/grafana/influxdb-api"
  },
  "build": {
    "on": [
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/home-assistant
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/home-assistant/dist /app/modules/home-assistant/d
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/home-assistant/dist/index.js,/app/modules/home-assistant/dist/tools/index.js
 # NOT dist/provisions/index.js: that is a step the host runs to completion, named by the
 # `provisions` container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run
 # inside the serving sidecar too, and exit it.
@@ -18,7 +18,21 @@
      "port": 8123,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the dashboard and the API"
+      "why": "the dashboard, the API and the companion apps"
    },
    {
      "name": "sonos-events",
      "port": 1400,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the Sonos integration's event callback: speakers push their state changes here"
    },
    {
      "name": "webrtc",
      "port": 18555,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the bundled go2rtc's WebRTC port, which camera streams to a browser use"
    }
  ],
  "resources": [
@@ -28,24 +42,33 @@
      "path": "/var/lib/mesh/home-assistant",
      "mode": "0700"
    },
    {
      "id": "state",
      "type": "directory",
      "mode": "0700",
      "place": "."
    },
    {
      "id": "config",
      "type": "directory",
-      "path": "/services/home-assistant/config",
+      "mode": "0700"
-      "mode": "0700",
+    },
-      "owner": "1000:1000"
+    {
      "id": "written",
      "type": "directory",
      "mode": "0700"
    },
    {
      "id": "server",
      "type": "container",
      "name": "home-assistant",
-      "image": "ghcr.io/home-assistant/home-assistant@sha256:14931c6b13756317849f46da1d01b45937a1150db66c081cfe529d48215943fe",
+      "image": "ghcr.io/home-assistant/home-assistant@sha256:d8922685169707fd91e8b9729902d975f06157d005e422874d201e0261dda196",
      "network": "host",
      "env": {
        "TZ": "Etc/UTC"
      },
      "volumes": [
-        "/services/home-assistant/config:/config"
+        "${dir:config}:/config"
      ]
    },
    {
@@ -64,33 +87,90 @@
      "volumes": [
        "/var/lib/mesh/home-assistant/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/home-assistant/token:/run/secrets/token:ro",
-        "/var/lib/mesh/home-assistant/config.json:/run/config/config.json:ro",
+        "/var/lib/mesh/home-assistant/config.json:/run/config/config.json:ro"
        "/services/home-assistant/config:/var/lib/home-assistant/config:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:8123",
+        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
        "MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
-        "MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json",
+        "MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json"
        "MESH_HOMEASSISTANT_CONFIG_DIR": "/var/lib/home-assistant/config"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
    },
    {
      "id": "provisions",
      "type": "container",
      "name": "mesh-home-assistant-provisions",
      "network": "host",
      "run-once": true,
      "volumes": [
        "/var/lib/mesh/home-assistant/token:/run/secrets/token:ro",
        "${dir:written}:/var/lib/home-assistant-provisions",
        "${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
        "${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
        "${dir:state}/sonarr-api.json:/run/provisions/sonarr-api.json:ro",
        "${dir:state}/sonarr-api.secret:/run/provisions/sonarr-api.secret:ro",
        "${dir:state}/radarr-api.json:/run/provisions/radarr-api.json:ro",
        "${dir:state}/radarr-api.secret:/run/provisions/radarr-api.secret:ro",
        "${dir:state}/lidarr-api.json:/run/provisions/lidarr-api.json:ro",
        "${dir:state}/lidarr-api.secret:/run/provisions/lidarr-api.secret:ro"
      ],
      "env": {
        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
        "MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
        "MESH_PROVISIONS_DIR": "/run/provisions",
        "MESH_WRITTEN_DIR": "/var/lib/home-assistant-provisions"
      },
      "args": [
        "run",
        "/app/modules/home-assistant/dist/provisions/index.js"
      ],
      "restart-on": [
        "bound-mqtt-topic",
        "secret-mqtt-topic",
        "bound-sonarr-api",
        "secret-sonarr-api",
        "bound-radarr-api",
        "secret-radarr-api",
        "bound-lidarr-api",
        "secret-lidarr-api"
      ],
      "artifact": "runtime"
    }
  ],
  "requires": [
-    "route"
+    "lidarr-api",
    "mqtt-topic",
    "radarr-api",
    "route",
    "sonarr-api"
  ],
  "contributes": {
    "mqtt-topic": {
      "topics": [
        "#"
      ]
    },
    "route": {
      "label": "home-assistant",
      "endpoint": "web"
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/home-assistant/route.json"
+    "route": "${dir:state}/route.json",
    "mqtt-topic": "${dir:state}/mqtt-topic.json",
    "sonarr-api": "${dir:state}/sonarr-api.json",
    "radarr-api": "${dir:state}/radarr-api.json",
    "lidarr-api": "${dir:state}/lidarr-api.json"
  },
  "secrets": {
    "mqtt-topic": "${dir:state}/mqtt-topic.secret",
    "sonarr-api": "${dir:state}/sonarr-api.secret",
    "radarr-api": "${dir:state}/radarr-api.secret",
    "lidarr-api": "${dir:state}/lidarr-api.secret"
  },
  "build": {
    "on": [
@@ -1,9 +1,14 @@
 {
  "name": "@novox/module-home-assistant",
  "version": "0.1.0",
-  "description": "home-assistant — home automation platform. Its API client, tools and events live here (novox/hq ADR 0039).",
+  "description": "home-assistant \u2014 home automation platform. Its API client, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
    "typecheck": "tsc -p tsconfig.json",
    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
  },
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
@@ -0,0 +1,486 @@
 // How home-assistant's provisions step brings Home Assistant's integrations in line with what the
 // mesh bound: the MQTT integration to `mqtt-topic`, the Sonarr, Radarr and Lidarr integrations to
 // `sonarr-api`, `radarr-api` and `lidarr-api`. Pure logic over two seams — Home Assistant's config
 // flows (hass.ts) and the broker/apps — so it is tested against fakes (test/provisions.test.ts).
 //
 // The half that reads files and talks HTTP lives beside it (mesh.ts, hass.ts, probe.ts, index.ts).
 import { createHash } from "node:crypto";
 import type { Hass, SchemaField } from "./hass.js";
 import type { Probe } from "./probe.js";
 /** What the mesh wrote at `binds.<provision>` (the controller's binding document). */
 export interface Binding {
  provision?: string;
  from?: string;
  at?: string;
  as?: string;
  serves?: Record<string, unknown>;
 }
 /** How one provision came out. Never carries a credential. */
 export type Outcome =
  | { what: string; result: "unchanged"; note?: string }
  | { what: string; result: "written"; fields: string[]; note?: string }
  | { what: string; result: "equivalent"; note: string }
  | { what: string; result: "refused"; problem: string };
 /** A port the binding serves, or undefined when it names none usable. */
 export function portOf(serves: Record<string, unknown> | undefined): number | undefined {
  const port = Number(serves?.port);
  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : undefined;
 }
 /** A host as it goes into a URL: an IPv6 literal bracketed. */
 export function urlHost(host: string): string {
  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 /**
 * What this step last wrote, per target, as a digest: the only way to know "already as the mesh
 * says" for a credential Home Assistant will not show back. A sha256 over the target and the values,
 * never the values; kept in the module's own placed directory.
 */
 export interface Marks {
  get(name: string): Promise<string | undefined>;
  set(name: string, digest: string): Promise<void>;
 }
 export function digest(...parts: (string | number)[]): string {
  return createHash("sha256").update(parts.map(String).join("\u0000")).digest("hex");
 }
 /** An error as text with the credential taken out, raw and URL-encoded. */
 export function scrub(err: unknown, ...secrets: (string | undefined)[]): string {
  let text = err instanceof Error ? err.message : String(err);
  for (const s of secrets) {
    if (!s) continue;
    for (const form of new Set([s, encodeURIComponent(s)])) text = text.split(form).join("***");
  }
  return text;
 }
 /**
 * What a form would submit if a person pressed "submit" without touching it: each field's
 * suggested value (what Home Assistant pre-fills from the entry), else its default; a section's
 * fields nested under its name. The step lays only the connection fields over this, so every other
 * choice the entry carries is sent back exactly as Home Assistant showed it.
 */
 export function formValues(schema: readonly SchemaField[] | null | undefined): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const field of schema ?? []) {
    if (Array.isArray(field.schema)) {
      out[field.name] = formValues(field.schema);
      continue;
    }
    const suggested = field.description?.suggested_value;
    if (suggested !== undefined && suggested !== null) out[field.name] = suggested;
    else if (field.default !== undefined) out[field.name] = field.default;
  }
  return out;
 }
 /** Whether a form has a field of this name at its top level. */
 export function hasField(schema: readonly SchemaField[] | null | undefined, name: string): boolean {
  return (schema ?? []).some((f) => f.name === name);
 }
 // ---- MQTT ----
 // Home Assistant's MQTT integration, pointed at the broker the mesh bound — `mqtt-topic`.
 //
 // **Why a step.** Home Assistant keeps its broker, login and password in its MQTT config entry
 // (`.storage/core.config_entries`), not in a file the mesh could fill with `${bound:mqtt-topic:at}`.
 // So this reads the binding and the pair credential and makes the entry say the same thing, through
 // the MQTT integration's own reconfigure flow — the flow its "Reconfigure" button runs, which tests
 // the connection itself and saves nothing it could not connect with.
 //
 // **Only the connection, and only when it differs.** Broker, port, username, password. The protocol
 // version, client id, keepalive, TLS choices and discovery options the entry holds are sent back
 // exactly as Home Assistant pre-filled them. Whether the password already matches cannot be read
 // back (Home Assistant never shows a stored password), so the step keeps a digest of what it last
 // wrote: equal broker/port/username and an equal digest is "already as the mesh says".
 //
 // **Nothing loses its connection without someone seeing it.** Before Home Assistant is touched the
 // broker itself is asked whether it takes the delivered login (the provisioner creates it within
 // seconds of the grant): if not, nothing is written and the step fails saying why, and Home
 // Assistant keeps the login it has — the carried `luffy` on ace, which mosquitto keeps. If Home
 // Assistant's own connection test refuses the new settings, the flow saves nothing, and the step
 // fails with Home Assistant's reason. A login that may not subscribe to the discovery topics is said
 // as a warning: discovery would find nothing.
 export const MQTT_PROVISION = "mqtt-topic";
 /** Home Assistant's discovery prefix, subscribed to whenever discovery is on (the default). */
 export const DISCOVERY_FILTER = "homeassistant/#";
 export interface MqttWanted {
  host: string;
  port: number;
  username: string;
  password: string;
 }
 export type Wanted = { ok: true; want: MqttWanted } | { ok: false; problem: string };
 /** The broker, port and login the mesh says Home Assistant uses. */
 export function wantedMqtt(binding: Binding | undefined, credential: string | undefined): Wanted {
  if (!binding) return { ok: false, problem: `no binding for ${MQTT_PROVISION} was delivered — the mesh writes it before this step runs` };
  const host = typeof binding.at === "string" ? binding.at.trim() : "";
  if (!host) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no host (at)` };
  const port = portOf(binding.serves);
  if (port === undefined) return { ok: false, problem: `the ${MQTT_PROVISION} binding serves no usable port (${String(binding.serves?.port)})` };
  const scheme = binding.serves?.scheme;
  if (scheme !== undefined && scheme !== "mqtt") {
    return { ok: false, problem: `the ${MQTT_PROVISION} binding serves scheme ${String(scheme)}; this step writes plain MQTT` };
  }
  const username = typeof binding.as === "string" ? binding.as.trim() : "";
  if (!username) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no login (as)` };
  const password = (credential ?? "").replace(/\n$/, "");
  if (!password) return { ok: false, problem: `the ${MQTT_PROVISION} credential is empty or was not delivered` };
  return { ok: true, want: { host, port, username, password } };
 }
 export interface MqttDeps {
  hass: Hass;
  probe: Probe;
  marks: Marks;
 }
 const markFor = (entryId: string, w: MqttWanted): string => digest("mqtt", entryId, w.host, w.port, w.username, w.password);
 /** Bring Home Assistant's MQTT entry in line with the mesh. Never throws: every failure is an outcome. */
 export async function reconcileMqtt(deps: MqttDeps, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
  const what = "mqtt";
  const w = wantedMqtt(binding, credential);
  if ("problem" in w) return { what, result: "refused", problem: w.problem };
  const want = w.want;
  // The broker first: a login it does not take is never written into Home Assistant.
  let note: string | undefined;
  try {
    const probe = await deps.probe(want.host, want.port, want.username, want.password, DISCOVERY_FILTER);
    if (probe.connack === 4 || probe.connack === 5) {
      return {
        what,
        result: "refused",
        problem:
          `the broker at ${want.host}:${want.port} does not (yet) take the login ${want.username} with the delivered ` +
          `password (CONNACK ${probe.connack}); mosquitto's provisioner creates it from the grant — nothing was ` +
          `written, and Home Assistant keeps the broker login it has`,
      };
    }
    if (probe.connack !== 0) {
      return { what, result: "refused", problem: `the broker at ${want.host}:${want.port} answered CONNACK ${probe.connack}; nothing was written` };
    }
    if (probe.suback === 0x80) {
      note =
        `warning: ${want.username} may not subscribe to ${DISCOVERY_FILTER} — MQTT discovery will find nothing; ` +
        `grant it with the mqtt-topic contribution's \`topics\``;
    }
  } catch (err) {
    return {
      what,
      result: "refused",
      problem: `the broker at ${want.host}:${want.port} could not be asked: ${scrub(err, want.password)}; nothing was written`,
    };
  }
  try {
    const entries = (await deps.hass.entries("mqtt")).filter((e) => e.domain === "mqtt");
    if (entries.length > 1) {
      return { what, result: "refused", problem: `Home Assistant has ${entries.length} MQTT entries; which one the mesh owns is not guessed` };
    }
    if (entries.length === 0) return await createEntry(deps, want, note);
    const entry = entries[0];
    const flow = await deps.hass.startFlow("mqtt", entry.entry_id);
    if (flow.type !== "form" || !flow.flow_id || !flow.data_schema) {
      if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
      return { what, result: "refused", problem: `Home Assistant's MQTT reconfigure flow answered ${flow.type}${flow.reason ? ` (${flow.reason})` : ""}` };
    }
    const current = formValues(flow.data_schema);
    const fields: string[] = [];
    if (String(current.broker ?? "") !== want.host) fields.push("broker");
    if (Number(current.port ?? 0) !== want.port) fields.push("port");
    if (String(current.username ?? "") !== want.username) fields.push("username");
    if ((await deps.marks.get("mqtt")) !== markFor(entry.entry_id, want)) fields.push("password");
    if (fields.length === 0) {
      await deps.hass.abortFlow(flow.flow_id);
      return note ? { what, result: "unchanged", note } : { what, result: "unchanged" };
    }
    const saved = await deps.hass.stepFlow(flow.flow_id, {
      ...current,
      broker: want.host,
      port: want.port,
      username: want.username,
      password: want.password,
    });
    if (saved.type === "abort" && saved.reason === "reconfigure_successful") {
      await deps.marks.set("mqtt", markFor(entry.entry_id, want));
      return { what, result: "written", fields, ...(note ? { note } : {}) };
    }
    if (saved.flow_id) await deps.hass.abortFlow(saved.flow_id);
    return {
      what,
      result: "refused",
      problem:
        `Home Assistant's own connection test refused ${want.username}@${want.host}:${want.port} ` +
        `(${describe(saved)}); its MQTT entry is unchanged`,
    };
  } catch (err) {
    return { what, result: "refused", problem: scrub(err, want.password) };
  }
 }
 /** A fresh Home Assistant has no MQTT entry: made through the integration's user flow. */
 async function createEntry(deps: MqttDeps, want: MqttWanted, note?: string): Promise<Outcome> {
  const what = "mqtt";
  let flow = await deps.hass.startFlow("mqtt");
  if (flow.type === "form" && flow.step_id !== "broker" && flow.flow_id) {
    // Anything before the broker form (none outside the Supervisor) is not this step's to answer.
    await deps.hass.abortFlow(flow.flow_id);
    return { what, result: "refused", problem: `Home Assistant's MQTT user flow asked ${flow.step_id} before the broker` };
  }
  if (flow.type !== "form" || !flow.flow_id) {
    return { what, result: "refused", problem: `Home Assistant's MQTT user flow answered ${describe(flow)}` };
  }
  const shown = formValues(flow.data_schema);
  // A new entry's form has no value for its two certificate choices (a reconfigure pre-fills them
  // from the entry): plain MQTT, so neither a CA nor a client certificate.
  const other = (shown.other_settings ?? {}) as Record<string, unknown>;
  if (flow.data_schema?.some((f) => f.name === "other_settings")) {
    shown.other_settings = { set_ca_cert: "off", set_client_cert: false, ...other };
  }
  flow = await deps.hass.stepFlow(flow.flow_id, {
    ...shown,
    broker: want.host,
    port: want.port,
    username: want.username,
    password: want.password,
  });
  if (flow.type === "create_entry") {
    const id = (flow.result as { entry_id?: string } | undefined)?.entry_id;
    if (id) await deps.marks.set("mqtt", markFor(id, want));
    return { what, result: "written", fields: ["entry"], ...(note ? { note } : {}) };
  }
  if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
  return { what, result: "refused", problem: `Home Assistant refused a new MQTT entry for ${want.host}:${want.port} (${describe(flow)})` };
 }
 export function describe(r: { type: string; reason?: string; errors?: Record<string, string> | null }): string {
  const errors = r.errors ? Object.entries(r.errors).map(([k, v]) => `${k}: ${v}`).join(", ") : "";
  return [r.type, r.reason, errors].filter(Boolean).join(" — ");
 }
 // ---- Sonarr, Radarr, Lidarr ----
 // Home Assistant's Sonarr, Radarr and Lidarr integrations, pointed at the apps the mesh bound —
 // `sonarr-api`, `radarr-api`, `lidarr-api` (their providers: mesh-catalog #156).
 //
 // **What Home Assistant lets anyone change, and what it does not.** Each integration keeps a URL and
 // an API key in its config entry. None of the three has a reconfigure flow: Home Assistant changes
 // them only through the flow its UI runs —
 //   - a **user flow** makes a new entry (validated against the app);
 //   - a **reauth flow**, which Home Assistant starts by itself when the app refuses the key it holds,
 //     takes a new key (Sonarr) or a new URL and key (Radarr, Lidarr);
 //   - anything else — the URL of a working entry — only by removing the integration and adding it
 //     again, which throws away its entities' names, areas and history links. **This step never
 //     removes an entry.**
 // So, per app:
 //   1. The bound key is tried against the bound app first. Refused, nothing is written: until the
 //      operator accepts the app's own key for this pair, the mesh delivers a value it minted, which
 //      no Servarr app takes (novox/hq ADR 0092) — the failure names the `secret accept` that fixes it.
 //   2. No entry: one is made through the user flow.
 //   3. A reauth flow Home Assistant started for the entry: finished with the bound key (and URL,
 //      where the integration's reauth asks for one).
 //   4. An entry whose URL (read from the device the integration registered, `configuration_url`)
 //      is the bound one and which is loaded: already as the mesh says. The key needs no digest here:
 //      a Servarr app has one key, so an entry loaded against the app holds the key the app took.
 //   5. A working entry at a different URL that reaches **the same app** — the same process, by the
 //      app's own status (start time, data folder, version) — is left as it is and said: ace's entries
 //      say `127.0.0.1:<port>` and the binding says `ace.internal:<port>`, one Sonarr either way.
 //   6. Anything else is refused, loudly, with what the operator can do; nothing is removed.
 export interface ServarrApp {
  /** The integration's domain, also the app. */
  domain: "sonarr" | "radarr" | "lidarr";
  /** The provision it is required as: the `requires`, `binds` and `secrets` key. */
  provision: string;
  /** The app's status endpoint: answers 401 to a wrong key, and says which process answered. */
  statusPath: string;
 }
 export const APPS: readonly ServarrApp[] = [
  { domain: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
  { domain: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status" },
  { domain: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
 ];
 /** The HTTP the step needs toward the apps, so a test can stand fakes in. */
 export interface Http {
  fetch(url: string, init?: { method?: string; headers?: Record<string, string> }): Promise<{ status: number; text(): Promise<string> }>;
 }
 export type AppWanted = { ok: true; url: string; key: string; from: string } | { ok: false; problem: string };
 /** The URL and key the mesh says Home Assistant uses for this app. */
 export function wantedApp(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): AppWanted {
  if (!binding) return { ok: false, problem: `no binding for ${spec.provision} was delivered — the mesh writes it before this step runs` };
  const at = typeof binding.at === "string" ? binding.at.trim() : "";
  if (!at) return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
  const port = portOf(binding.serves);
  if (port === undefined) return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(binding.serves?.port)})` };
  const scheme = typeof binding.serves?.scheme === "string" && binding.serves.scheme ? binding.serves.scheme : "http";
  if (scheme !== "http" && scheme !== "https") return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}` };
  const base = typeof binding.serves?.["url-base"] === "string" ? String(binding.serves["url-base"]).trim().replace(/^\/+|\/+$/g, "") : "";
  const key = (credential ?? "").trim();
  if (!key) return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
  return {
    ok: true,
    url: `${scheme}://${urlHost(at)}:${port}${base ? `/${base}` : ""}`,
    key,
    from: typeof binding.from === "string" ? binding.from : "",
  };
 }
 /** Two URLs naming the same place: scheme, host, port (explicit or default) and base path. */
 export function sameUrl(a: string | null | undefined, b: string): boolean {
  if (!a) return false;
  try {
    const x = new URL(a);
    const y = new URL(b);
    const port = (u: URL) => u.port || (u.protocol === "https:" ? "443" : "80");
    const path = (u: URL) => u.pathname.replace(/\/+$/, "");
    return x.protocol === y.protocol && x.hostname.toLowerCase() === y.hostname.toLowerCase() && port(x) === port(y) && path(x) === path(y);
  } catch {
    return false;
  }
 }
 type Status = { taken: true; status: Record<string, unknown> } | { taken: false };
 /** The app's status with this key: `taken: false` when it refuses the key; throws when it cannot be asked. */
 export async function appStatus(http: Http, spec: ServarrApp, url: string, key: string): Promise<Status> {
  const res = await http.fetch(`${url.replace(/\/+$/, "")}${spec.statusPath}`, {
    method: "GET",
    headers: { "X-Api-Key": key, Accept: "application/json" },
  });
  if (res.status === 401 || res.status === 403) return { taken: false };
  if (res.status < 200 || res.status >= 300) throw new Error(`${spec.domain} answered ${res.status} at ${spec.statusPath}`);
  return { taken: true, status: JSON.parse(await res.text()) as Record<string, unknown> };
 }
 /** Whether two status answers came from one running app. */
 export function sameInstance(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
  const facts = ["startTime", "appData", "version"];
  return facts.every((k) => a[k] !== undefined && a[k] !== null && a[k] === b[k]);
 }
 /** The remedy for a refused key, in the controller's words (ADR 0092). */
 export function acceptRemedy(spec: ServarrApp, from: string): string {
  return (
    `${spec.domain} refuses the ${spec.provision} credential the mesh delivered, so nothing was written into ` +
    `Home Assistant. A Servarr app has one API key and the mesh cannot make it: accept ${spec.domain}'s own key ` +
    `for this pair — \`secret accept <this node> home-assistant ${spec.provision} --provider ${from || "<its node>"} ` +
    `--from <file holding ${spec.domain}'s ApiKey>\``
  );
 }
 export interface ServarrDeps {
  hass: Hass;
  http: Http;
 }
 /** The input a Servarr form takes: what it shows, with the URL (where asked) and the key laid over. */
 function servarrInput(schema: readonly SchemaField[] | null | undefined, url: string, key: string): Record<string, unknown> {
  const input = formValues(schema);
  if (hasField(schema, "url")) input.url = url;
  if (hasField(schema, "api_key")) input.api_key = key;
  return input;
 }
 /** Bring Home Assistant's entry for one app in line with the mesh. Never throws. */
 export async function reconcileApp(deps: ServarrDeps, spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
  const what = spec.domain;
  const w = wantedApp(spec, binding, credential);
  if ("problem" in w) return { what, result: "refused", problem: w.problem };
  let bound: Status;
  try {
    bound = await appStatus(deps.http, spec, w.url, w.key);
  } catch (err) {
    return { what, result: "refused", problem: `${spec.domain} could not be asked at ${w.url}: ${scrub(err, w.key)}` };
  }
  if (!bound.taken) return { what, result: "refused", problem: acceptRemedy(spec, w.from) };
  try {
    const entries = (await deps.hass.entries(spec.domain)).filter((e) => e.domain === spec.domain);
    if (entries.length > 1) {
      return { what, result: "refused", problem: `Home Assistant has ${entries.length} ${spec.domain} entries; which one the mesh owns is not guessed` };
    }
    // No entry: made, through the integration's own user flow, which validates the key itself.
    if (entries.length === 0) {
      const flow = await deps.hass.startFlow(spec.domain);
      if (flow.type !== "form" || !flow.flow_id) return { what, result: "refused", problem: `Home Assistant's ${spec.domain} user flow answered ${describe(flow)}` };
      const made = await deps.hass.stepFlow(flow.flow_id, servarrInput(flow.data_schema, w.url, w.key));
      if (made.type === "create_entry") return { what, result: "written", fields: ["entry"] };
      if (made.flow_id) await deps.hass.abortFlow(made.flow_id);
      return { what, result: "refused", problem: `Home Assistant refused a new ${spec.domain} entry at ${w.url} (${describe(made)})` };
    }
    const entry = entries[0];
    if (entry.disabled_by) return { what, result: "unchanged", note: `the ${spec.domain} entry is disabled (by ${entry.disabled_by}); left alone` };
    // A reauth Home Assistant started because the app refused its key: finished with the bound one.
    const reauth = (await deps.hass.flowsInProgress()).find(
      (f) => f.handler === spec.domain && f.context?.source === "reauth" && f.context?.entry_id === entry.entry_id,
    );
    if (reauth) {
      let step = await deps.hass.stepFlow(reauth.flow_id, {}); // reauth_confirm: a confirmation, no fields
      if (step.type === "form" && step.flow_id && step.step_id !== "reauth_confirm") {
        const input = servarrInput(step.data_schema, w.url, w.key);
        const fields = ["api_key", ...(hasField(step.data_schema, "url") ? ["url"] : [])];
        step = await deps.hass.stepFlow(step.flow_id, input);
        if (step.type === "abort" && step.reason === "reauth_successful") return { what, result: "written", fields };
      }
      return { what, result: "refused", problem: `Home Assistant's ${spec.domain} reauth did not take the bound key and URL (${describe(step)})` };
    }
    const device = (await deps.hass.devices()).find((d) => d.config_entries?.includes(entry.entry_id) && d.configuration_url);
    const current = device?.configuration_url ?? undefined;
    if (entry.state === "loaded" && sameUrl(current, w.url)) return { what, result: "unchanged" };
    if (entry.state === "loaded" && current) {
      let there: Status | undefined;
      try {
        there = await appStatus(deps.http, spec, current, w.key);
      } catch {
        there = undefined;
      }
      if (there?.taken && sameInstance(there.status, bound.status)) {
        return {
          what,
          result: "equivalent",
          note:
            `Home Assistant reaches ${spec.domain} at ${current}, the same running app the mesh bound at ${w.url}; ` +
            `Home Assistant has no way to change a working ${spec.domain} entry's URL short of removing it, so it is left as it is`,
        };
      }
    }
    return {
      what,
      result: "refused",
      problem:
        `Home Assistant's ${spec.domain} entry (${entry.state ?? "unknown state"}) points at ${current ?? "an unknown URL"}, ` +
        `not the ${spec.domain} the mesh bound at ${w.url}. Home Assistant only lets a working entry's URL change by ` +
        `removing and re-adding the integration, which this step never does: remove it in Home Assistant ` +
        `(Settings → Devices & services → ${spec.domain}) and the next run adds it at the bound URL`,
    };
  } catch (err) {
    return { what, result: "refused", problem: scrub(err, w.key) };
  }
 }
@@ -0,0 +1,160 @@
 // Home Assistant's own configuration API, as the provisions step uses it — the supported way to
 // change an integration's connection. Home Assistant keeps every integration in
 // `.storage/core.config_entries`, a file it owns and rewrites; the mesh may not write it, and it is
 // not a file the mesh could merge into. What Home Assistant offers instead is the same thing its UI
 // uses: **config flows** over REST (`/api/config/config_entries/flow`) — a user flow creates an
 // entry, a reconfigure flow changes one, a reauth flow (which Home Assistant starts itself when a
 // credential stops working) replaces its credential — each validated by the integration's own
 // connection test before anything is saved. The two things REST does not answer (which flows Home
 // Assistant has started, which device an entry made) come over its WebSocket API.
 //
 // Nothing here reads `.storage`. Authenticated with the module's accepted long-lived access token.
 /** A config entry as `GET /api/config/config_entries/entry` lists it — no data, no credentials. */
 export interface ConfigEntry {
  entry_id: string;
  domain: string;
  title?: string;
  source?: string;
  state?: string;
  disabled_by?: string | null;
 }
 /** One field of a flow's form, as Home Assistant serializes a voluptuous schema. */
 export interface SchemaField {
  name: string;
  type?: string;
  required?: boolean;
  optional?: boolean;
  default?: unknown;
  description?: { suggested_value?: unknown } | null;
  /** A section (`type: "expandable"`) carries its own fields. */
  schema?: SchemaField[];
 }
 /** What a flow answered: another form, an entry made, or the flow ended (abort). */
 export interface FlowResult {
  type: string;
  flow_id?: string;
  handler?: string;
  step_id?: string;
  data_schema?: SchemaField[] | null;
  errors?: Record<string, string> | null;
  reason?: string;
  result?: { entry_id?: string } | unknown;
 }
 /** A flow in progress that Home Assistant started itself (a reauth, a discovery). */
 export interface FlowProgress {
  flow_id: string;
  handler: string;
  step_id?: string;
  context?: { source?: string; entry_id?: string };
 }
 /** A device from the device registry; an integration names where its app is as configuration_url. */
 export interface DeviceEntry {
  id: string;
  config_entries?: string[];
  configuration_url?: string | null;
 }
 export interface Hass {
  entries(domain: string): Promise<ConfigEntry[]>;
  /** A user flow for `handler`, or — given an entry — a reconfigure flow for it. */
  startFlow(handler: string, entryId?: string): Promise<FlowResult>;
  stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult>;
  abortFlow(flowId: string): Promise<void>;
  flowsInProgress(): Promise<FlowProgress[]>;
  devices(): Promise<DeviceEntry[]>;
 }
 /** Home Assistant over HTTP: REST for entries and flows, one short WebSocket session per question. */
 export class HassApi implements Hass {
  private readonly base: string;
  constructor(url: string, private readonly token: string) {
    this.base = url.replace(/\/$/, "");
  }
  private async rest(method: string, path: string, body?: unknown): Promise<unknown> {
    const res = await fetch(`${this.base}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${this.token}`,
        Accept: "application/json",
        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
      },
      body: body !== undefined ? JSON.stringify(body) : undefined,
    });
    const text = await res.text();
    if (!res.ok) {
      // Home Assistant's error text names fields, never echoes their values.
      throw new Error(`Home Assistant ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
    }
    return text ? (JSON.parse(text) as unknown) : undefined;
  }
  async entries(domain: string): Promise<ConfigEntry[]> {
    return ((await this.rest("GET", `/api/config/config_entries/entry?domain=${encodeURIComponent(domain)}`)) ??
      []) as ConfigEntry[];
  }
  async startFlow(handler: string, entryId?: string): Promise<FlowResult> {
    return (await this.rest("POST", "/api/config/config_entries/flow", {
      handler,
      show_advanced_options: true,
      ...(entryId ? { entry_id: entryId } : {}),
    })) as FlowResult;
  }
  async stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult> {
    return (await this.rest("POST", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`, input)) as FlowResult;
  }
  async abortFlow(flowId: string): Promise<void> {
    await this.rest("DELETE", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`).catch(() => undefined);
  }
  async flowsInProgress(): Promise<FlowProgress[]> {
    return (await this.ws("config_entries/flow/progress")) as FlowProgress[];
  }
  async devices(): Promise<DeviceEntry[]> {
    return (await this.ws("config/device_registry/list")) as DeviceEntry[];
  }
  /** One WebSocket command: connect, authenticate, ask, close. */
  private ws(type: string): Promise<unknown> {
    const url = `${this.base.replace(/^http/, "ws")}/api/websocket`;
    return new Promise((resolve, reject) => {
      const socket = new WebSocket(url);
      const timer = setTimeout(() => {
        socket.close();
        reject(new Error(`Home Assistant's WebSocket did not answer ${type} within 30s`));
      }, 30_000);
      const done = (fn: () => void): void => {
        clearTimeout(timer);
        socket.close();
        fn();
      };
      socket.onerror = () => done(() => reject(new Error(`Home Assistant's WebSocket at ${url} failed`)));
      socket.onmessage = (event: { data: unknown }) => {
        const msg = JSON.parse(String(event.data)) as {
          type: string;
          id?: number;
          success?: boolean;
          result?: unknown;
          error?: { message?: string };
        };
        if (msg.type === "auth_required") socket.send(JSON.stringify({ type: "auth", access_token: this.token }));
        else if (msg.type === "auth_invalid") done(() => reject(new Error("Home Assistant refused the token")));
        else if (msg.type === "auth_ok") socket.send(JSON.stringify({ id: 1, type }));
        else if (msg.type === "result" && msg.id === 1) {
          if (msg.success) done(() => resolve(msg.result));
          else done(() => reject(new Error(`Home Assistant ${type}: ${msg.error?.message ?? "failed"}`)));
        }
      };
    });
  }
 }
@@ -0,0 +1,84 @@
 // home-assistant's provisions step — run once by the host after Home Assistant starts, and again
 // whenever a binding or pair credential it reads changes (the container's `restart-on`, novox/hq
 // ADR 0099). It points Home Assistant's MQTT integration at the `mqtt-topic` broker and its Sonarr,
 // Radarr and Lidarr integrations at the `sonarr-api`, `radarr-api` and `lidarr-api` apps, through
 // Home Assistant's own config flows (connections.ts). It connects to no mesh broker.
 //
 // Exits non-zero when anything could not be put right, so the node reports the step failed and the
 // host runs it again on the next apply. Declared last in the manifest, so its failing gates nothing
 // else of home-assistant's (novox/hq ADR 0136). Never prints a key or password.
 import { join } from "node:path";
 import { APPS, MQTT_PROVISION, reconcileApp, reconcileMqtt, type Outcome } from "./connections.js";
 import { HassApi } from "./hass.js";
 import { marksIn, readBinding, readIfThere } from "./mesh.js";
 import { probeBroker } from "./probe.js";
 const dir = process.env.MESH_PROVISIONS_DIR ?? "/run/provisions";
 const url = process.env.MESH_HOMEASSISTANT_URL ?? "http://127.0.0.1:8123";
 const token = (await readIfThere(process.env.MESH_HOMEASSISTANT_TOKEN_FILE))?.trim() ?? "";
 const marks = marksIn(process.env.MESH_WRITTEN_DIR ?? "/var/lib/home-assistant-provisions");
 const waitSeconds = Number(process.env.MESH_HOMEASSISTANT_WAIT_SECONDS ?? "300");
 if (!token) {
  console.error("[hass-provisions] no Home Assistant token — home-assistant's own `token` secret has not been accepted");
  process.exit(1);
 }
 /** Home Assistant answers /api/ with 200 once it is up and the token is good. */
 async function ready(): Promise<boolean> {
  const until = Date.now() + waitSeconds * 1000;
  for (;;) {
    try {
      const res = await fetch(`${url.replace(/\/$/, "")}/api/`, { headers: { Authorization: `Bearer ${token}` } });
      if (res.status === 200) return true;
      if (res.status === 401 || res.status === 403) {
        console.error("[hass-provisions] Home Assistant refuses the token — accept a long-lived access token it issued");
        return false;
      }
    } catch {
      // not listening yet
    }
    if (Date.now() >= until) return false;
    await new Promise((r) => setTimeout(r, 3000));
  }
 }
 if (!(await ready())) {
  console.error(`[hass-provisions] Home Assistant did not answer at ${url} within ${waitSeconds}s`);
  process.exit(1);
 }
 const hass = new HassApi(url, token);
 const read = async (p: string) => [await readBinding(join(dir, `${p}.json`)), await readIfThere(join(dir, `${p}.secret`))] as const;
 const outcomes: Outcome[] = [];
 {
  const [binding, secret] = await read(MQTT_PROVISION);
  outcomes.push(await reconcileMqtt({ hass, probe: probeBroker, marks }, binding, secret));
 }
 for (const spec of APPS) {
  const [binding, secret] = await read(spec.provision);
  outcomes.push(await reconcileApp({ hass, http: { fetch: (u, init) => fetch(u, init) } }, spec, binding, secret));
 }
 let failed = 0;
 for (const o of outcomes) {
  switch (o.result) {
    case "unchanged":
      console.log(`[hass-provisions] ${o.what}: already as the mesh says${o.note ? ` — ${o.note}` : ""}`);
      break;
    case "written":
      console.log(`[hass-provisions] ${o.what}: wrote ${o.fields.join(", ")}; Home Assistant's own test passed${o.note ? ` — ${o.note}` : ""}`);
      break;
    case "equivalent":
      console.log(`[hass-provisions] ${o.what}: ${o.note}`);
      break;
    case "refused":
      failed++;
      console.error(`[hass-provisions] ${o.what}: ${o.problem}`);
      break;
  }
 }
 process.exitCode = failed > 0 ? 1 : 0;
@@ -0,0 +1,42 @@
 // What the mesh delivered to home-assistant's provisions step, and the step's own small memory.
 //
 // Per provision it requires, the mesh writes two files beside each other (the manifest's `binds` and
 // `secrets`): `<provision>.json`, the binding — where the provider is (`at`), what it serves (`port`,
 // `scheme`, …) and the login this module presents (`as`) — and `<provision>.secret`, the pair
 // credential. Nothing here guesses a host, a port or a key.
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { Binding, Marks } from "./connections.js";
 /** A file the mesh wrote, or undefined when it is not there. */
 export async function readIfThere(path: string | undefined): Promise<string | undefined> {
  if (!path) return undefined;
  return readFile(path, "utf8").catch(() => undefined);
 }
 /** A binding file parsed, or undefined when absent or not JSON. */
 export async function readBinding(path: string): Promise<Binding | undefined> {
  const raw = await readIfThere(path);
  if (raw === undefined) return undefined;
  try {
    return JSON.parse(raw) as Binding;
  } catch {
    return undefined;
  }
 }
 export function marksIn(dir: string): Marks {
  return {
    async get(name) {
      return (await readIfThere(join(dir, `${name}.digest`)))?.trim() || undefined;
    },
    async set(name, value) {
      await mkdir(dir, { recursive: true, mode: 0o700 });
      const path = join(dir, `${name}.digest`);
      await writeFile(`${path}.tmp`, `${value}\n`, { mode: 0o600 });
      await rename(`${path}.tmp`, path);
    },
  };
 }
@@ -0,0 +1,117 @@
 // Ask the broker, before Home Assistant is told anything, whether it takes the login and password
 // the mesh delivered — and whether that login may subscribe to Home Assistant's discovery topics.
 //
 // One MQTT 3.1.1 session: CONNECT (clean, a throwaway client id, so Home Assistant's own session is
 // never taken over), read the CONNACK, optionally SUBSCRIBE once and read the SUBACK, DISCONNECT.
 // No dependency: the handful of bytes MQTT needs for this are written here.
 import { randomBytes } from "node:crypto";
 import { connect } from "node:net";
 export interface ProbeResult {
  /** 0 accepted; 4 bad username or password; 5 not authorised. */
  connack: number;
  /** The SUBACK return code for the filter asked about: 0–2 granted, 0x80 refused. */
  suback?: number;
 }
 export type Probe = (host: string, port: number, username: string, password: string, subscribe?: string) => Promise<ProbeResult>;
 function str(v: string): Buffer {
  const b = Buffer.from(v, "utf8");
  const len = Buffer.alloc(2);
  len.writeUInt16BE(b.length);
  return Buffer.concat([len, b]);
 }
 function packet(type: number, body: Buffer): Buffer {
  let remaining = body.length;
  const lenBytes: number[] = [];
  do {
    let byte = remaining % 128;
    remaining = Math.floor(remaining / 128);
    if (remaining > 0) byte |= 0x80;
    lenBytes.push(byte);
  } while (remaining > 0);
  return Buffer.concat([Buffer.from([type, ...lenBytes]), body]);
 }
 /** The first complete packet in `buf`: its type byte, its body, and how many bytes it took. */
 export function firstPacket(buf: Buffer): { type: number; body: Buffer; used: number } | undefined {
  if (buf.length < 2) return undefined;
  let length = 0;
  let multiplier = 1;
  let i = 1;
  for (;;) {
    if (i >= buf.length) return undefined;
    const byte = buf[i++];
    length += (byte & 0x7f) * multiplier;
    if ((byte & 0x80) === 0) break;
    multiplier *= 128;
    if (i > 4) throw new Error("malformed MQTT remaining length");
  }
  if (buf.length < i + length) return undefined;
  return { type: buf[0], body: buf.subarray(i, i + length), used: i + length };
 }
 export const probeBroker: Probe = (host, port, username, password, subscribe) => {
  const connectBody = Buffer.concat([
    str("MQTT"),
    Buffer.from([4, 0xc2, 0, 10]), // level 4 (3.1.1); username + password + clean session; keepalive 10s
    str(`mesh-probe-${randomBytes(6).toString("hex")}`),
    str(username),
    str(password),
  ]);
  return new Promise((resolve, reject) => {
    const socket = connect({ host, port });
    let buf = Buffer.alloc(0);
    const result: ProbeResult = { connack: -1 };
    const timer = setTimeout(() => {
      socket.destroy();
      reject(new Error(`no answer from the broker at ${host}:${port} within 10s`));
    }, 10_000);
    const finish = (): void => {
      clearTimeout(timer);
      if (result.connack === 0) socket.end(Buffer.from([0xe0, 0]));
      else socket.destroy();
      resolve(result);
    };
    socket.on("connect", () => socket.write(packet(0x10, connectBody)));
    socket.on("data", (chunk) => {
      buf = Buffer.concat([buf, chunk]);
      for (;;) {
        let p;
        try {
          p = firstPacket(buf);
        } catch (err) {
          clearTimeout(timer);
          socket.destroy();
          reject(err);
          return;
        }
        if (!p) return;
        buf = buf.subarray(p.used);
        const kind = p.type >> 4;
        if (kind === 2) {
          result.connack = p.body[1] ?? -1;
          if (result.connack !== 0 || !subscribe) return finish();
          // SUBSCRIBE, packet id 1, one filter at QoS 0.
          socket.write(packet(0x82, Buffer.concat([Buffer.from([0, 1]), str(subscribe), Buffer.from([0])])));
        } else if (kind === 9) {
          result.suback = p.body[2];
          return finish();
        }
      }
    });
    socket.on("error", (err) => {
      clearTimeout(timer);
      reject(err);
    });
    socket.on("close", () => {
      if (result.connack === -1) {
        clearTimeout(timer);
        reject(new Error(`the broker at ${host}:${port} closed the connection without answering`));
      }
    });
  });
 };
@@ -0,0 +1,293 @@
 // What holds home-assistant's provisions step (provisions/*.ts): Home Assistant's MQTT entry is
 // made to use the broker, port and login the mesh bound — only after the broker takes that login,
 // through the reconfigure flow, keeping every other setting as Home Assistant pre-filled it, and not
 // again once it already says so; its Sonarr/Radarr/Lidarr entries are made, finished (reauth), left
 // alone when they already reach the bound app, and never removed; a key the app refuses (the mesh's
 // minted value before the operator accepts the app's) is never written.
 //
 // Home Assistant and the apps are fakes answering as the real ones do (flow shapes checked against
 // ghcr.io/home-assistant/home-assistant 2026.9.3, the build ace runs).
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import type { ConfigEntry, DeviceEntry, FlowProgress, FlowResult, Hass, SchemaField } from "../provisions/hass.ts";
 import type { Binding, Marks } from "../provisions/connections.ts";
 import { APPS, formValues, reconcileApp, reconcileMqtt, sameUrl, type Http, type ServarrApp } from "../provisions/connections.ts";
 import type { Probe } from "../provisions/probe.ts";
 const PWD_NOT_CHANGED = "__**password_not_changed**__";
 const MINTED = "mesh-minted-password";
 function mqttBinding(): Binding {
  return { provision: "mqtt-topic", from: "ace", at: "ace.internal", as: "mesh_ace_hass", serves: { scheme: "mqtt", port: 1883 } };
 }
 /** The MQTT reconfigure form as Home Assistant serializes it, pre-filled from an entry. */
 function brokerForm(data: Record<string, unknown>): SchemaField[] {
  return [
    { name: "broker", type: "string", required: true, description: { suggested_value: data.broker } },
    { name: "port", type: "integer", required: true, default: 1883, description: { suggested_value: data.port } },
    { name: "protocol", type: "select", required: true, default: "3.1.1", description: { suggested_value: data.protocol } },
    { name: "username", type: "string", optional: true, description: { suggested_value: data.username } },
    { name: "password", type: "string", optional: true, description: { suggested_value: data.password ? PWD_NOT_CHANGED : undefined } },
    {
      name: "other_settings",
      type: "expandable",
      required: true,
      schema: [
        { name: "keepalive", type: "integer", optional: true, description: { suggested_value: 60 } },
        { name: "transport", type: "select", required: true, default: "tcp", description: { suggested_value: "tcp" } },
        { name: "set_ca_cert", type: "select", required: true, description: { suggested_value: "off" } },
        { name: "set_client_cert", type: "boolean", required: true, description: { suggested_value: false } },
      ],
    },
  ];
 }
 interface FakeOpts {
  entries?: Record<string, (ConfigEntry & { data: Record<string, unknown> })[]>;
  /** What Home Assistant's own connection test accepts. */
  accepts?: (data: Record<string, unknown>) => boolean;
  reauth?: FlowProgress[];
  devices?: DeviceEntry[];
 }
 function fakeHass(opts: FakeOpts = {}) {
  const entries = opts.entries ?? {};
  const calls: string[] = [];
  const submitted: Record<string, unknown>[] = [];
  const flows = new Map<string, { handler: string; entryId?: string; step: string; reauth?: boolean }>();
  let n = 0;
  const accepts = opts.accepts ?? (() => true);
  const form = (id: string, step: string, schema: SchemaField[], errors?: Record<string, string>): FlowResult => ({
    type: "form", flow_id: id, step_id: step, data_schema: schema, errors: errors ?? null,
  });
  const servarrUser: SchemaField[] = [
    { name: "url", type: "string", required: true },
    { name: "api_key", type: "string", required: true },
    { name: "more_options", type: "expandable", required: true, schema: [{ name: "verify_ssl", type: "boolean", optional: true, default: false }] },
  ];
  const hass: Hass = {
    async entries(domain) {
      calls.push(`entries ${domain}`);
      return (entries[domain] ?? []).map(({ data: _d, ...e }) => e);
    },
    async startFlow(handler, entryId) {
      calls.push(`start ${handler}${entryId ? ` ${entryId}` : ""}`);
      const id = `f${++n}`;
      if (handler === "mqtt") {
        const entry = entryId ? entries.mqtt.find((e) => e.entry_id === entryId) : undefined;
        if (entryId && !entry) return { type: "abort", reason: "not_found" };
        flows.set(id, { handler, entryId, step: "broker" });
        return form(id, "broker", brokerForm(entry?.data ?? {}));
      }
      if (entryId) return { type: "abort", reason: "not_implemented" }; // no reconfigure for Servarr
      flows.set(id, { handler, step: "user" });
      return form(id, "user", servarrUser);
    },
    async stepFlow(flowId, input) {
      calls.push(`step ${flowId}`);
      const flow = flows.get(flowId);
      if (!flow) throw new Error(`Home Assistant POST flow/${flowId} answered 404`);
      if (flow.step === "reauth_confirm") {
        flow.step = "user";
        return form(flowId, "user", [
          { name: "url", type: "string", required: true, default: "http://old:1" },
          { name: "api_key", type: "string", optional: true },
          { name: "verify_ssl", type: "boolean", optional: true, default: false },
        ]);
      }
      submitted.push(input);
      if (flow.handler === "mqtt") {
        const entry = entries.mqtt?.find((e) => e.entry_id === flow.entryId);
        const data = { ...input, ...(input.password === PWD_NOT_CHANGED ? { password: entry?.data.password } : {}) };
        if (!accepts(data)) return form(flowId, "broker", brokerForm(data), { base: "cannot_connect" });
        flows.delete(flowId);
        if (entry) {
          entry.data = data;
          return { type: "abort", reason: "reconfigure_successful" };
        }
        (entries.mqtt ??= []).push({ entry_id: "new-mqtt", domain: "mqtt", state: "loaded", data });
        return { type: "create_entry", result: { entry_id: "new-mqtt" } };
      }
      if (!accepts(input)) return form(flowId, "user", servarrUser, { base: "invalid_auth" });
      flows.delete(flowId);
      if (flow.reauth) return { type: "abort", reason: "reauth_successful" };
      (entries[flow.handler] ??= []).push({ entry_id: `new-${flow.handler}`, domain: flow.handler, state: "loaded", data: input });
      return { type: "create_entry", result: { entry_id: `new-${flow.handler}` } };
    },
    async abortFlow(flowId) {
      calls.push(`abort ${flowId}`);
      flows.delete(flowId);
    },
    async flowsInProgress() {
      for (const f of opts.reauth ?? []) flows.set(f.flow_id, { handler: f.handler, entryId: f.context?.entry_id, step: "reauth_confirm", reauth: true });
      return opts.reauth ?? [];
    },
    async devices() {
      return opts.devices ?? [];
    },
  };
  return { hass, calls, submitted, entries };
 }
 function memoryMarks(): Marks & { store: Map<string, string> } {
  const store = new Map<string, string>();
  return { store, get: async (k) => store.get(k), set: async (k, v) => void store.set(k, v) };
 }
 const takes = (suback = 0): Probe => async (_h, _p, user, pass) => ({ connack: user === "mesh_ace_hass" && pass === MINTED ? 0 : 5, suback });
 const aceMqttEntry = () => ({
  entry_id: "7d1e", domain: "mqtt", state: "loaded",
  data: { broker: "127.0.0.1", port: 1883, protocol: "5", username: "luffy", password: "luffys-password" },
 });
 test("mqtt: the broker is asked first; a login it does not take is never written", async () => {
  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
  const out = await reconcileMqtt({ hass: f.hass, probe: async () => ({ connack: 5 }), marks: memoryMarks() }, mqttBinding(), MINTED);
  assert.equal(out.result, "refused");
  assert.match((out as { problem: string }).problem, /does not \(yet\) take the login mesh_ace_hass/);
  assert.deepEqual(f.calls, []); // Home Assistant not even asked
  assert.equal(f.entries.mqtt[0].data.username, "luffy");
 });
 test("mqtt: ace's entry (127.0.0.1, luffy) is moved to the bound broker and login, every other setting kept", async () => {
  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
  const marks = memoryMarks();
  const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), `${MINTED}\n`);
  assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["broker", "username", "password"] });
  assert.deepEqual(f.entries.mqtt[0].data, {
    broker: "ace.internal", port: 1883, protocol: "5", username: "mesh_ace_hass", password: MINTED,
    other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
  });
  assert.ok(marks.store.get("mqtt"));
  assert.ok(![...marks.store.values()].some((v) => v.includes(MINTED)));
  // Run again: nothing differs, the flow is opened to read and closed without submitting.
  const before = f.submitted.length;
  const again = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
  assert.deepEqual(again, { what: "mqtt", result: "unchanged" });
  assert.equal(f.submitted.length, before);
  assert.match(f.calls.at(-1) ?? "", /^abort /);
 });
 test("mqtt: a new password alone is written (the digest tells)", async () => {
  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
  const marks = memoryMarks();
  await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
  const rotated: Probe = async () => ({ connack: 0, suback: 0 });
  const out = await reconcileMqtt({ hass: f.hass, probe: rotated, marks }, mqttBinding(), "rotated");
  assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["password"] });
  assert.equal(f.entries.mqtt[0].data.password, "rotated");
 });
 test("mqtt: Home Assistant's own connection test refusing saves nothing and fails loudly", async () => {
  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] }, accepts: () => false });
  const marks = memoryMarks();
  const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
  assert.equal(out.result, "refused");
  assert.match((out as { problem: string }).problem, /cannot_connect.*unchanged/);
  assert.equal(f.entries.mqtt[0].data.username, "luffy");
  assert.equal(marks.store.size, 0);
 });
 test("mqtt: a fresh Home Assistant gets an entry; a grant without the discovery topics is warned about", async () => {
  const f = fakeHass();
  const out = await reconcileMqtt({ hass: f.hass, probe: takes(0x80), marks: memoryMarks() }, mqttBinding(), MINTED);
  assert.equal(out.result, "written");
  assert.match((out as { note?: string }).note ?? "", /may not subscribe to homeassistant\/#/);
  assert.equal(f.entries.mqtt[0].data.broker, "ace.internal");
 });
 test("mqtt: two entries, or a binding without a port, are refused rather than guessed", async () => {
  const f = fakeHass({ entries: { mqtt: [aceMqttEntry(), { ...aceMqttEntry(), entry_id: "other" }] } });
  assert.equal((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, mqttBinding(), MINTED)).result, "refused");
  const noPort = { ...mqttBinding(), serves: {} };
  assert.match(((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, noPort, MINTED)) as { problem: string }).problem, /no usable port/);
 });
 // ---- Servarr ----
 const SONARR = APPS.find((a) => a.domain === "sonarr") as ServarrApp;
 const RADARR = APPS.find((a) => a.domain === "radarr") as ServarrApp;
 const KEY = "the-apps-own-key";
 const servarrBinding = (port: number, at = "ace.internal"): Binding => ({ provision: "sonarr-api", from: "ace", at, as: "mesh_ace_hass", serves: { scheme: "http", port, "url-base": "" } });
 /** One running Sonarr, answering on several addresses (127.0.0.1 and ace.internal are one host). */
 function apps(instances: Record<string, { startTime: string }>): Http & { asked: string[] } {
  const asked: string[] = [];
  return {
    asked,
    async fetch(url, init) {
      asked.push(url);
      const u = new URL(url);
      const inst = instances[`${u.hostname}:${u.port}`];
      if (!inst) throw new Error("connect ECONNREFUSED");
      if (init?.headers?.["X-Api-Key"] !== KEY) return { status: 401, text: async () => "" };
      return { status: 200, text: async () => JSON.stringify({ version: "4.0.15", appData: "/config", startTime: inst.startTime }) };
    },
  };
 }
 const oneSonarr = () => apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "t1" } });
 const sonarrEntry = (state = "loaded") => ({ entry_id: "5a1d", domain: "sonarr", state, data: { url: "http://127.0.0.1:8989", api_key: KEY } });
 test("servarr: the mesh's minted key is never written; the remedy names the accept", async () => {
  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] } });
  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), "minted-by-the-mesh");
  assert.equal(out.result, "refused");
  assert.match((out as { problem: string }).problem, /secret accept <this node> home-assistant sonarr-api --provider ace/);
  assert.deepEqual(f.calls, []);
 });
 test("servarr: ace's entry at 127.0.0.1 reaches the same Sonarr the mesh bound at ace.internal — left, and said", async () => {
  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
  assert.equal(out.result, "equivalent");
  assert.equal(f.submitted.length, 0);
 });
 test("servarr: an entry already at the bound URL is unchanged", async () => {
  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://ace.internal:8989" }] });
  assert.deepEqual(await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY), { what: "sonarr", result: "unchanged" });
 });
 test("servarr: a working entry that reaches a different app is refused, and nothing is removed", async () => {
  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
  const two = apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "another" } });
  const out = await reconcileApp({ hass: f.hass, http: two }, SONARR, servarrBinding(8989), KEY);
  assert.equal(out.result, "refused");
  assert.match((out as { problem: string }).problem, /never does/);
  assert.equal(f.entries.sonarr.length, 1);
 });
 test("servarr: no entry — one is made at the bound URL through the user flow", async () => {
  const f = fakeHass({ entries: {} });
  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
  assert.deepEqual(out, { what: "sonarr", result: "written", fields: ["entry"] });
  assert.deepEqual(f.submitted[0], { url: "http://ace.internal:8989", api_key: KEY, more_options: { verify_ssl: false } });
 });
 test("servarr: a reauth Home Assistant started is finished with the bound URL and key", async () => {
  const entry = { ...sonarrEntry("setup_error"), domain: "radarr", entry_id: "1955" };
  const f = fakeHass({
    entries: { radarr: [entry] },
    reauth: [{ flow_id: "r1", handler: "radarr", step_id: "reauth_confirm", context: { source: "reauth", entry_id: "1955" } }],
  });
  const radarr = apps({ "ace.internal:7878": { startTime: "t" } });
  const out = await reconcileApp({ hass: f.hass, http: radarr }, RADARR, { ...servarrBinding(7878), provision: "radarr-api" }, KEY);
  assert.deepEqual(out, { what: "radarr", result: "written", fields: ["api_key", "url"] });
  assert.deepEqual(f.submitted[0], { url: "http://ace.internal:7878", api_key: KEY, verify_ssl: false });
 });
 test("form values: suggested first, then default, sections nested", () => {
  assert.deepEqual(formValues(brokerForm({ broker: "b", port: 1, protocol: "5", username: "u", password: "p" })), {
    broker: "b", port: 1, protocol: "5", username: "u", password: PWD_NOT_CHANGED,
    other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
  });
  assert.ok(sameUrl("http://ace.internal:8989/", "http://ace.internal:8989"));
  assert.ok(sameUrl("http://ACE.internal", "http://ace.internal:80"));
  assert.ok(!sameUrl("http://127.0.0.1:8989", "http://ace.internal:8989"));
 });
@@ -8,5 +8,14 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "index.ts", "tools/index.ts"]
+  "include": [
    "client.ts",
    "index.ts",
    "tools/index.ts",
    "provisions/hass.ts",
    "provisions/probe.ts",
    "provisions/connections.ts",
    "provisions/mesh.ts",
    "provisions/index.ts"
  ]
 }
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/influxdb
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts grants.ts provisioner/index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
@@ -21,4 +21,4 @@ COPY --from=build /app/modules/influxdb/dist /app/modules/influxdb/dist
 # Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/influxdb/dist/tools/index.js,/app/modules/influxdb/dist/provisioner/index.js
+ENV MESH_TOOL_MODULES=/app/modules/influxdb/dist/tools/index.js
@@ -17,25 +17,6 @@ export interface InfluxBucket {
  retentionSeconds?: number;
 }
 /** One permission of an authorization, as InfluxDB represents it: an action on a resource type,
 *  in one org, optionally narrowed to one resource by id (no id = every resource of that type). */
 export interface InfluxPermission {
  action: "read" | "write";
  resource: { type: string; orgID?: string; id?: string; name?: string; org?: string };
 }
 /** A v1-compatibility ("legacy") authorization: a username (InfluxDB calls it `token`) and a
 *  password the caller chooses, scoped by permissions. The one credential InfluxDB 2.x lets a
 *  caller set to a value it did not generate — which is what a mesh-minted password needs. */
 export interface LegacyAuthorization {
  id: string;
  token: string;
  orgID: string;
  status?: "active" | "inactive";
  description?: string;
  permissions: InfluxPermission[];
 }
 /** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
 function meshConfig(file?: string): Record<string, string> {
  if (!file) return {};
@@ -43,20 +24,13 @@ function meshConfig(file?: string): Record<string, string> {
  catch { return {}; }
 }
 /** A secret delivered as a file, trimmed; undefined when there is none, so the caller can fall back. */
 function tokenFromFile(file?: string): string | undefined {
  if (!file) return undefined;
  try { return readFileSync(file, "utf8").trim() || undefined; }
  catch { return undefined; }
 }
 export class InfluxDBClient {
  readonly baseUrl: string;
  constructor(
    url: string,
    private readonly token: string,
-    readonly org: string,
+    private readonly org: string,
  ) {
    this.baseUrl = url.replace(/\/$/, "");
  }
@@ -69,10 +43,8 @@ export class InfluxDBClient {
  static fromEnv(env: NodeJS.ProcessEnv = process.env): InfluxDBClient {
    const cfg = meshConfig(env.MESH_INFLUXDB_CONFIG_FILE);
    const url = cfg.url ?? env.MESH_INFLUXDB_URL ?? `http://127.0.0.1:${env.INFLUXDB_PORT ?? "8086"}`;
-    // The token reaches the process as a file (novox/hq ADR 0086); the environment variable stays
+    const token = cfg.token ?? env.MESH_INFLUXDB_TOKEN;
-    // only for a workstation running the tools by hand.
+    if (!token) throw new Error("no InfluxDB token — set MESH_INFLUXDB_TOKEN");
    const token = cfg.token ?? tokenFromFile(env.MESH_INFLUXDB_TOKEN_FILE) ?? env.MESH_INFLUXDB_TOKEN;
    if (!token) throw new Error("no InfluxDB token — set MESH_INFLUXDB_TOKEN_FILE");
    const org = cfg.org ?? env.MESH_INFLUXDB_ORG ?? "mesh";
    return new InfluxDBClient(url, token, org);
  }
@@ -89,93 +61,6 @@ export class InfluxDBClient {
    return res;
  }
  /** Like request, but the answer is returned whatever its status, for the caller to read. */
  private async raw(path: string, init?: RequestInit): Promise<Response> {
    return fetch(`${this.baseUrl}${path}`, {
      ...init,
      headers: { Authorization: `Token ${this.token}`, ...(init?.headers ?? {}) },
    });
  }
  private async send(path: string, method: string, body?: unknown): Promise<Response> {
    return this.request(path, {
      method,
      headers: { "Content-Type": "application/json" },
      body: body === undefined ? undefined : JSON.stringify(body),
    });
  }
  /** The id of the org of this name, or undefined when there is none. */
  async orgID(name: string): Promise<string | undefined> {
    const res = await this.raw(`/api/v2/orgs?org=${encodeURIComponent(name)}`);
    if (res.status === 404) return undefined;
    if (!res.ok) throw new Error(`InfluxDB API /api/v2/orgs: ${res.status} ${await res.text()}`);
    const body = (await res.json()) as { orgs?: { id: string; name: string }[] };
    return body.orgs?.find((o) => o.name === name)?.id;
  }
  /** The bucket of exactly this name in the org, or undefined. */
  async findBucket(orgID: string, name: string): Promise<InfluxBucket | undefined> {
    const res = await this.raw(`/api/v2/buckets?orgID=${encodeURIComponent(orgID)}&name=${encodeURIComponent(name)}`);
    if (res.status === 404) return undefined;
    if (!res.ok) throw new Error(`InfluxDB API /api/v2/buckets: ${res.status} ${await res.text()}`);
    const body = (await res.json()) as { buckets?: { id: string; name: string; orgID?: string }[] };
    const b = body.buckets?.find((x) => x.name === name);
    return b ? { id: b.id, name: b.name, orgID: b.orgID } : undefined;
  }
  /** Create a bucket that keeps its data for ever — retention is the operator's choice, never the mesh's. */
  async createBucket(orgID: string, name: string, description: string): Promise<InfluxBucket> {
    const b = (await (await this.send("/api/v2/buckets", "POST", {
      orgID, name, description, retentionRules: [],
    })).json()) as { id: string; name: string; orgID?: string };
    return { id: b.id, name: b.name, orgID: b.orgID };
  }
  /** The v1 authorization whose username is exactly this, or undefined. */
  async findLegacy(username: string): Promise<LegacyAuthorization | undefined> {
    const path = `/private/legacy/authorizations?token=${encodeURIComponent(username)}`;
    const res = await this.raw(path);
    // InfluxDB answers a filter matching nothing with 404, not an empty list.
    if (res.status === 404) return undefined;
    if (!res.ok) throw new Error(`InfluxDB API ${path}: ${res.status} ${await res.text()}`);
    const body = (await res.json()) as { authorizations?: LegacyAuthorization[] };
    return body.authorizations?.find((a) => a.token === username);
  }
  async createLegacy(a: Omit<LegacyAuthorization, "id">): Promise<LegacyAuthorization> {
    return (await (await this.send("/private/legacy/authorizations", "POST", a)).json()) as LegacyAuthorization;
  }
  /** Set a v1 authorization's password. InfluxDB keeps only a hash of it, so it can be set, never read. */
  async setLegacyPassword(id: string, password: string): Promise<void> {
    await this.send(`/private/legacy/authorizations/${encodeURIComponent(id)}/password`, "POST", { password });
  }
  async updateLegacy(id: string, patch: { status?: "active" | "inactive"; description?: string }): Promise<void> {
    await this.send(`/private/legacy/authorizations/${encodeURIComponent(id)}`, "PATCH", patch);
  }
  async deleteLegacy(id: string): Promise<void> {
    await this.send(`/private/legacy/authorizations/${encodeURIComponent(id)}`, "DELETE");
  }
  /**
   * Whether this username and password sign in on the v1 API — the consumer's own view. Asked with
   * a statement that reads nothing (`SHOW DATABASES` lists only what the credential may read), sent
   * with Basic auth so the password is never in a URL. 401 is a wrong password or no such user;
   * anything else that is not a server error means InfluxDB knew who was asking.
   */
  async legacySignsIn(username: string, password: string): Promise<boolean> {
    const res = await fetch(`${this.baseUrl}/query?q=${encodeURIComponent("SHOW DATABASES")}`, {
      headers: { Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}` },
    });
    await res.arrayBuffer();
    if (res.status === 401) return false;
    if (res.status >= 500) throw new Error(`InfluxDB v1 /query: ${res.status}`);
    return true;
  }
  /** Server health — the one endpoint that needs no token, but we send it anyway. */
  async health(): Promise<InfluxHealth> {
    return (await (await this.request("/health")).json()) as InfluxHealth;
@@ -1,186 +0,0 @@
 // What the `influxdb-api` provision means in InfluxDB: one v1-compatibility authorization per
 // consumer, in the org this module serves, under the username and password the mesh gave both ends,
 // allowed exactly the access the consumer contributed. The provisioner (provisioner/index.ts) is the
 // sdk harness calling these; they are here, apart from it, so they can be exercised against a fake
 // InfluxDB without a broker or a contributions file.
 //
 // **Why a v1 authorization and not a v2 API token.** The mesh mints the consumer's password and
 // hands it to both ends (novox/hq ADR 0048); the provider sets it, and never hands one back. An
 // InfluxDB 2.x API token is generated by the server — `POST /api/v2/authorizations` ignores a token
 // the caller sends — so a token could only ever be the operator's to accept, one per pair, by hand.
 // A v1 authorization is a username and a password the caller chooses (8–72 characters; the mesh
 // mints 40), stored hashed, and it reads and writes through InfluxQL (`/query`) and line protocol
 // (`/write`), which every bucket answers under its own name as a database (InfluxDB maps each
 // bucket to a database of the same name by itself). That is what grafana's InfluxDB data source
 // speaks, and what Node-RED's influxdb nodes speak in their 1.x mode — so the mesh can make every
 // consumer's credential, rotate it and withdraw it, with no person in the loop.
 //
 // **What a consumer contributes.** `access`: "read" (the default), "write" or "read-write".
 // `buckets`: the buckets it may use, by name. A reader that names none may read every bucket of the
 // org — a dashboard is pointed at data, it does not own it. A writer must name its buckets: writing
 // everywhere, the org's system buckets included, is never what a consumer means. A named bucket
 // that does not exist is created, keeping its data for ever; the mesh never deletes a bucket.
 //
 // **Only what the mesh made is touched.** An authorization this module creates is named with the
 // mesh's identity prefix and its description starts with MARK. One with the same username that
 // lacks the mark is somebody else's: it is refused, never adopted, never updated, never deleted.
 // Every other authorization, token, user and bucket in the instance is left exactly as it was.
 import type { InfluxDBClient, InfluxPermission, LegacyAuthorization } from "./client.js";
 /** How a description marks an authorization as the mesh's own work. */
 export const MARK = "[mesh]";
 /** The prefix the mesh gives every consumer identity (novox/hq ADR 0049). */
 const IDENTITY_PREFIX = "mesh_";
 /** One consumer, as the harness hands it over. */
 export interface ApiGrant {
  readonly as: string;
  readonly password: string;
  readonly values: Readonly<Record<string, unknown>>;
  readonly consumer?: string;
 }
 export type Access = "read" | "write" | "read-write";
 /** What a contribution asks for, checked. Refused when it cannot be served as asked. */
 export function askedFor(values: Readonly<Record<string, unknown>>): { access: Access; buckets: string[] } {
  const access = values.access ?? "read";
  if (access !== "read" && access !== "write" && access !== "read-write") {
    throw new Error(`contributes an access of ${JSON.stringify(access)} — it is "read", "write" or "read-write"`);
  }
  const raw = values.buckets ?? [];
  if (!Array.isArray(raw) || raw.some((b) => typeof b !== "string" || b.trim() === "")) {
    throw new Error(`contributes buckets of ${JSON.stringify(raw)} — a list of bucket names`);
  }
  const buckets = [...new Set((raw as string[]).map((b) => b.trim()))].sort();
  if (access !== "read" && buckets.length === 0) {
    throw new Error(`asks to write and names no bucket (\`buckets\`) — a writer names what it writes to`);
  }
  if (buckets.some((b) => b.startsWith("_"))) {
    throw new Error(`names a system bucket (${buckets.filter((b) => b.startsWith("_")).join(", ")}) — those are InfluxDB's own`);
  }
  return { access: access as Access, buckets };
 }
 /** The permissions a grant resolves to, given each named bucket's id. */
 export function permissionsFor(orgID: string, access: Access, bucketIDs: string[]): InfluxPermission[] {
  const actions: ("read" | "write")[] = access === "read-write" ? ["read", "write"] : [access];
  const out: InfluxPermission[] = [];
  for (const action of actions) {
    if (bucketIDs.length === 0) {
      out.push({ action, resource: { type: "buckets", orgID } });
      continue;
    }
    for (const id of bucketIDs) out.push({ action, resource: { type: "buckets", orgID, id } });
  }
  return out;
 }
 /** A permission as a comparable string: what InfluxDB answers carries names and links besides. */
 function key(p: InfluxPermission): string {
  return `${p.action}:${p.resource.type}:${p.resource.orgID ?? ""}:${p.resource.id ?? "*"}`;
 }
 function samePermissions(a: readonly InfluxPermission[], b: readonly InfluxPermission[]): boolean {
  const x = a.map(key).sort();
  const y = b.map(key).sort();
  return x.length === y.length && x.every((v, i) => v === y[i]);
 }
 export function marked(a: Pick<LegacyAuthorization, "token" | "description">): boolean {
  return a.token.startsWith(IDENTITY_PREFIX) && (a.description ?? "").startsWith(MARK);
 }
 function describe(g: ApiGrant): string {
  return `${MARK} made by the mesh for ${g.consumer ? `a module on ${g.consumer}` : "a consumer"} — do not edit; it is reset`;
 }
 export class ApiGrants {
  constructor(private readonly influx: InfluxDBClient, readonly org: string) {}
  private async orgID(): Promise<string> {
    const id = await this.influx.orgID(this.org);
    if (!id) throw new Error(`InfluxDB has no org ${JSON.stringify(this.org)} — the org this module serves must exist`);
    return id;
  }
  /** The ids of the named buckets, creating any that are missing when `create` says so. Undefined
   *  when one is missing and may not be created (a read-only question). */
  private async bucketIDs(orgID: string, names: string[], create: ApiGrant | undefined): Promise<string[] | undefined> {
    const ids: string[] = [];
    for (const name of names) {
      let b = await this.influx.findBucket(orgID, name);
      if (!b) {
        if (!create) return undefined;
        b = await this.influx.createBucket(orgID, name, `${MARK} made by the mesh for ${create.as}; the mesh never deletes it`);
      }
      ids.push(b.id);
    }
    return ids.sort();
  }
  /** Create the consumer's authorization, or bring the mesh's existing one back to what the grant
   *  says. Idempotent: a second apply of the same grant changes nothing beyond re-asserting the
   *  password, which InfluxDB can be told but never asked. */
  async ensure(g: ApiGrant): Promise<"created" | "updated" | "unchanged"> {
    if (!g.as.startsWith(IDENTITY_PREFIX)) {
      throw new Error(`${g.as} is not a mesh identity — the mesh names every consumer ${IDENTITY_PREFIX}<node>_<module>`);
    }
    const { access, buckets } = askedFor(g.values);
    const orgID = await this.orgID();
    const found = await this.influx.findLegacy(g.as);
    if (found && !marked(found)) {
      throw new Error(
        `InfluxDB already has a v1 authorization ${g.as} the mesh did not make — left alone; ` +
          `delete it if the mesh should own that name`);
    }
    const want = permissionsFor(orgID, access, (await this.bucketIDs(orgID, buckets, g))!);
    if (found && found.orgID === orgID && samePermissions(found.permissions, want)) {
      // Only what differs is written. The password cannot be read back, so it is tried instead.
      let changed = false;
      if (found.status === "inactive") {
        await this.influx.updateLegacy(found.id, { status: "active" });
        changed = true;
      }
      if (!(await this.influx.legacySignsIn(g.as, g.password))) {
        await this.influx.setLegacyPassword(found.id, g.password);
        changed = true;
      }
      return changed ? "updated" : "unchanged";
    }
    // InfluxDB cannot change an authorization's permissions in place, so the mesh's own is made
    // again. Only ever one the mesh made: a foreign one was refused above.
    if (found) await this.influx.deleteLegacy(found.id);
    const made = await this.influx.createLegacy({
      token: g.as, orgID, status: "active", description: describe(g), permissions: want,
    });
    await this.influx.setLegacyPassword(made.id, g.password);
    return found ? "updated" : "created";
  }
  /** Whether InfluxDB still holds this consumer's authorization exactly as the grant says: present,
   *  the mesh's, active, allowed what was asked and nothing more, and signing in with the mesh's
   *  password. Reads only — a missing bucket is "not held", never created here. */
  async holds(g: ApiGrant): Promise<boolean> {
    const { access, buckets } = askedFor(g.values);
    const orgID = await this.influx.orgID(this.org);
    if (!orgID) return false;
    const found = await this.influx.findLegacy(g.as);
    if (!found || !marked(found) || found.status === "inactive" || found.orgID !== orgID) return false;
    const ids = await this.bucketIDs(orgID, buckets, undefined);
    if (!ids || !samePermissions(found.permissions, permissionsFor(orgID, access, ids))) return false;
    return this.influx.legacySignsIn(g.as, g.password);
  }
  /** Withdraw a consumer's authorization — only one the mesh made. Its buckets and their data stay. */
  async remove(as: string): Promise<"removed" | "absent" | "not ours"> {
    const found = await this.influx.findLegacy(as);
    if (!found) return "absent";
    if (!marked(found)) return "not ours";
    await this.influx.deleteLegacy(found.id);
    return "removed";
  }
 }
@@ -1,12 +1,6 @@
 {
  "module": "influxdb",
  "version": "1",
  "provides": [
    {
      "name": "influxdb-api",
      "scope": "mesh"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
@@ -19,23 +13,9 @@
      "port": 8086,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "queries, writes and the web UI, over http; consumers granted influxdb-api sign in with the mesh's credential, and a name is a route grant"
+      "why": "queries and writes, over http"
    }
  ],
  "serves": {
    "influxdb-api": {
      "scheme": "http",
      "port": 8086,
      "org": "mesh",
      "bucket": "default"
    }
  },
  "receives": {
    "influxdb-api": "${dir:grants}/mesh.json"
  },
  "grants": {
    "influxdb-api": "${dir:grants}"
  },
  "resources": [
    {
      "id": "mesh-state",
@@ -46,50 +26,46 @@
    {
      "id": "state",
      "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/influxdb-module",
-      "place": "."
+      "mode": "0700"
    },
    {
      "id": "server-env",
      "type": "file",
      "path": "/var/lib/influxdb-module/server.env",
      "mode": "0600",
      "content": "DOCKER_INFLUXDB_INIT_MODE=setup\nDOCKER_INFLUXDB_INIT_USERNAME=admin\nDOCKER_INFLUXDB_INIT_PASSWORD=${secret:admin}\nDOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${secret:admin-token}\nDOCKER_INFLUXDB_INIT_ORG=mesh\nDOCKER_INFLUXDB_INIT_BUCKET=default\n"
    },
    {
      "id": "data",
      "type": "directory",
      "path": "/services/influxdb/data",
      "mode": "0700",
      "owner": "1000:1000"
    },
    {
      "id": "config",
      "type": "directory",
      "path": "/services/influxdb/config",
      "mode": "0700",
      "owner": "1000:1000"
    },
    {
      "id": "grants",
      "type": "directory",
      "mode": "0700"
    },
    {
      "id": "server-env",
      "type": "file",
      "path": "${dir:state}/server.env",
      "mode": "0600",
      "content": "DOCKER_INFLUXDB_INIT_MODE=setup\nDOCKER_INFLUXDB_INIT_USERNAME=admin\nDOCKER_INFLUXDB_INIT_PASSWORD_FILE=/run/secrets/admin\nDOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE=/run/secrets/admin-token\nDOCKER_INFLUXDB_INIT_ORG=mesh\nDOCKER_INFLUXDB_INIT_BUCKET=default\n"
    },
    {
      "id": "server",
      "type": "container",
      "name": "influxdb",
      "image": "influxdb@sha256:f75e48af0598e8aec7986e991a848d19a119101a7d563a2e5db1dfaac9c45daa",
      "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/influxdb-module/server.env"
      ],
      "ports": [
        "8086"
      ],
      "volumes": [
-        "${dir:data}:/var/lib/influxdb2",
+        "/services/influxdb/data:/var/lib/influxdb2",
-        "${dir:config}:/etc/influxdb2",
+        "/services/influxdb/config:/etc/influxdb2"
-        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+      ],
-        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro"
+      "secrets-in-environment": "the image honours DOCKER_INFLUXDB_INIT_PASSWORD_FILE and _ADMIN_TOKEN_FILE; convertible, awaiting a bed that proves it"
      ]
    },
    {
      "id": "runtime-config",
@@ -107,15 +83,13 @@
      "volumes": [
        "/var/lib/mesh/influxdb/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/influxdb/config.json:/run/config/config.json:ro",
-        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro",
+        "/services/influxdb/config:/var/lib/influxdb/config:ro"
        "${dir:grants}:${dir:grants}:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
+        "MESH_INFLUXDB_URL": "http://127.0.0.1:8086",
        "MESH_INFLUXDB_CONFIG_FILE": "/run/config/config.json",
-        "MESH_INFLUXDB_TOKEN_FILE": "/run/secrets/admin-token",
+        "MESH_INFLUXDB_CONFIG_DIR": "/var/lib/influxdb/config"
        "MESH_RECEIVES": "${dir:grants}/mesh.json"
      },
      "restart-on": [
        "runtime-config"
@@ -123,22 +97,6 @@
      "artifact": "runtime"
    }
  ],
  "requires": [
    "route",
    "secret"
  ],
  "contributes": {
    "route": {
      "label": "influxdb",
      "endpoint": "api"
    }
  },
  "secrets": {
    "secret": {
      "admin": "${dir:state}/admin.secret",
      "admin-token": "${dir:state}/admin-token.secret"
    }
  },
  "build": {
    "on": [
      {
@@ -159,5 +117,14 @@
        "from": "Dockerfile"
      }
    ]
  },
  "requires": [
    "secret"
  ],
  "secrets": {
    "secret": {
      "admin": "/var/lib/influxdb-module/admin.secret",
      "admin-token": "/var/lib/influxdb-module/admin-token.secret"
    }
  }
 }
@@ -1,14 +1,9 @@
 {
  "name": "@novox/module-influxdb",
  "version": "0.1.0",
-  "description": "influxdb — time-series database; provides the mesh influxdb-api interface. Its API client, provisioner and tools live here (novox/hq ADR 0039).",
+  "description": "influxdb — time-series database. Its API client and tools live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc client.ts grants.ts provisioner/index.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
    "typecheck": "tsc -p tsconfig.json",
    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
  },
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
@@ -1,54 +0,0 @@
 // influxdb's provisioner — the adapter that makes influxdb a provider of the mesh `influxdb-api`
 // interface. The reconcile loop, the contributions file and reading the mesh's minted secret are the
 // sdk harness's; this writes only the per-service half: how InfluxDB creates, checks and removes a
 // consumer's credential (novox/hq ADR 0039/0040/0048). What that credential is, and why it is a v1
 // authorization, is in ../grants.ts.
 //
 // The `influxdb-api` interface: a consumer reaches `${bound:influxdb-api:scheme}://…:at:…:port`,
 // signs in as `${bound:influxdb-api:as}` with the password the mesh minted for the pair, and reads
 // or writes the org's buckets as databases of the same name — `${bound:influxdb-api:bucket}` being
 // the one this instance serves by default. The org and the default bucket are the assignment's
 // settings, which reach both what is served and this module's config.json, so the org a consumer is
 // told and the org its credential is made in cannot disagree.
 import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
 import { InfluxDBClient } from "../client.js";
 import { ApiGrants } from "../grants.js";
 let grants: ApiGrants | undefined;
 try {
  const influx = InfluxDBClient.fromEnv();
  grants = new ApiGrants(influx, influx.org);
 } catch (err) {
  // No admin token: nothing can be provisioned, and the tools loaded beside this must still serve.
  console.error(`[provisioner:influxdb-api] not started: ${err instanceof Error ? err.message : err}`);
 }
 if (grants) serve(grants);
 function serve(grants: ApiGrants): void {
  runProvisioner("influxdb-api", {
    async create(p: Provision): Promise<void> {
      const done = await grants.ensure(p);
      if (done !== "unchanged") {
        console.log(`[provisioner:influxdb-api] ${done} v1 authorization ${p.as} in org ${grants.org}`);
      }
    },
    async remove(p: { as: string }): Promise<void> {
      const done = await grants.remove(p.as);
      if (done === "not ours") {
        console.error(`[provisioner:influxdb-api] ${p.as}: an authorization of that name exists that the mesh did not make — left alone`);
      } else if (done === "removed") {
        console.log(`[provisioner:influxdb-api] removed v1 authorization ${p.as}; its buckets and their data stay`);
      }
    },
    // Asked every minute by the harness: whether InfluxDB still holds this consumer's authorization
    // exactly as the mesh gave it, so one deleted, disabled or re-passworded behind the mesh's back is
    // made whole again (hq issue 120).
    async holds(p: Provision): Promise<boolean> {
      return grants.holds(p);
    },
  });
 }
@@ -1,246 +0,0 @@
 // What holds influxdb to the `influxdb-api` provision (grants.ts): one v1 authorization per consumer,
 // under the username and password the mesh gave, allowed only what the consumer contributed; made
 // once and brought back on every apply; buckets created when missing and never deleted; and an
 // authorization the mesh did not make — same name or not — never adopted, changed or deleted.
 //
 // InfluxDB is a fake: the routes the module touches, answering with the status codes and shapes
 // InfluxDB 2.9 gives (a filter matching nothing is a 404, a password outside 8–72 characters a 400,
 // an inactive authorization or a wrong password a 401 on /query). Run against the compiled module
 // (npm test builds first), the way the runtime loads it.
 import { test, after, beforeEach } from "node:test";
 import assert from "node:assert/strict";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { InfluxDBClient } from "../dist/client.js";
 import { ApiGrants, MARK, askedFor, marked } from "../dist/grants.js";
 type Rec = Record<string, any>;
 const ADMIN = "operator-token";
 const orgs = new Map<string, string>([["zurag", "org1"]]);
 let buckets: Rec[] = [];
 let auths: Rec[] = [];
 let calls: string[] = [];
 let seq = 0;
 function body(req: IncomingMessage): Promise<any> {
  return new Promise((resolve) => {
    let raw = "";
    req.on("data", (c) => (raw += c));
    req.on("end", () => resolve(raw ? JSON.parse(raw) : undefined));
  });
 }
 function send(res: ServerResponse, status: number, value?: unknown): void {
  res.writeHead(status, { "Content-Type": "application/json" });
  res.end(value === undefined ? "" : JSON.stringify(value));
 }
 const server = createServer(async (req, res) => {
  const url = new URL(req.url!, "http://fake");
  const p = url.pathname;
  calls.push(`${req.method} ${p}`);
  if (p === "/query") {
    const basic = (req.headers.authorization ?? "").replace(/^Basic /, "");
    const [u, pw] = Buffer.from(basic, "base64").toString().split(":");
    const a = auths.find((x) => x.token === u);
    if (!a || a.status !== "active" || a.password === undefined || a.password !== pw) {
      return send(res, 401, { code: "unauthorized", message: "Unauthorized" });
    }
    return send(res, 200, { results: [{ statement_id: 0 }] });
  }
  if (req.headers.authorization !== `Token ${ADMIN}`) return send(res, 401, { code: "unauthorized" });
  if (p === "/api/v2/orgs") {
    const id = orgs.get(url.searchParams.get("org") ?? "");
    if (!id) return send(res, 404, { code: "not found", message: "organization name not found" });
    return send(res, 200, { orgs: [{ id, name: url.searchParams.get("org") }] });
  }
  if (p === "/api/v2/buckets" && req.method === "GET") {
    const found = buckets.filter((b) => b.orgID === url.searchParams.get("orgID") && b.name === url.searchParams.get("name"));
    if (found.length === 0) return send(res, 404, { code: "not found", message: "bucket not found" });
    return send(res, 200, { buckets: found });
  }
  if (p === "/api/v2/buckets" && req.method === "POST") {
    const b = { ...(await body(req)), id: `b${++seq}` };
    buckets.push(b);
    return send(res, 201, b);
  }
  if (p === "/private/legacy/authorizations" && req.method === "GET") {
    const found = auths.filter((a) => a.token === url.searchParams.get("token"));
    if (found.length === 0) return send(res, 404, { code: "not found", message: "authorization not found" });
    // Never answers with the password: InfluxDB keeps only its hash.
    return send(res, 200, { authorizations: found.map(({ password, ...a }) => ({ ...a, links: {} })) });
  }
  if (p === "/private/legacy/authorizations" && req.method === "POST") {
    const a = await body(req);
    if (auths.some((x) => x.token === a.token)) return send(res, 409, { code: "conflict", message: "token already exists" });
    const made = { ...a, id: `a${++seq}`, status: a.status ?? "active" };
    auths.push(made);
    return send(res, 201, made);
  }
  const m = /^\/private\/legacy\/authorizations\/([^/]+)(\/password)?$/.exec(p);
  const a = m && auths.find((x) => x.id === m[1]);
  if (!a) return send(res, 404, { code: "not found" });
  if (m![2] && req.method === "POST") {
    const { password } = await body(req);
    if (typeof password !== "string" || password.length < 8 || password.length > 72) {
      return send(res, 400, { code: "invalid", message: "passwords must be between 8 and 72 characters long" });
    }
    a.password = password;
    return send(res, 204);
  }
  if (req.method === "PATCH") {
    Object.assign(a, await body(req));
    return send(res, 200, a);
  }
  if (req.method === "DELETE") {
    auths = auths.filter((x) => x !== a);
    return send(res, 204);
  }
  send(res, 405);
 });
 await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
 after(() => server.close());
 const port = (server.address() as { port: number }).port;
 const grants = new ApiGrants(new InfluxDBClient(`http://127.0.0.1:${port}`, ADMIN, "zurag"), "zurag");
 const PW = "mesh-minted-password-of-forty-characters";
 /** Grafana on ace, as the mesh hands it to the provisioner. */
 function grafana(password = PW, values: Record<string, unknown> = { access: "read" }) {
  return { as: "mesh_ace_grafana", password, consumer: "ace", values };
 }
 /** Node-RED on ace: writes one bucket. */
 function nodered(password = PW, values: Record<string, unknown> = { access: "write", buckets: ["zurag"] }) {
  return { as: "mesh_ace_nodered", password, consumer: "ace", values };
 }
 function only(token: string): Rec {
  const found = auths.filter((a) => a.token === token);
  assert.equal(found.length, 1, `exactly one authorization ${token}, found ${found.length}`);
  return found[0];
 }
 function perms(a: Rec): string[] {
  return a.permissions.map((p: Rec) => `${p.action}:${p.resource.type}:${p.resource.id ?? "*"}`).sort();
 }
 beforeEach(() => {
  buckets = [{ id: "zb", orgID: "org1", name: "zurag" }];
  auths = [];
  calls = [];
 });
 test("what a contribution may ask for, and what is refused", () => {
  assert.deepEqual(askedFor({}), { access: "read", buckets: [] });
  assert.deepEqual(askedFor({ access: "read-write", buckets: ["b", "a", "a"] }), { access: "read-write", buckets: ["a", "b"] });
  assert.throws(() => askedFor({ access: "admin" }), /access/);
  assert.throws(() => askedFor({ access: "write" }), /names no bucket/);
  assert.throws(() => askedFor({ buckets: "zurag" }), /list of bucket names/);
  assert.throws(() => askedFor({ access: "write", buckets: ["_monitoring"] }), /system bucket/);
 });
 test("a reader is given one authorization, reading every bucket of the org, under the mesh's password", async () => {
  assert.equal(await grants.ensure(grafana()), "created");
  const a = only("mesh_ace_grafana");
  assert.equal(a.orgID, "org1");
  assert.equal(a.status, "active");
  assert.ok(a.description.startsWith(MARK));
  assert.deepEqual(perms(a), ["read:buckets:*"]);
  assert.equal(a.password, PW);
  assert.equal(await grants.holds(grafana()), true);
 });
 test("a writer is allowed its own buckets only, and a missing one is made — never deleted", async () => {
  assert.equal(await grants.ensure(nodered(PW, { access: "write", buckets: ["zurag", "printer"] })), "created");
  const made = buckets.find((b) => b.name === "printer");
  assert.ok(made, "the missing bucket was created");
  assert.deepEqual(made!.retentionRules, [], "kept for ever: retention is the operator's choice");
  assert.deepEqual(perms(only("mesh_ace_nodered")), [`write:buckets:${made!.id}`, "write:buckets:zb"]);
  assert.equal(await grants.remove("mesh_ace_nodered"), "removed");
  assert.equal(buckets.length, 2, "withdrawing the consumer leaves every bucket and its data");
 });
 test("applying the same grant again writes nothing", async () => {
  await grants.ensure(grafana());
  calls = [];
  assert.equal(await grants.ensure(grafana()), "unchanged");
  assert.ok(calls.every((c) => c.startsWith("GET")), `only reads: ${calls.join(", ")}`);
  only("mesh_ace_grafana");
 });
 test("a rotated password is set in place; a changed access remakes only the mesh's own", async () => {
  await grants.ensure(nodered());
  const id = only("mesh_ace_nodered").id;
  assert.equal(await grants.holds(nodered("rotated-password-0123456789")), false);
  assert.equal(await grants.ensure(nodered("rotated-password-0123456789")), "updated");
  assert.equal(only("mesh_ace_nodered").id, id, "updated, not replaced");
  assert.equal(await grants.holds(nodered("rotated-password-0123456789")), true);
  await grants.ensure(nodered(PW, { access: "read-write", buckets: ["zurag"] }));
  assert.deepEqual(perms(only("mesh_ace_nodered")), ["read:buckets:zb", "write:buckets:zb"]);
  assert.equal(await grants.holds(nodered(PW, { access: "read-write", buckets: ["zurag"] })), true);
 });
 test("an authorization disabled, re-passworded or deleted behind the mesh's back is not held, and is made whole", async () => {
  await grants.ensure(grafana());
  only("mesh_ace_grafana").status = "inactive";
  assert.equal(await grants.holds(grafana()), false);
  assert.equal(await grants.ensure(grafana()), "updated");
  assert.equal(await grants.holds(grafana()), true);
  only("mesh_ace_grafana").password = "somebody-else-set-this";
  assert.equal(await grants.holds(grafana()), false);
  await grants.ensure(grafana());
  assert.equal(await grants.holds(grafana()), true);
  auths = [];
  assert.equal(await grants.holds(grafana()), false);
  assert.equal(await grants.ensure(grafana()), "created");
 });
 test("holds only reads, and a bucket gone missing is not held rather than made", async () => {
  await grants.ensure(nodered());
  buckets = [];
  calls = [];
  assert.equal(await grants.holds(nodered()), false);
  assert.ok(calls.every((c) => c.startsWith("GET")), `only reads: ${calls.join(", ")}`);
  assert.equal(buckets.length, 0);
 });
 test("an authorization of the same name the mesh did not make is refused, and left exactly as it was", async () => {
  auths = [{ id: "theirs", token: "mesh_ace_grafana", orgID: "org1", status: "active", description: "hand-made",
    permissions: [{ action: "write", resource: { type: "buckets", orgID: "org1" } }], password: "their-password" }];
  const before = JSON.stringify(auths);
  await assert.rejects(grants.ensure(grafana()), /did not make/);
  assert.equal(JSON.stringify(auths), before);
  assert.ok(calls.every((c) => c.startsWith("GET")), `only reads: ${calls.join(", ")}`);
  assert.equal(await grants.holds(grafana()), false);
  assert.equal(await grants.remove("mesh_ace_grafana"), "not ours");
  assert.equal(auths.length, 1, "never deleted");
 });
 test("the predecessor's own v1 users and tokens are never touched", async () => {
  auths = [{ id: "hal", token: "grafana", orgID: "org1", status: "active", description: "",
    permissions: [{ action: "read", resource: { type: "buckets", orgID: "org1" } }], password: "old-password" }];
  await grants.ensure(grafana());
  assert.equal(auths.find((a) => a.id === "hal")!.password, "old-password");
  assert.equal(await grants.remove("grafana"), "not ours");
  assert.equal(marked({ token: "grafana", description: `${MARK} x` }), false, "the mark needs the mesh's name too");
 });
 test("an org the instance does not have, or a non-mesh name, makes nothing", async () => {
  const elsewhere = new ApiGrants(new InfluxDBClient(`http://127.0.0.1:${port}`, ADMIN, "nope"), "nope");
  await assert.rejects(elsewhere.ensure(grafana()), /no org "nope"/);
  await assert.rejects(grants.ensure({ ...grafana(), as: "grafana" }), /not a mesh identity/);
  assert.equal(auths.length, 0);
 });
 test("a withdrawn consumer's authorization is removed, and an absent one is not an error", async () => {
  await grants.ensure(grafana());
  assert.equal(await grants.remove("mesh_ace_grafana"), "removed");
  assert.equal(auths.length, 0);
  assert.equal(await grants.remove("mesh_ace_grafana"), "absent");
 });
@@ -8,10 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": [
+  "include": ["client.ts", "tools/index.ts"]
    "client.ts",
    "grants.ts",
    "provisioner/index.ts",
    "tools/index.ts"
  ]
 }
@@ -17,7 +17,7 @@ FROM ${BUILD_BASE} AS build
 # resolved away.
 WORKDIR /app/modules/keycloak
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
@@ -27,4 +27,4 @@ COPY --from=build /app/modules/keycloak/dist /app/modules/keycloak/dist
 # the convention novox/hq issues 060/061 settled. A container that instead ran only its
 # provisioner (`run`) served no tools and emitted no events; a container that named no command
 # ran no provisioner at all.
-ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js,/app/modules/keycloak/dist/provisioner/index.js
+ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js
@@ -12,45 +12,6 @@ function meshConfig(file?: string): Record<string, string> {
  catch { return {}; }
 }
 /** A secret file's value, trailing newline trimmed; undefined when unset or unreadable. */
 function secretFile(file?: string): string | undefined {
  if (!file) return undefined;
  try { return readFileSync(file, "utf8").replace(/\n$/, "") || undefined; }
  catch { return undefined; }
 }
 /** A client as the admin API represents it — only the fields this module reads or writes are typed;
 *  the rest travel through untouched, so an update never drops what somebody else set. */
 export interface ClientRepresentation {
  id?: string;
  clientId: string;
  name?: string;
  enabled?: boolean;
  protocol?: string;
  publicClient?: boolean;
  clientAuthenticatorType?: string;
  secret?: string;
  rootUrl?: string;
  baseUrl?: string;
  redirectUris?: string[];
  webOrigins?: string[];
  standardFlowEnabled?: boolean;
  implicitFlowEnabled?: boolean;
  directAccessGrantsEnabled?: boolean;
  serviceAccountsEnabled?: boolean;
  attributes?: Record<string, string>;
  protocolMappers?: ProtocolMapperRepresentation[];
  [other: string]: unknown;
 }
 export interface ProtocolMapperRepresentation {
  id?: string;
  name: string;
  protocol: string;
  protocolMapper: string;
  config: Record<string, string>;
 }
 export class KeycloakClient {
  readonly baseUrl: string;
  readonly defaultRealm: string;
@@ -79,13 +40,8 @@ export class KeycloakClient {
    const cfg = meshConfig(env.MESH_KEYCLOAK_CONFIG_FILE);
    const url = cfg.url ?? env.MESH_KEYCLOAK_URL ?? `http://127.0.0.1:${env.KEYCLOAK_PORT ?? "8080"}`;
    const adminUser = cfg.user ?? env.MESH_KEYCLOAK_ADMIN ?? env.KEYCLOAK_ADMIN ?? "admin";
-    // The admin password reaches the runtime as a file (novox/hq ADR 0086): the module's own `admin`
+    const adminPass = cfg.password ?? env.MESH_KEYCLOAK_PASSWORD ?? env.KEYCLOAK_ADMIN_PASSWORD;
-    // secret, mounted read-only. The environment forms stay for a co-located server that has them.
+    if (!adminPass) throw new Error("no Keycloak admin password — set MESH_KEYCLOAK_PASSWORD");
    const adminPass = cfg.password ?? secretFile(env.MESH_KEYCLOAK_PASSWORD_FILE)
      ?? env.MESH_KEYCLOAK_PASSWORD ?? env.KEYCLOAK_ADMIN_PASSWORD;
    if (!adminPass) {
      throw new Error("no Keycloak admin password — set MESH_KEYCLOAK_PASSWORD_FILE (or MESH_KEYCLOAK_PASSWORD)");
    }
    const realm = cfg.realm ?? env.MESH_KEYCLOAK_REALM ?? "master";
    return new KeycloakClient(url, adminUser, adminPass, realm);
  }
@@ -203,50 +159,6 @@ export class KeycloakClient {
    return client.id as string;
  }
  /** The one client with exactly this clientId, or undefined. The admin API's `clientId` filter is an
   *  exact match unless `search=true` is asked for. */
  async findClient(realm: string, clientId: string): Promise<ClientRepresentation | undefined> {
    const found = await this.request<ClientRepresentation[]>(
      `/${realm}/clients?clientId=${encodeURIComponent(clientId)}`);
    return found.find((c) => c.clientId === clientId);
  }
  async createClientFrom(realm: string, rep: ClientRepresentation): Promise<void> {
    await this.request(`/${realm}/clients`, { method: "POST", body: JSON.stringify(rep) });
  }
  /** Replace a client's representation, addressed by its internal id. */
  async updateClient(realm: string, id: string, rep: ClientRepresentation): Promise<void> {
    await this.request(`/${realm}/clients/${id}`, { method: "PUT", body: JSON.stringify(rep) });
  }
  async deleteClientById(realm: string, id: string): Promise<void> {
    await this.request(`/${realm}/clients/${id}`, { method: "DELETE" });
  }
  async clientSecretById(realm: string, id: string): Promise<string | undefined> {
    const result = await this.request<{ value?: string }>(`/${realm}/clients/${id}/client-secret`);
    return result.value;
  }
  async listClientMappers(realm: string, id: string): Promise<ProtocolMapperRepresentation[]> {
    return this.request(`/${realm}/clients/${id}/protocol-mappers/models`);
  }
  async addClientMapper(realm: string, id: string, mapper: ProtocolMapperRepresentation): Promise<void> {
    await this.request(`/${realm}/clients/${id}/protocol-mappers/models`, {
      method: "POST",
      body: JSON.stringify(mapper),
    });
  }
  async updateClientMapper(realm: string, id: string, mapper: ProtocolMapperRepresentation): Promise<void> {
    await this.request(`/${realm}/clients/${id}/protocol-mappers/models/${mapper.id}`, {
      method: "PUT",
      body: JSON.stringify(mapper),
    });
  }
  async deleteClient(realm: string, clientId: string): Promise<void> {
    await this.request(`/${realm}/clients/${await this.resolveClientId(realm, clientId)}`, { method: "DELETE" });
  }
@@ -1,12 +1,6 @@
 {
  "module": "keycloak",
  "version": "1",
  "provides": [
    {
      "name": "oidc-client",
      "scope": "mesh"
    }
  ],
  "requires": [
    "postgres-database",
    "route"
@@ -47,19 +41,6 @@
      "why": "anything the mesh runs that authenticates a person"
    }
  ],
  "serves": {
    "oidc-client": {
      "authorization-path": "/protocol/openid-connect/auth",
      "token-path": "/protocol/openid-connect/token",
      "userinfo-path": "/protocol/openid-connect/userinfo"
    }
  },
  "receives": {
    "oidc-client": "/var/lib/keycloak/grants/mesh.json"
  },
  "grants": {
    "oidc-client": "/var/lib/keycloak/grants"
  },
  "own-secrets": {
    "admin": "/var/lib/keycloak/admin.secret",
    "broker": "/var/lib/mesh/keycloak/broker"
@@ -77,12 +58,6 @@
      "path": "/var/lib/keycloak",
      "mode": "0700"
    },
    {
      "id": "grants",
      "type": "directory",
      "path": "/var/lib/keycloak/grants",
      "mode": "0700"
    },
    {
      "id": "admin-env",
      "type": "file",
@@ -102,13 +77,6 @@
      "type": "network",
      "name": "keycloak"
    },
    {
      "id": "hostname",
      "type": "file",
      "path": "/var/lib/keycloak/hostname.env",
      "mode": "0644",
      "content": "KC_HOSTNAME=https://${bound:route:name}\n"
    },
    {
      "id": "server",
      "type": "container",
@@ -122,20 +90,17 @@
        "KC_DB": "postgres",
        "KC_HTTP_ENABLED": "true",
        "KC_HEALTH_ENABLED": "true",
        "KC_HOSTNAME": "https://keycloak.novox.be",
        "KC_PROXY_HEADERS": "xforwarded"
      },
      "env-file": [
        "/var/lib/keycloak/admin.env",
-        "/var/lib/keycloak/database.env",
+        "/var/lib/keycloak/database.env"
        "/var/lib/keycloak/hostname.env"
      ],
      "ports": [
        "8080"
      ],
-      "secrets-in-environment": "KC_DB_PASSWORD is convertible through a generated keycloak.conf (db-password=); KEYCLOAK_ADMIN_PASSWORD is env-only before Keycloak 26; not yet converted",
+      "secrets-in-environment": "KC_DB_PASSWORD is convertible through a generated keycloak.conf (db-password=); KEYCLOAK_ADMIN_PASSWORD is env-only before Keycloak 26; not yet converted"
      "restart-on": [
        "hostname"
      ]
    },
    {
      "id": "runtime-config",
@@ -152,16 +117,12 @@
      "network": "host",
      "volumes": [
        "/var/lib/mesh/keycloak/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/keycloak/config.json:/run/config/config.json:ro",
+        "/var/lib/mesh/keycloak/config.json:/run/config/config.json:ro"
        "/var/lib/keycloak/admin.secret:/run/secrets/admin:ro",
        "/var/lib/keycloak/grants:/var/lib/keycloak/grants:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
        "MESH_KEYCLOAK_URL": "http://127.0.0.1:${port:8080}",
-        "MESH_KEYCLOAK_CONFIG_FILE": "/run/config/config.json",
+        "MESH_KEYCLOAK_CONFIG_FILE": "/run/config/config.json"
        "MESH_KEYCLOAK_PASSWORD_FILE": "/run/secrets/admin",
        "MESH_RECEIVES": "/var/lib/keycloak/grants/mesh.json"
      },
      "restart-on": [
        "runtime-config"
@@ -1,185 +0,0 @@
 // What the `oidc-client` provision means in Keycloak: one confidential OpenID Connect client per
 // consumer, in the realm this module serves, under the name and secret the mesh gave both ends.
 // The provisioner (provisioner/index.ts) is the sdk harness calling these; they are here, apart from
 // it, so they can be exercised against a fake admin API without a broker or a contributions file.
 //
 // **The client id and the secret are the mesh's, not Keycloak's (novox/hq ADR 0048).** The mesh
 // derives the consumer's identity (`as`, e.g. `mesh_ace_grafana`) and hands it to both ends — the
 // consumer names it as its client id through `${bound:oidc-client:as}` — and mints the secret, which
 // this sets as the client's secret. Keycloak generates neither.
 //
 // **Where the consumer's browser comes back to is the consumer's to say.** Its contribution carries
 // `callback` (a path, e.g. `/login/generic_oauth`) and the `label`/`endpoint` of the endpoint it is
 // reached on; the mesh composes that endpoint's names into `name` (public) and `internal-name`
 // (private network) exactly as it does for a route (novox/hq ADR 0056, 0138), so the redirect URI
 // registered here is built from the same names the proxy serves the consumer under.
 //
 // **Only what the mesh made is touched.** A client this module creates carries the attribute
 // `mesh.provisioned=true`, and its id starts with the mesh's own prefix. A client with the same id
 // that lacks the mark is somebody else's: it is refused, never adopted, never updated, never deleted.
 import type { ClientRepresentation, KeycloakClient, ProtocolMapperRepresentation } from "./client.js";
 /** The attribute marking a client as the mesh's own work. */
 export const MARK = "mesh.provisioned";
 /** The mapper every mesh client carries: realm roles as a flat `roles` claim in the id token, the
 *  access token and userinfo — what a consumer maps its own roles from (grafana's role path reads
 *  `roles[*]`), and what the predecessor added to its hand-made clients by hand. */
 export const ROLES_MAPPER: ProtocolMapperRepresentation = {
  name: "realm roles",
  protocol: "openid-connect",
  protocolMapper: "oidc-usermodel-realm-role-mapper",
  config: {
    "claim.name": "roles",
    "jsonType.label": "String",
    multivalued: "true",
    "id.token.claim": "true",
    "access.token.claim": "true",
    "userinfo.token.claim": "true",
  },
 };
 /** One consumer, as the harness hands it over. */
 export interface OidcGrant {
  readonly as: string;
  readonly password: string;
  readonly values: Readonly<Record<string, unknown>>;
  readonly consumer?: string;
 }
 /** The realm named by an issuer URL — `https://id.example/realms/Novox` is realm `Novox`. The issuer is
 *  the one value an assignment sets (it is also what consumers are served), so the realm is read
 *  out of it rather than set a second time where the two could disagree. */
 export function realmOf(issuer: string): string {
  let path: string;
  try {
    path = new URL(issuer).pathname;
  } catch {
    throw new Error(`the issuer ${JSON.stringify(issuer)} is not a URL`);
  }
  const m = /\/realms\/([^/]+)\/?$/.exec(path);
  if (!m) throw new Error(`the issuer ${JSON.stringify(issuer)} does not end in /realms/<realm>`);
  return decodeURIComponent(m[1]);
 }
 /** The redirect URIs a consumer's contribution asks for: its callback under each name the mesh
 *  composed for its endpoint. Refused when there is nothing to register — a client that accepts no
 *  redirect is a client nobody can log in through, and one that accepts any is worse. */
 export function redirectsOf(values: Readonly<Record<string, unknown>>): { root: string; redirects: string[] } {
  const callback = values.callback;
  if (typeof callback !== "string" || !callback.startsWith("/")) {
    throw new Error(`contributes no callback path (\`callback\`, starting with "/"): ${JSON.stringify(callback)}`);
  }
  const names: string[] = [];
  for (const key of ["name", "internal-name"]) {
    const n = values[key];
    if (typeof n === "string" && n.trim() !== "" && !names.includes(n.trim())) names.push(n.trim());
  }
  if (names.length === 0) {
    throw new Error("has no name the mesh composed (`name` / `internal-name`) — contribute a `label` and the `endpoint` it is reached on");
  }
  return { root: `https://${names[0]}`, redirects: names.map((n) => `https://${n}${callback}`) };
 }
 /** The fields the mesh owns on a client it made. Everything else on the client is left as found. */
 function wanted(g: OidcGrant): ClientRepresentation {
  const { root, redirects } = redirectsOf(g.values);
  return {
    clientId: g.as,
    name: g.as,
    description: `made by the mesh for ${g.consumer ? `a module on ${g.consumer}` : "a consumer"} — do not edit; it is reset`,
    enabled: true,
    protocol: "openid-connect",
    publicClient: false,
    clientAuthenticatorType: "client-secret",
    secret: g.password,
    rootUrl: root,
    baseUrl: root,
    redirectUris: redirects,
    standardFlowEnabled: true,
    implicitFlowEnabled: false,
    directAccessGrantsEnabled: false,
    serviceAccountsEnabled: false,
  };
 }
 function sameSet(a: readonly string[] | undefined, b: readonly string[]): boolean {
  const x = [...(a ?? [])].sort();
  const y = [...b].sort();
  return x.length === y.length && x.every((v, i) => v === y[i]);
 }
 function marked(c: ClientRepresentation): boolean {
  return c.attributes?.[MARK] === "true";
 }
 export class OidcClients {
  constructor(private readonly kc: KeycloakClient, readonly realm: string) {}
  /** Create the consumer's client, or bring the mesh's existing one back to what the grant says.
   *  Returns whether it was newly created. Idempotent: applying the same grant twice changes nothing
   *  the second time beyond re-asserting it. */
  async ensure(g: OidcGrant): Promise<"created" | "updated"> {
    const want = wanted(g);
    const found = await this.kc.findClient(this.realm, g.as);
    if (found && !marked(found)) {
      throw new Error(
        `realm ${this.realm} already has a client ${g.as} the mesh did not make — left alone; ` +
          `delete or rename it if the mesh should own that id`);
    }
    if (!found) {
      await this.kc.createClientFrom(this.realm, {
        ...want,
        attributes: { [MARK]: "true" },
        protocolMappers: [ROLES_MAPPER],
      });
      return "created";
    }
    // Overlay what the mesh owns on what is there, so a field Keycloak added or an operator set on a
    // field the mesh does not own survives the update.
    await this.kc.updateClient(this.realm, found.id!, {
      ...found,
      ...want,
      attributes: { ...(found.attributes ?? {}), [MARK]: "true" },
    });
    await this.ensureMapper(found.id!);
    return "updated";
  }
  private async ensureMapper(id: string): Promise<void> {
    const mappers = await this.kc.listClientMappers(this.realm, id);
    const have = mappers.find((m) => m.name === ROLES_MAPPER.name);
    if (!have) {
      await this.kc.addClientMapper(this.realm, id, ROLES_MAPPER);
      return;
    }
    const drifted =
      have.protocolMapper !== ROLES_MAPPER.protocolMapper ||
      Object.entries(ROLES_MAPPER.config).some(([k, v]) => have.config?.[k] !== v);
    if (drifted) {
      await this.kc.updateClientMapper(this.realm, id, { ...ROLES_MAPPER, id: have.id });
    }
  }
  /** Whether Keycloak still holds this consumer's client exactly as the grant says: present, the
   *  mesh's, enabled, confidential, with the mesh's secret and the redirects asked for. Reads only. */
  async holds(g: OidcGrant): Promise<boolean> {
    const want = wanted(g);
    const found = await this.kc.findClient(this.realm, g.as);
    if (!found || !marked(found) || found.enabled === false || found.publicClient) return false;
    if (!sameSet(found.redirectUris, want.redirectUris!)) return false;
    const mappers = await this.kc.listClientMappers(this.realm, found.id!);
    if (!mappers.some((m) => m.name === ROLES_MAPPER.name)) return false;
    return (await this.kc.clientSecretById(this.realm, found.id!)) === g.password;
  }
  /** Withdraw a consumer's client — only one the mesh made. Returns what happened, for the log. */
  async remove(as: string): Promise<"removed" | "absent" | "not ours"> {
    const found = await this.kc.findClient(this.realm, as);
    if (!found) return "absent";
    if (!marked(found)) return "not ours";
    await this.kc.deleteClientById(this.realm, found.id!);
    return "removed";
  }
 }
@@ -1,15 +1,11 @@
 {
  "name": "@novox/module-keycloak",
  "version": "0.1.0",
-  "description": "keycloak — identity and access; provides the mesh oidc-client interface. Its admin API client, provisioner, tools and events live here (novox/hq ADR 0039).",
+  "description": "keycloak — identity and access. Its admin API client, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
  },
  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.1"
+    "@novox/mesh-sdk": "^0.1.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
@@ -1,73 +0,0 @@
 // keycloak's provisioner — the adapter that makes keycloak a provider of the mesh `oidc-client`
 // interface. The reconcile loop, the contributions file and reading the mesh's minted secret are the
 // sdk harness's; this writes only the per-service half: how Keycloak creates, checks and removes a
 // consumer's client (novox/hq ADR 0039/0040/0048). What a client is, and which ones are the mesh's,
 // is in ../oidc.ts.
 //
 // The `oidc-client` interface: a consumer logs people in through the realm this module serves, as
 // the confidential client `as` with the secret the mesh minted, and is redirected back to the
 // callback it contributed under the names the mesh composed for its endpoint. What it is served —
 // the issuer and the endpoint paths under it — is in the manifest's `serves`, settled with the
 // assignment's settings.
 //
 // **The realm is read out of the issuer**, the one value an assignment sets (settings reach both the
 // served facts and this module's config.json): a realm set in one place and an issuer in another
 // would let the consumer be told one realm while its client is made in another.
 import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
 import { emit } from "@novox/mesh-sdk/events";
 import { readFileSync } from "node:fs";
 import { KeycloakClient } from "../client.js";
 import { OidcClients, realmOf } from "../oidc.js";
 /** The issuer this assignment serves, from the settings-merged config the mesh delivers. */
 function issuer(): string {
  const file = process.env.MESH_KEYCLOAK_CONFIG_FILE;
  let cfg: Record<string, unknown> = {};
  if (file) {
    try {
      cfg = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
    } catch {
      // Absent or unreadable: fall through to the environment, and refuse below if that is empty too.
    }
  }
  const said = typeof cfg.issuer === "string" ? cfg.issuer : process.env.MESH_KEYCLOAK_ISSUER;
  if (!said) throw new Error("no issuer — the module's config.json carries none and MESH_KEYCLOAK_ISSUER is unset");
  return said;
 }
 const clients = new OidcClients(KeycloakClient.fromEnv(), realmOf(issuer()));
 /** Emit a lifecycle event without letting a broker hiccup fail the provisioning itself. */
 async function announce(type: string, body: Record<string, string>): Promise<void> {
  try {
    await emit(type, body);
  } catch (err) {
    console.error(`[provisioner:oidc-client] emit ${type} failed: ${err}`);
  }
 }
 runProvisioner("oidc-client", {
  async create(p: Provision): Promise<void> {
    const done = await clients.ensure(p);
    if (done === "created") {
      console.log(`[provisioner:oidc-client] created client ${p.as} in realm ${clients.realm}`);
      await announce("client.created", { realm: clients.realm, clientId: p.as, consumer: p.consumer ?? "" });
    }
  },
  async remove(p: { as: string }): Promise<void> {
    const done = await clients.remove(p.as);
    if (done === "not ours") {
      console.error(`[provisioner:oidc-client] ${p.as}: a client of that id exists that the mesh did not make — left alone`);
    } else if (done === "removed") {
      console.log(`[provisioner:oidc-client] removed client ${p.as} from realm ${clients.realm}`);
    }
  },
  // Asked every minute by the harness: whether Keycloak still holds this consumer's client exactly as
  // the mesh gave it, so a client deleted or edited behind the mesh's back is made again (hq issue 120).
  async holds(p: Provision): Promise<boolean> {
    return clients.holds(p);
  },
 });
@@ -1,239 +0,0 @@
 // What holds keycloak to the `oidc-client` provision (oidc.ts): one confidential client per consumer,
 // under the id and secret the mesh gave, redirecting only to the consumer's own callback under the
 // names the mesh composed; made once and brought back on every apply; and a client the mesh did not
 // make — same id or not — never adopted, changed or deleted.
 //
 // Keycloak is a fake: the admin routes the module touches, answering with the status codes and the
 // shapes Keycloak gives. Run against the compiled module (npm test builds first), the way the runtime
 // loads it.
 import { test, after } from "node:test";
 import assert from "node:assert/strict";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { randomUUID } from "node:crypto";
 import { KeycloakClient } from "../dist/client.js";
 import { MARK, OidcClients, ROLES_MAPPER, realmOf, redirectsOf } from "../dist/oidc.js";
 type Client = Record<string, any>;
 /** The realm's clients, by internal id, and what the fake was asked. */
 const realm = "Novox";
 const clients = new Map<string, Client>();
 const calls: string[] = [];
 function body(req: IncomingMessage): Promise<any> {
  return new Promise((resolve) => {
    let raw = "";
    req.on("data", (c) => (raw += c));
    req.on("end", () => resolve(raw ? JSON.parse(raw) : undefined));
  });
 }
 function send(res: ServerResponse, status: number, value?: unknown): void {
  res.writeHead(status, { "Content-Type": "application/json" });
  res.end(value === undefined ? "" : JSON.stringify(value));
 }
 const server = createServer(async (req, res) => {
  const url = new URL(req.url!, "http://fake");
  calls.push(`${req.method} ${url.pathname}`);
  if (url.pathname === "/realms/master/protocol/openid-connect/token") {
    return send(res, 200, { access_token: "t", expires_in: 300 });
  }
  const base = `/admin/realms/${realm}/clients`;
  if (!url.pathname.startsWith(base)) return send(res, 404, { error: "Realm not found." });
  const rest = url.pathname.slice(base.length).split("/").filter(Boolean);
  if (rest.length === 0 && req.method === "GET") {
    const want = url.searchParams.get("clientId");
    return send(res, 200, [...clients.values()].filter((c) => !want || c.clientId === want));
  }
  if (rest.length === 0 && req.method === "POST") {
    const rep = await body(req);
    if ([...clients.values()].some((c) => c.clientId === rep.clientId)) {
      return send(res, 409, { errorMessage: `Client ${rep.clientId} already exists` });
    }
    const id = randomUUID();
    const mappers = (rep.protocolMappers ?? []).map((m: Client) => ({ ...m, id: randomUUID() }));
    clients.set(id, { ...rep, id, protocolMappers: mappers });
    return send(res, 201);
  }
  const c = clients.get(rest[0]);
  if (!c) return send(res, 404, { error: "Could not find client" });
  if (rest.length === 1 && req.method === "PUT") {
    // Keycloak ignores protocolMappers on a client update: they have their own endpoints.
    const rep = await body(req);
    clients.set(c.id, { ...rep, id: c.id, protocolMappers: c.protocolMappers });
    return send(res, 204);
  }
  if (rest.length === 1 && req.method === "DELETE") {
    clients.delete(c.id);
    return send(res, 204);
  }
  if (rest[1] === "client-secret" && req.method === "GET") {
    return send(res, 200, { type: "secret", value: c.secret });
  }
  if (rest[1] === "protocol-mappers") {
    if (req.method === "GET") return send(res, 200, c.protocolMappers ?? []);
    if (req.method === "POST") {
      c.protocolMappers = [...(c.protocolMappers ?? []), { ...(await body(req)), id: randomUUID() }];
      return send(res, 201);
    }
    if (req.method === "PUT") {
      const m = await body(req);
      c.protocolMappers = c.protocolMappers.map((x: Client) => (x.id === rest[4] ? m : x));
      return send(res, 204);
    }
  }
  send(res, 405);
 });
 await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
 after(() => server.close());
 const port = (server.address() as { port: number }).port;
 const oidc = new OidcClients(new KeycloakClient(`http://127.0.0.1:${port}`, "admin", "pw"), realm);
 /** Grafana on ace, as the mesh hands it to the provisioner. */
 function grafana(secret = "s3cret", values: Record<string, unknown> = {}) {
  return {
    as: "mesh_ace_grafana",
    password: secret,
    consumer: "ace",
    values: {
      label: "grafana", endpoint: "web", port: 20010, callback: "/login/generic_oauth",
      name: "grafana.zurag.be", "internal-name": "grafana.ace.internal", ...values,
    },
  };
 }
 function only(clientId: string): Client {
  const found = [...clients.values()].filter((c) => c.clientId === clientId);
  assert.equal(found.length, 1, `exactly one client ${clientId}, found ${found.length}`);
  return found[0];
 }
 test("the realm is read out of the issuer, and an issuer that names none is refused", () => {
  assert.equal(realmOf("https://keycloak.novox.be/realms/Novox"), "Novox");
  assert.equal(realmOf("https://keycloak.novox.be/realms/Novox/"), "Novox");
  assert.equal(realmOf("http://127.0.0.1:18500/realms/master"), "master");
  assert.throws(() => realmOf("https://keycloak.novox.be"), /realms/);
  assert.throws(() => realmOf("keycloak"), /not a URL/);
 });
 test("the redirect is the consumer's callback under every name the mesh composed for it", () => {
  assert.deepEqual(redirectsOf(grafana().values), {
    root: "https://grafana.zurag.be",
    redirects: ["https://grafana.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"],
  });
  // A route reaching only the private network has only the internal name, and that is enough.
  assert.deepEqual(redirectsOf({ callback: "/cb", "internal-name": "x.ace.internal" }).redirects,
    ["https://x.ace.internal/cb"]);
  assert.throws(() => redirectsOf({ name: "grafana.zurag.be" }), /callback/);
  assert.throws(() => redirectsOf({ name: "grafana.zurag.be", callback: "login" }), /callback/);
  assert.throws(() => redirectsOf({ callback: "/cb" }), /label/);
 });
 test("a consumer is given one confidential client, under its id and the mesh's secret", async () => {
  clients.clear();
  assert.equal(await oidc.ensure(grafana()), "created");
  const c = only("mesh_ace_grafana");
  assert.equal(c.publicClient, false);
  assert.equal(c.clientAuthenticatorType, "client-secret");
  assert.equal(c.secret, "s3cret");
  assert.equal(c.enabled, true);
  assert.equal(c.standardFlowEnabled, true);
  assert.equal(c.directAccessGrantsEnabled, false);
  assert.equal(c.implicitFlowEnabled, false);
  assert.deepEqual(c.redirectUris, [
    "https://grafana.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"]);
  assert.equal(c.attributes[MARK], "true");
  assert.deepEqual(c.protocolMappers.map((m: Client) => m.name), [ROLES_MAPPER.name]);
  assert.equal(await oidc.holds(grafana()), true);
 });
 test("applying the same grant again makes no second client", async () => {
  clients.clear();
  await oidc.ensure(grafana());
  assert.equal(await oidc.ensure(grafana()), "updated");
  assert.equal(await oidc.ensure(grafana()), "updated");
  only("mesh_ace_grafana");
  assert.equal(only("mesh_ace_grafana").protocolMappers.length, 1, "the roles mapper is not added twice");
 });
 test("a new secret or a moved name is applied in place, and what the mesh does not own survives", async () => {
  clients.clear();
  await oidc.ensure(grafana());
  const id = only("mesh_ace_grafana").id;
  // Something the mesh does not own, set on the client after it was made.
  clients.get(id)!.consentRequired = true;
  clients.get(id)!.attributes["post.logout.redirect.uris"] = "+";
  assert.equal(await oidc.holds(grafana("rotated")), false, "a rotated secret is not held until applied");
  await oidc.ensure(grafana("rotated", { name: "dash.zurag.be" }));
  const c = only("mesh_ace_grafana");
  assert.equal(c.id, id, "updated, not replaced");
  assert.equal(c.secret, "rotated");
  assert.deepEqual(c.redirectUris, [
    "https://dash.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"]);
  assert.equal(c.rootUrl, "https://dash.zurag.be");
  assert.equal(c.consentRequired, true);
  assert.equal(c.attributes["post.logout.redirect.uris"], "+");
  assert.equal(c.attributes[MARK], "true");
  assert.equal(await oidc.holds(grafana("rotated", { name: "dash.zurag.be" })), true);
 });
 test("a client lost or edited behind the mesh's back is not held, and is made whole again", async () => {
  clients.clear();
  await oidc.ensure(grafana());
  const c = only("mesh_ace_grafana");
  c.redirectUris = ["*"];
  assert.equal(await oidc.holds(grafana()), false, "a widened redirect is not what the mesh gave");
  await oidc.ensure(grafana());
  assert.equal(await oidc.holds(grafana()), true);
  only("mesh_ace_grafana").protocolMappers = [];
  assert.equal(await oidc.holds(grafana()), false, "a client without its roles mapper is not held");
  await oidc.ensure(grafana());
  assert.equal(await oidc.holds(grafana()), true);
  clients.clear();
  assert.equal(await oidc.holds(grafana()), false);
 });
 test("a client of the same id the mesh did not make is refused, and left exactly as it was", async () => {
  clients.clear();
  clients.set("theirs", { id: "theirs", clientId: "mesh_ace_grafana", secret: "their-secret", redirectUris: ["*"] });
  const before = JSON.stringify(clients.get("theirs"));
  const writes = calls.length;
  await assert.rejects(oidc.ensure(grafana()), /did not make/);
  assert.equal(JSON.stringify(clients.get("theirs")), before);
  assert.ok(calls.slice(writes).every((c) => c.startsWith("GET") || c.startsWith("POST /realms/master")),
    `only reads were made: ${calls.slice(writes).join(", ")}`);
  assert.equal(await oidc.holds(grafana()), false);
  assert.equal(await oidc.remove("mesh_ace_grafana"), "not ours");
  assert.ok(clients.has("theirs"), "a client the mesh did not make is never deleted");
 });
 test("the predecessor's hand-made client is never touched: the mesh's has its own id", async () => {
  clients.clear();
  clients.set("hal", { id: "hal", clientId: "grafana", secret: "old", redirectUris: ["https://grafana.zurag.be/*"] });
  await oidc.ensure(grafana());
  assert.equal(clients.get("hal")!.secret, "old");
  only("mesh_ace_grafana");
  assert.equal(await oidc.remove("grafana"), "not ours");
  assert.ok(clients.has("hal"));
 });
 test("a withdrawn consumer's client is removed, and an absent one is not an error", async () => {
  clients.clear();
  await oidc.ensure(grafana());
  assert.equal(await oidc.remove("mesh_ace_grafana"), "removed");
  assert.equal([...clients.values()].length, 0);
  assert.equal(await oidc.remove("mesh_ace_grafana"), "absent");
 });
 test("a contribution with no callback makes no client at all", async () => {
  clients.clear();
  await assert.rejects(oidc.ensure({ ...grafana(), values: { name: "grafana.zurag.be" } }), /callback/);
  assert.equal(clients.size, 0);
 });
@@ -8,5 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "oidc.ts", "index.ts", "provisioner/index.ts", "tools/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts"]
 }
@@ -1,6 +1,19 @@
 {
  "module": "lidarr",
  "version": "1",
  "provides": [
    {
      "name": "lidarr-api",
      "scope": "mesh"
    }
  ],
  "serves": {
    "lidarr-api": {
      "scheme": "http",
      "port": 8686,
      "url-base": ""
    }
  },
  "capabilities": [
    "container-runtime"
  ],
@@ -75,7 +88,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_LIDARR_URL": "http://127.0.0.1:8686",
+        "MESH_LIDARR_URL": "http://127.0.0.1:${port:8686}",
        "MESH_LIDARR_CONFIG_DIR": "/var/lib/lidarr/config"
      },
      "artifact": "runtime"
@@ -81,7 +81,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NZBGET_URL": "http://127.0.0.1:6789",
+        "MESH_NZBGET_URL": "http://127.0.0.1:${port:6789}",
        "MESH_NZBGET_PASSWORD_FILE": "/run/secrets/password",
        "MESH_NZBGET_CONFIG_FILE": "/run/config/config.json",
        "MESH_NZBGET_CONFIG_DIR": "/var/lib/nzbget/config"
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/ombi
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/ombi/dist /app/modules/ombi/dist
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/ombi/dist/index.js,/app/modules/ombi/dist/tools/index.js
 # NOT dist/servarr/index.js: that is a step the host runs to completion, named by the `servarr`
 # container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
 # serving sidecar too, and exit it.
@@ -28,10 +28,15 @@
      "path": "/var/lib/mesh/ombi",
      "mode": "0700"
    },
    {
      "id": "state",
      "type": "directory",
      "mode": "0700",
      "place": "."
    },
    {
      "id": "config",
      "type": "directory",
      "path": "/services/ombi/config",
      "mode": "0700",
      "owner": "1000:1000"
    },
@@ -39,7 +44,7 @@
      "id": "server",
      "type": "container",
      "name": "ombi",
-      "image": "lscr.io/linuxserver/ombi@sha256:a6f76ac521ba01eee2e9f0c23a3fed22e56630d97a04d5eeaeaa36c1e681640d",
+      "image": "lscr.io/linuxserver/ombi@sha256:22d6ebadbaaa728571353e74dc2173719e0fb02d4eaec551a7e9d2ee99ef68ac",
      "env": {
        "PUID": "1000",
        "PGID": "1000",
@@ -49,7 +54,7 @@
        "3579"
      ],
      "volumes": [
-        "/services/ombi/config:/config"
+        "${dir:config}:/config"
      ]
    },
    {
@@ -68,24 +73,59 @@
      "volumes": [
        "/var/lib/mesh/ombi/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
-        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro",
+        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro"
        "/services/ombi/config:/var/lib/ombi/config:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_OMBI_URL": "http://127.0.0.1:3579",
+        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
-        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json",
+        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json"
        "MESH_OMBI_CONFIG_DIR": "/var/lib/ombi/config"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
    },
    {
      "id": "servarr",
      "type": "container",
      "name": "mesh-ombi-servarr",
      "network": "host",
      "run-once": true,
      "volumes": [
        "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
        "${dir:state}/sonarr-api.json:/run/servarr/sonarr-api.json:ro",
        "${dir:state}/sonarr-api.secret:/run/servarr/sonarr-api.secret:ro",
        "${dir:state}/radarr-api.json:/run/servarr/radarr-api.json:ro",
        "${dir:state}/radarr-api.secret:/run/servarr/radarr-api.secret:ro",
        "${dir:state}/lidarr-api.json:/run/servarr/lidarr-api.json:ro",
        "${dir:state}/lidarr-api.secret:/run/servarr/lidarr-api.secret:ro"
      ],
      "env": {
        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
        "MESH_SERVARR_DIR": "/run/servarr"
      },
      "args": [
        "run",
        "/app/modules/ombi/dist/servarr/index.js"
      ],
      "restart-on": [
        "bound-sonarr-api",
        "secret-sonarr-api",
        "bound-radarr-api",
        "secret-radarr-api",
        "bound-lidarr-api",
        "secret-lidarr-api"
      ],
      "artifact": "runtime"
    }
  ],
  "requires": [
-    "route"
+    "lidarr-api",
    "radarr-api",
    "route",
    "sonarr-api"
  ],
  "contributes": {
    "route": {
@@ -94,7 +134,15 @@
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/ombi/route.json"
+    "route": "${dir:state}/route.json",
    "sonarr-api": "${dir:state}/sonarr-api.json",
    "radarr-api": "${dir:state}/radarr-api.json",
    "lidarr-api": "${dir:state}/lidarr-api.json"
  },
  "secrets": {
    "sonarr-api": "${dir:state}/sonarr-api.secret",
    "radarr-api": "${dir:state}/radarr-api.secret",
    "lidarr-api": "${dir:state}/lidarr-api.secret"
  },
  "build": {
    "on": [
@@ -4,6 +4,11 @@
  "description": "ombi — media requests. Its API client, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
    "typecheck": "tsc -p tsconfig.json",
    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
  },
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
@@ -0,0 +1,59 @@
 // ombi's Servarr step — run once by the host after ombi's server starts, and run again whenever a
 // binding or pair credential it reads changes (the container's `restart-on`, novox/hq ADR 0099).
 //
 // **A step, not a loop**, for the reason route-adapter gives: everything it does is a function of
 // files the mesh writes, and the host already knows when they change. It connects to no broker.
 //
 // Exits non-zero when any app could not be put right — a refused credential, an unreachable app, an
 // ombi that cannot reach it — so the node reports the step failed and the host runs it again on the
 // next apply. It is declared last in the manifest, so its failing gates nothing else of ombi's
 // (novox/hq ADR 0136).
 //
 // Reads, per app, `<dir>/<provision>.json` (the binding) and `<dir>/<provision>.secret` (the pair
 // credential), where <dir> is MESH_SERVARR_DIR. Never prints a key.
 import { join } from "node:path";
 import { APPS, ombiReady, readBinding, readIfThere, reconcileApp, type Http } from "./settings.js";
 const dir = process.env.MESH_SERVARR_DIR ?? "/run/servarr";
 const url = process.env.MESH_OMBI_URL ?? "http://127.0.0.1:3579";
 const apiKey = (await readIfThere(process.env.MESH_OMBI_API_KEY_FILE))?.trim() ?? process.env.MESH_OMBI_API_KEY ?? "";
 const waitSeconds = Number(process.env.MESH_OMBI_WAIT_SECONDS ?? "180");
 const http: Http = { fetch: (u, init) => fetch(u, init) };
 if (!apiKey) {
  console.error("[ombi-servarr] no ombi API key — ombi's own `api-key` secret has not been accepted");
  process.exit(1);
 }
 const ombi = { url, apiKey };
 if (!(await ombiReady(http, ombi, waitSeconds * 1000))) {
  console.error(`[ombi-servarr] ombi did not answer at ${url} within ${waitSeconds}s`);
  process.exit(1);
 }
 let failed = 0;
 for (const spec of APPS) {
  const outcome = await reconcileApp(
    http,
    ombi,
    spec,
    await readBinding(join(dir, `${spec.provision}.json`)),
    await readIfThere(join(dir, `${spec.provision}.secret`)),
  );
  switch (outcome.result) {
    case "unchanged":
      console.log(`[ombi-servarr] ${outcome.app}: already as the mesh says; connection tested`);
      break;
    case "written":
      console.log(`[ombi-servarr] ${outcome.app}: wrote ${outcome.fields.join(", ")}; connection tested`);
      break;
    case "refused":
      failed++;
      console.error(`[ombi-servarr] ${outcome.app}: ${outcome.problem}`);
      break;
  }
 }
 process.exitCode = failed > 0 ? 1 : 0;
@@ -0,0 +1,304 @@
 // Where ombi reaches Sonarr, Radarr and Lidarr — decided by the mesh, written into ombi by ombi's
 // own API.
 //
 // **Why this exists.** ombi keeps its connection to each Servarr app in its own database
 // (OmbiSettings.db), not in a file, so the mesh has nowhere to write `${bound:sonarr-api:at}` for it.
 // ombi requires `sonarr-api`, `radarr-api` and `lidarr-api`; the mesh delivers, for each, a binding
 // (where the app is: `at`, and what it serves: `port`, `scheme`, `url-base`) and a pair credential
 // (the app's API key, accepted by the operator — a Servarr app has exactly one key and the mesh
 // cannot mint it). This step reads those files and makes ombi's settings say the same thing.
 //
 // **Only the connection, and only when it differs.** Host, port, TLS, base path and API key. The
 // quality profile, root folder, language profile, tags, "enabled" and every other choice an operator
 // made in ombi's settings screen are left exactly as they are: the mesh knows where the app is, not
 // what ombi should do with it. Radarr's 4K instance is a different Radarr and is not touched.
 //
 // **A credential the app refuses is never written.** Until the operator accepts the app's API key
 // for this pair, the mesh delivers a value it minted itself, which no Servarr app will ever accept
 // (novox/hq ADR 0092). Writing it would replace a working key in ombi with a dead one. So the key is
 // tried against the app first; refused, nothing for that app is written and the step fails naming
 // the `secret accept` that fixes it.
 //
 // Pure logic and a small HTTP seam, so it is tested against fake servers (test/servarr.test.ts).
 import { readFile } from "node:fs/promises";
 /** One Servarr app ombi connects to, and the shape of that connection in ombi's API. */
 export interface ServarrApp {
  /** The app, as ombi's API names it: /Settings/<app>, /Tester/<app>. */
  app: "sonarr" | "radarr" | "lidarr";
  /** The provision it is required as — the manifest's `requires`, `binds` and `secrets` key. */
  provision: string;
  /** The app's own status endpoint, which answers 401 to a wrong key. */
  statusPath: string;
  /**
   * Where the one connection sits in ombi's settings document. Radarr's is `{radarr, radarr4K}`
   * (two Radarr instances); only `radarr` is this provision's.
   */
  within?: string;
 }
 export const APPS: readonly ServarrApp[] = [
  { app: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
  { app: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status", within: "radarr" },
  { app: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
 ];
 /** The connection fields ombi keeps for an app — the only ones this step ever writes. */
 export interface Connection {
  ip: string;
  port: number;
  ssl: boolean;
  /** ombi's name for the app's URL base; null when the app is served at the root. */
  subDir: string | null;
  apiKey: string;
 }
 /** What the mesh wrote at `binds.<provision>`: the binding document (controller's boundFile). */
 export interface Binding {
  provision?: string;
  from?: string;
  at?: string;
  as?: string;
  serves?: Record<string, unknown>;
 }
 export type Wanted = { ok: true; connection: Connection; from: string } | { ok: false; problem: string };
 /**
 * The connection the mesh says ombi should use, from the binding and the pair credential.
 *
 * Refused rather than guessed when the binding cannot be dialled from ombi's own container: a
 * loopback `at` — what the mesh hands a machine that is not on the private network — is ombi's
 * container itself, not the app.
 */
 export function wanted(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Wanted {
  if (!binding) {
    return { ok: false, problem: `no binding for ${spec.provision} was delivered — the mesh writes it before this step runs` };
  }
  const at = typeof binding.at === "string" ? binding.at.trim() : "";
  const serves = binding.serves ?? {};
  const port = Number(serves.port);
  if (!at) {
    return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
  }
  if (isLoopback(at)) {
    return {
      ok: false,
      problem:
        `the ${spec.provision} binding says ${spec.app} is at ${at}, which from ombi's own container is ` +
        `ombi itself. The mesh hands loopback to a machine that is not on the private network; put it ` +
        `on the private network so ${spec.app} has an address ombi can dial`,
    };
  }
  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
    return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(serves.port)})` };
  }
  const scheme = typeof serves.scheme === "string" && serves.scheme ? serves.scheme : "http";
  if (scheme !== "http" && scheme !== "https") {
    return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}, which ombi cannot dial` };
  }
  const key = (credential ?? "").trim();
  if (!key) {
    return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
  }
  return {
    ok: true,
    from: typeof binding.from === "string" ? binding.from : "",
    connection: { ip: at, port, ssl: scheme === "https", subDir: subDirOf(serves["url-base"]), apiKey: key },
  };
 }
 /** ombi's `subDir`: the URL base with its slashes trimmed, null when there is none. */
 export function subDirOf(urlBase: unknown): string | null {
  const trimmed = typeof urlBase === "string" ? urlBase.trim().replace(/^\/+|\/+$/g, "") : "";
  return trimmed === "" ? null : trimmed;
 }
 function isLoopback(host: string): boolean {
  const h = host.toLowerCase();
  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
 }
 /** Which connection fields differ between what ombi holds and what the mesh says. Names only. */
 export function differing(current: Record<string, unknown> | undefined, want: Connection): (keyof Connection)[] {
  const now = current ?? {};
  const out: (keyof Connection)[] = [];
  if (String(now.ip ?? "") !== want.ip) out.push("ip");
  if (Number(now.port ?? 0) !== want.port) out.push("port");
  if (Boolean(now.ssl) !== want.ssl) out.push("ssl");
  if (subDirOf(now.subDir) !== want.subDir) out.push("subDir");
  if (String(now.apiKey ?? "") !== want.apiKey) out.push("apiKey");
  return out;
 }
 /** ombi's settings for the app with the connection laid over them and nothing else changed. */
 export function withConnection(current: Record<string, unknown> | undefined, want: Connection): Record<string, unknown> {
  return { ...(current ?? {}), ip: want.ip, port: want.port, ssl: want.ssl, subDir: want.subDir, apiKey: want.apiKey };
 }
 /** The app's base URL as the step dials it — the same host and port ombi will be given. */
 export function appUrl(want: Connection): string {
  const scheme = want.ssl ? "https" : "http";
  const host = want.ip.includes(":") && !want.ip.startsWith("[") ? `[${want.ip}]` : want.ip;
  return `${scheme}://${host}:${want.port}${want.subDir ? `/${want.subDir}` : ""}`;
 }
 /** How one app came out. */
 export type Outcome =
  | { app: string; result: "unchanged" }
  | { app: string; result: "written"; fields: string[] }
  | { app: string; result: "refused"; problem: string };
 /** The HTTP the step needs, so a test can stand fakes in for ombi and the apps. */
 export interface Http {
  fetch(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string }): Promise<{
    status: number;
    text(): Promise<string>;
  }>;
 }
 export interface Ombi {
  url: string;
  apiKey: string;
 }
 async function ombiCall(http: Http, ombi: Ombi, method: string, path: string, body?: unknown): Promise<unknown> {
  const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1${path}`, {
    method,
    headers: {
      ApiKey: ombi.apiKey,
      Accept: "application/json",
      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
    },
    body: body !== undefined ? JSON.stringify(body) : undefined,
  });
  const text = await res.text();
  if (res.status < 200 || res.status >= 300) {
    // The body is ombi's error, never a request echo, so it carries no key.
    throw new Error(`ombi ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
  }
  return text ? (JSON.parse(text) as unknown) : undefined;
 }
 /**
 * Does the app take this key? `true` it does, `false` it refused it (401/403), and a thrown error
 * when it could not be asked — unreachable, or answering something that is neither.
 */
 export async function appTakes(http: Http, spec: ServarrApp, want: Connection): Promise<boolean> {
  const res = await http.fetch(`${appUrl(want)}${spec.statusPath}`, {
    method: "GET",
    headers: { "X-Api-Key": want.apiKey, Accept: "application/json" },
  });
  if (res.status === 401 || res.status === 403) return false;
  if (res.status >= 200 && res.status < 300) return true;
  throw new Error(`${spec.app} answered ${res.status} at ${spec.statusPath}`);
 }
 /** The remedy for a refused key, in the controller's own words (ADR 0092). */
 export function acceptRemedy(spec: ServarrApp, from: string): string {
  return (
    `${spec.app} refuses the ${spec.provision} credential the mesh delivered, so it was not written ` +
    `into ombi. A Servarr app has one API key and the mesh cannot make it: accept ${spec.app}'s own ` +
    `key for this pair — \`secret accept <this node> ombi ${spec.provision} --provider ${from || "<its node>"} ` +
    `--from <file holding ${spec.app}'s ApiKey>\``
  );
 }
 /**
 * Bring ombi's connection to one app in line with the mesh: check the key against the app, compare,
 * write only the connection fields when they differ, then have ombi test the connection from its own
 * container. Never throws: every failure is an outcome with a reason.
 */
 export async function reconcileApp(
  http: Http,
  ombi: Ombi,
  spec: ServarrApp,
  binding: Binding | undefined,
  credential: string | undefined,
 ): Promise<Outcome> {
  const w = wanted(spec, binding, credential);
  // `in`, not `!w.ok`: the Dockerfile compiles without strict, where a boolean discriminant does not
  // narrow.
  if ("problem" in w) return { app: spec.app, result: "refused", problem: w.problem };
  const want = w.connection;
  try {
    if (!(await appTakes(http, spec, want))) {
      return { app: spec.app, result: "refused", problem: acceptRemedy(spec, w.from) };
    }
  } catch (err) {
    return {
      app: spec.app,
      result: "refused",
      problem: `${spec.app} could not be asked whether it takes the key at ${want.ip}:${want.port}: ${message(err)}`,
    };
  }
  try {
    const document = (await ombiCall(http, ombi, "GET", `/Settings/${spec.app}`)) as Record<string, unknown> | undefined;
    const current = spec.within ? (document?.[spec.within] as Record<string, unknown> | undefined) : document;
    const fields = differing(current, want);
    if (fields.length > 0) {
      const next = withConnection(current, want);
      const body = spec.within ? { ...(document ?? {}), [spec.within]: next } : next;
      const saved = await ombiCall(http, ombi, "POST", `/Settings/${spec.app}`, body);
      if (saved === false) {
        return { app: spec.app, result: "refused", problem: `ombi declined to save its ${spec.app} settings` };
      }
    }
    // ombi's own test, from ombi's own container — the path the step's check above did not take.
    const tested = (await ombiCall(http, ombi, "POST", `/Tester/${spec.app}`, withConnection(current, want))) as
      | { isValid?: boolean; expectedSubDir?: string | null }
      | undefined;
    if (!tested?.isValid) {
      const hint = tested?.expectedSubDir ? ` (ombi expected the base path ${tested.expectedSubDir})` : "";
      return {
        app: spec.app,
        result: "refused",
        problem:
          `ombi cannot reach ${spec.app} at ${want.ip}:${want.port} from its own container${hint}` +
          (fields.length > 0 ? `; its settings were written (${fields.join(", ")})` : ""),
      };
    }
    return fields.length > 0 ? { app: spec.app, result: "written", fields } : { app: spec.app, result: "unchanged" };
  } catch (err) {
    return { app: spec.app, result: "refused", problem: message(err) };
  }
 }
 /** Wait for ombi to answer, because the step runs right after its container starts. */
 export async function ombiReady(http: Http, ombi: Ombi, waitMs: number, pauseMs = 2000): Promise<boolean> {
  const until = Date.now() + waitMs;
  for (;;) {
    try {
      const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1/Status`, { method: "GET" });
      if (res.status === 200) return true;
    } catch {
      // not listening yet
    }
    if (Date.now() >= until) return false;
    await new Promise((r) => setTimeout(r, pauseMs));
  }
 }
 /** A file the mesh wrote, or undefined when it is not there. */
 export async function readIfThere(path: string | undefined): Promise<string | undefined> {
  if (!path) return undefined;
  return readFile(path, "utf8").catch(() => undefined);
 }
 /** A binding file parsed, or undefined when absent or not JSON. */
 export async function readBinding(path: string | undefined): Promise<Binding | undefined> {
  const raw = await readIfThere(path);
  if (raw === undefined) return undefined;
  try {
    return JSON.parse(raw) as Binding;
  } catch {
    return undefined;
  }
 }
 function message(err: unknown): string {
  return err instanceof Error ? err.message : String(err);
 }
@@ -0,0 +1,147 @@
 // What holds ombi's Servarr step (servarr/settings.ts): the connection ombi keeps for each app is
 // made to say what the mesh bound — host, port, TLS, base path, key — and nothing else it keeps is
 // touched; nothing is written when nothing differs; Radarr's 4K instance is left alone; and a key the
 // app refuses (the mesh's own minted value, before the operator accepts the app's key) is never
 // written, with the `secret accept` that fixes it named.
 //
 // ombi and the apps are fakes: the routes the step touches, answering as the real ones do (checked
 // against lscr.io/linuxserver/ombi 4.53.10 and the catalogue's pinned sonarr/radarr/lidarr).
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { APPS, differing, reconcileApp, subDirOf, wanted, type Binding, type Http, type ServarrApp } from "../servarr/settings.ts";
 const SONARR = APPS.find((a) => a.app === "sonarr") as ServarrApp;
 const RADARR = APPS.find((a) => a.app === "radarr") as ServarrApp;
 const LIDARR = APPS.find((a) => a.app === "lidarr") as ServarrApp;
 const THE_KEY = "the-apps-own-key";
 function binding(provision: string, port: number, at = "ace.internal"): Binding {
  return { binding: 1, provision, from: "ace", at, as: "mesh_ace_ombi", serves: { scheme: "http", port, "url-base": "" } } as Binding;
 }
 interface Call {
  method: string;
  url: string;
  body?: unknown;
 }
 /** ombi's settings store and the apps' key check, behind one fetch. */
 function fakes(settings: Record<string, unknown>, opts: { appKey?: string; reachable?: boolean } = {}) {
  const calls: Call[] = [];
  const appKey = opts.appKey ?? THE_KEY;
  const http: Http = {
    async fetch(url, init) {
      const method = init?.method ?? "GET";
      const body = init?.body ? (JSON.parse(init.body) as unknown) : undefined;
      calls.push({ method, url, body });
      const reply = (status: number, value?: unknown) => ({
        status,
        text: async () => (value === undefined ? "" : JSON.stringify(value)),
      });
      const u = new URL(url);
      if (u.pathname.endsWith("/system/status")) {
        if (opts.reachable === false) throw new Error("connect ECONNREFUSED");
        return init?.headers?.["X-Api-Key"] === appKey ? reply(200, { version: "4" }) : reply(401);
      }
      if (init?.headers?.ApiKey !== "ombi-key") return reply(401);
      const m = u.pathname.match(/^\/api\/v1\/(Settings|Tester)\/(\w+)$/);
      if (!m) return reply(404);
      const [, kind, app] = m;
      if (kind === "Settings" && method === "GET") return reply(200, settings[app]);
      if (kind === "Settings" && method === "POST") {
        settings[app] = body;
        return reply(200, true);
      }
      const tried = body as { apiKey?: string };
      return reply(200, { isValid: tried.apiKey === appKey, expectedSubDir: null });
    },
  };
  return { http, calls, settings };
 }
 const OMBI = { url: "http://127.0.0.1:3579", apiKey: "ombi-key" };
 const operatorSonarr = () => ({
  enabled: true, apiKey: "old-key", qualityProfile: "3", seasonFolders: true, rootPath: "10",
  qualityProfileAnime: "7", rootPathAnime: "9", languageProfile: 1, ssl: false, subDir: null,
  ip: "sonarr", port: 8989, id: 5,
 });
 test("it writes the connection the mesh bound, and keeps every other setting ombi had", async () => {
  const f = fakes({ sonarr: operatorSonarr() });
  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), `${THE_KEY}\n`);
  assert.deepEqual(out, { app: "sonarr", result: "written", fields: ["ip", "port", "apiKey"] });
  assert.deepEqual(f.settings.sonarr, {
    ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY, ssl: false, subDir: null,
  });
  // Checked against the app itself, at the bound address, before anything was written.
  assert.equal(f.calls[0].url, "http://ace.internal:20101/api/v3/system/status");
 });
 test("nothing is written when ombi already says what the mesh says", async () => {
  const f = fakes({ sonarr: { ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY } });
  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
  assert.deepEqual(out, { app: "sonarr", result: "unchanged" });
  assert.equal(f.calls.filter((c) => c.method === "POST" && c.url.includes("/Settings/")).length, 0);
 });
 test("a key the app refuses is never written, and the accept that fixes it is named", async () => {
  const f = fakes({ sonarr: operatorSonarr() });
  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), "a-value-the-mesh-minted");
  assert.equal(out.result, "refused");
  assert.match((out as { problem: string }).problem, /secret accept <this node> ombi sonarr-api --provider ace/);
  assert.doesNotMatch((out as { problem: string }).problem, /a-value-the-mesh-minted/);
  assert.deepEqual(f.settings.sonarr, operatorSonarr(), "ombi's working settings were left alone");
  assert.equal(f.calls.some((c) => c.url.includes("/api/v1/")), false, "ombi was not even asked");
 });
 test("an app it cannot reach is reported, and ombi is left alone", async () => {
  const f = fakes({ sonarr: operatorSonarr() }, { reachable: false });
  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
  assert.equal(out.result, "refused");
  assert.match((out as { problem: string }).problem, /could not be asked.*ECONNREFUSED/);
  assert.deepEqual(f.settings.sonarr, operatorSonarr());
 });
 test("radarr's connection is written inside its combined document, and the 4K instance is untouched", async () => {
  const fourK = { enabled: true, apiKey: "4k-key", ip: "radarr4k", port: 7879, defaultQualityProfile: "9", id: 7 };
  const f = fakes({ radarr: { radarr: { enabled: true, apiKey: "old", ip: "radarr", port: 7878, defaultRootPath: "/movies", id: 6 }, radarr4K: fourK } });
  const out = await reconcileApp(f.http, OMBI, RADARR, binding("radarr-api", 20102), THE_KEY);
  assert.equal(out.result, "written");
  const doc = f.settings.radarr as { radarr: Record<string, unknown>; radarr4K: unknown };
  assert.deepEqual(doc.radarr4K, fourK);
  assert.equal(doc.radarr.ip, "ace.internal");
  assert.equal(doc.radarr.port, 20102);
  assert.equal(doc.radarr.defaultRootPath, "/movies");
 });
 test("lidarr is checked on its own API version", async () => {
  const f = fakes({ lidarr: { enabled: true, apiKey: null, ip: null, port: 0, id: 0 } });
  const out = await reconcileApp(f.http, OMBI, LIDARR, binding("lidarr-api", 20103), THE_KEY);
  assert.equal(out.result, "written");
  assert.equal(f.calls[0].url, "http://ace.internal:20103/api/v1/system/status");
 });
 test("a loopback binding is refused: from ombi's container it is ombi itself", () => {
  const w = wanted(SONARR, binding("sonarr-api", 20101, "127.0.0.1"), THE_KEY);
  assert.equal(w.ok, false);
  assert.match((w as { problem: string }).problem, /private network/);
 });
 test("the base path is ombi's subDir, slashes trimmed; empty is none", () => {
  assert.equal(subDirOf(""), null);
  assert.equal(subDirOf("/sonarr/"), "sonarr");
  assert.deepEqual(
    differing({ ip: "h", port: 1, ssl: false, subDir: "", apiKey: "k" }, { ip: "h", port: 1, ssl: false, subDir: null, apiKey: "k" }),
    [],
  );
 });
 test("an https binding sets ombi's ssl flag", () => {
  const b = binding("sonarr-api", 443);
  (b.serves as Record<string, unknown>).scheme = "https";
  const w = wanted(SONARR, b, THE_KEY);
  assert.equal(w.ok && w.connection.ssl, true);
 });
@@ -8,5 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "index.ts", "tools/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts", "servarr/settings.ts", "servarr/index.ts"]
 }
@@ -82,7 +82,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_QBITTORRENT_URL": "http://127.0.0.1:8080",
+        "MESH_QBITTORRENT_URL": "http://127.0.0.1:${port:8080}",
        "MESH_QBITTORRENT_PASSWORD_FILE": "/run/secrets/password",
        "MESH_QBITTORRENT_CONFIG_FILE": "/run/config/config.json",
        "MESH_QBITTORRENT_CONFIG_DIR": "/var/lib/qbittorrent/config"
@@ -1,6 +1,19 @@
 {
  "module": "radarr",
  "version": "1",
  "provides": [
    {
      "name": "radarr-api",
      "scope": "mesh"
    }
  ],
  "serves": {
    "radarr-api": {
      "scheme": "http",
      "port": 7878,
      "url-base": ""
    }
  },
  "capabilities": [
    "container-runtime"
  ],
@@ -75,7 +88,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RADARR_URL": "http://127.0.0.1:7878",
+        "MESH_RADARR_URL": "http://127.0.0.1:${port:7878}",
        "MESH_RADARR_CONFIG_DIR": "/var/lib/radarr/config"
      },
      "artifact": "runtime"
@@ -100,7 +100,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SEARXNG_URL": "http://127.0.0.1:8080",
+        "MESH_SEARXNG_URL": "http://127.0.0.1:${port:8080}",
        "MESH_SEARXNG_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
@@ -1,6 +1,19 @@
 {
  "module": "sonarr",
  "version": "1",
  "provides": [
    {
      "name": "sonarr-api",
      "scope": "mesh"
    }
  ],
  "serves": {
    "sonarr-api": {
      "scheme": "http",
      "port": 8989,
      "url-base": ""
    }
  },
  "capabilities": [
    "container-runtime"
  ],
@@ -80,7 +93,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SONARR_URL": "http://127.0.0.1:8989",
+        "MESH_SONARR_URL": "http://127.0.0.1:${port:8989}",
        "MESH_SONARR_CONFIG_DIR": "/var/lib/sonarr/config"
      },
      "artifact": "runtime"
Author	SHA1	Message	Date
jschoubben	1e34ecc16b	home-assistant: a new MQTT entry says plain MQTT for its certificate choices Home Assistant's MQTT user flow shows no value for set_ca_cert and set_client_cert (a reconfigure pre-fills them from the entry), and refuses a submit without them — found against the pinned 2026.9.3 in a throwaway instance.	2026-09-30 13:11:40 +02:00
jschoubben	31af3f0ecc	home-assistant: its broker and its Sonarr, Radarr and Lidarr come from the mesh Home Assistant reached mosquitto and the three Servarr apps at 127.0.0.1 and a port typed into its own storage. It now requires mqtt-topic (asking for every topic: discovery and the devices' topics are its job), sonarr-api, radarr-api and lidarr-api, and a run-once `provisions` step — declared last, restarted when a binding or pair credential changes — makes Home Assistant's config entries say what the mesh bound, through Home Assistant's own config flows and never its .storage: - MQTT: the broker is asked first whether it takes the delivered login; then the integration's reconfigure flow sets broker, port, username and password, every other setting sent back as Home Assistant pre-filled it, and Home Assistant's own connection test must pass. A digest of what was written makes a rerun "already as the mesh says". Refused anywhere, nothing is written and Home Assistant keeps the login it has. - Sonarr/Radarr/Lidarr: the bound key is tried against the app (a minted key is never written; the failure names the `secret accept`); no entry is made through the user flow; a reauth Home Assistant started is finished with the bound key (and URL where the integration asks); an entry already at the bound URL, or at another URL reaching the same running app, is left as it is. These integrations have no reconfigure flow, so a working entry elsewhere is refused loudly — the step never removes an entry. The sidecar's URL now uses the port it was given.	2026-09-30 13:01:14 +02:00
jschoubben	958a6f4e3a	Merge origin/feat/servarr-api-provision (#156 ) into feat/home-assistant-for-ace home-assistant requires sonarr-api, radarr-api and lidarr-api, which #156 makes sonarr, radarr and lidarr provide; this branch needs those providers to resolve.	2026-09-30 12:49:55 +02:00
jschoubben	f14c763463	ombi: reach sonarr, radarr and lidarr through the mesh ombi keeps its Servarr connections in its own database, so the mesh has no file to write them into. A run-once step reads the three bindings and pair credentials and writes host, port, TLS, base path and key into ombi through ombi's own API - only when they differ, and nothing else ombi keeps. Until the operator accepts an app's key for this pair the mesh delivers a value it minted, which no Servarr app accepts. The step tries the key against the app first and, refused, writes nothing and fails naming the secret accept that fixes it, so the old working key in ombi is never replaced by a dead one. Declared last so its failing gates nothing else of ombi (ADR 0136), and restart-on its six inputs so it runs again when a provider moves (ADR 0099).	2026-09-30 00:39:19 +02:00
jschoubben	ab44ff02e1	sonarr, radarr, lidarr: provide their API to the mesh A consumer on another machine (ombi first; jackett, bazarr and home-assistant later) reached these by container name on HAL's shared network, which the mesh does not have. Each app now provides <app>-api at mesh scope and serves the software port, so the mesh tells a consumer where it is and redirects the port to where the machine published it. Named per app, not one servarr-api: a requirement is matched by name and answered by exactly one provider per node, so a consumer cannot require one name from three providers - and ombi's code is written against each app's own API version (ADR 0027). No grants and no provisioner: a Servarr instance has one API key, which the mesh cannot mint. The operator accepts it as the pair credential for each consumer (ADR 0092).	2026-09-30 00:39:19 +02:00
jschoubben	c4c44efb1b	Merge remote-tracking branch 'origin/fix/sidecars-dial-the-port-they-were-given' into feat/servarr-api-provision	2026-09-30 00:25:55 +02:00
jschoubben	5cc6258326	Sidecars dial the port they were given, not the software's A host-network sidecar reaches its service over the machine's loopback, and the mesh publishes that service on a machine port it assigns (ADR 0038) — so dialling the software's port reaches whatever else holds it. On ace, searxng's sidecar dialled 127.0.0.1:8080 and got unifi's inform port. The same shape in bazarr, bookshelf, lidarr, nzbget, qbittorrent, radarr and sonarr; each now asks with ${port:N} (hq 088). Found in review of ace's module preparation.	2026-09-29 23:50:19 +02:00
jschoubben	1df2a0b346	home-assistant: its directories are placed, and it runs the build in use The module stated /services/home-assistant/config and bound its route under /var/lib/mesh — novox's layout, a path no definition may carry (ADR 0112). The config dir and the module's state are now placed (${dir:config}, ${dir:state}); the route binds into ${dir:state}. The sidecar no longer mounts Home Assistant's config dir: nothing reads MESH_HOMEASSISTANT_CONFIG_DIR, and the mount handed it the auth store and secrets.yaml for nothing. The config dir loses owner 1000:1000 — the image runs as root, the uid was the predecessor's host-user convention. Two more listens that the software opens by default and LAN devices dial in on, which a converged filter would otherwise close: 1400 (Sonos event callback) and 18555 (bundled go2rtc WebRTC). Host network, so the machine port is the software's. Image pinned to the 2026.9.3 build ace's predecessor runs (2026-09-18); Home Assistant migrates its recorder schema, so older than running is unsafe. Verified: catalogue tests pass with MESH_CATALOGUE on this tree; the pinned image boots on a fresh root-owned 0700 config dir (manifest 200, API 401 without a token), and refuses X-Forwarded-For from an untrusted proxy (400).	2026-09-29 23:39:41 +02:00
jschoubben	21f5301268	ombi: its config is placed, its image is the one ace runs ombi's definition named /services/ombi/config (a HAL machine path) in three places and pinned an image older than the one ace runs. Ombi migrates its own SQLite schema, so a take onto the older pin (v4.53.10-ls267) would start it on a database the newer build (ls269) already touched. - config is a pathless placed directory, mounted as ${dir:config} - a state directory placed at the assignment root carries route.json - image pinned to the digest ace runs today (v4.53.10-ls269) - the sidecar reaches ombi on the machine port the mesh assigns (${port:3579}) rather than assuming 3579 is free - the sidecar no longer mounts ombi's data directory: MESH_OMBI_CONFIG_DIR is read by no code, and the mount exposed the databases for nothing Verified: catalogue tests (MESH_CATALOGUE set, 6 pass, none skipped); the pinned image starts as PUID 1000 in a 0700 dir and answers /api/v1/Status 200; data owned 1001:2000 (ace's media ids) under a 1000:1000 dir is re-owned by the image's init and serves 200; a minted ApiKey is refused (401) - the api-key secret must be accepted from ombi's own settings.	2026-09-29 23:38:56 +02:00