grafana: its InfluxDB data source comes from the influxdb-api provision

ace's grafana reads InfluxDB through a data source somebody typed into its database: a LAN address, a database InfluxDB 2 does not have, and a password for a v1 user of an earlier instance. Nothing in the mesh knew it existed, so migrating influxdb could only break it further. grafana now requires influxdb-api, contributes read access, and the mesh renders a provisioning file grafana reads at start: the address, port, org's default bucket (as the InfluxQL database) and its own login from the binding, the password by $__file from the pair credential the mesh delivers, 0400 for grafana's uid 472. It is a data source of its own name and uid, read-only in the UI and not the default, so the data source a person made is never overwritten; a changed binding or a rotated password restarts grafana, which re-reads the file. Includes #152 (merged into this branch): influxdb provides influxdb-api.
Merge feat/influxdb-for-ace (#152 ) into feat/oidc-client-provision
2026-09-30 13:02:11 +02:00 · 2026-09-30 12:55:43 +02:00 · 2026-09-30 12:55:38 +02:00 · 2026-09-30 00:49:08 +02:00 · 2026-09-30 00:39:16 +02:00 · 2026-09-30 00:39:16 +02:00
40 changed files with 1431 additions and 1306 deletions
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/bazarr
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc apikey.ts client.ts index.ts tools/index.ts servarr/settings.ts servarr/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}
@@ -22,6 +22,3 @@ COPY --from=build /app/modules/bazarr/dist /app/modules/bazarr/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/bazarr/dist/index.js,/app/modules/bazarr/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.
@@ -1,37 +0,0 @@
 // bazarr's own API key, found where bazarr keeps it. Shared by the client (tools, events) and the
 // Servarr step, and kept apart from client.ts so the step and its test load it without the client.
 import { readFileSync } from "node:fs";
 /**
 * bazarr's own API key, read from where bazarr keeps it: `auth.apikey` in `config/config.yaml` under
 * its config directory. bazarr makes this key itself on first start and nothing lets the mesh set it,
 * so a key the mesh minted could never work; reading bazarr's own file needs nothing accepted and
 * stays right if the operator regenerates the key in bazarr's settings screen. The file is read, never
 * written. Undefined when the file or the key is not there.
 */
 export function apiKeyFromConfigDir(configDir?: string): string | undefined {
  if (!configDir) return undefined;
  let text: string;
  try { text = readFileSync(`${configDir.replace(/\/$/, "")}/config/config.yaml`, "utf8"); }
  catch { return undefined; }
  return apiKeyFromConfigYaml(text);
 }
 /** `auth.apikey` from the text of bazarr's config.yaml — a top-level `auth:` mapping, one level deep. */
 export function apiKeyFromConfigYaml(text: string): string | undefined {
  let inAuth = false;
  for (const line of text.split(/\r?\n/)) {
    if (/^\S/.test(line)) {
      inAuth = /^auth:\s*$/.test(line);
      continue;
    }
    if (!inAuth) continue;
    const m = line.match(/^\s+apikey:\s*(.*?)\s*$/);
    if (m) {
      const v = m[1].replace(/^(['"])(.*)\1$/, "$2").trim();
      return v || undefined;
    }
  }
  return undefined;
 }
@@ -5,8 +5,6 @@
 import { readFileSync } from "node:fs";
 import { apiKeyFromConfigDir } from "./apikey.js";
 export interface WantedSubtitle {
  kind: "episode" | "movie";
  title: string; // series + episode, or movie title
@@ -49,7 +47,7 @@ function meshConfig(file?: string): Record<string, string> {
 *  absent or unreadable yields undefined so callers fall back rather than crash. */
 function readSecret(file?: string): string | undefined {
  if (!file) return undefined;
-  try { return readFileSync(file, "utf8").trim() || undefined; }
+  try { return readFileSync(file, "utf8").trim(); }
  catch { return undefined; }
 }
@@ -68,13 +66,9 @@ export class BazarrClient {
  static fromEnv(env: NodeJS.ProcessEnv = process.env): BazarrClient {
    const cfg = meshConfig(env.MESH_BAZARR_CONFIG_FILE);
    const url = cfg.url ?? env.MESH_BAZARR_URL;
-    const apiKey =
+    const apiKey = cfg.apiKey ?? readSecret(env.MESH_BAZARR_API_KEY_FILE) ?? env.MESH_BAZARR_API_KEY;
      cfg.apiKey ??
      apiKeyFromConfigDir(env.MESH_BAZARR_CONFIG_DIR) ??
      readSecret(env.MESH_BAZARR_API_KEY_FILE) ??
      env.MESH_BAZARR_API_KEY;
    if (!url) throw new Error("no Bazarr URL — set MESH_BAZARR_URL");
-    if (!apiKey) throw new Error("no Bazarr API key — bazarr's config/config.yaml under MESH_BAZARR_CONFIG_DIR has none");
+    if (!apiKey) throw new Error("no Bazarr API key — set MESH_BAZARR_API_KEY");
    return new BazarrClient(url, apiKey);
  }
@@ -8,7 +8,8 @@
    "subtitle.downloaded"
  ],
  "own-secrets": {
-    "broker": "/var/lib/mesh/bazarr/broker"
+    "broker": "/var/lib/mesh/bazarr/broker",
    "api-key": "/var/lib/mesh/bazarr/api-key"
  },
  "listens": [
    {
@@ -44,15 +45,10 @@
      "path": "/var/lib/mesh/bazarr",
      "mode": "0700"
    },
    {
      "id": "state",
      "type": "directory",
      "mode": "0700",
      "place": "."
    },
    {
      "id": "config",
      "type": "directory",
      "path": "/services/bazarr/config",
      "mode": "0700",
      "owner": "1000:1000"
    },
@@ -60,7 +56,7 @@
      "id": "server",
      "type": "container",
      "name": "bazarr",
-      "image": "lscr.io/linuxserver/bazarr@sha256:d24bd0048c759a468970989e9df11a6b96a7628d556d00f923e60a35ba59237b",
+      "image": "lscr.io/linuxserver/bazarr@sha256:3a820372f19fcb2981ea19fe4b5382934d67414afaba974bce831ddda0a64a02",
      "env": {
        "PUID": "1000",
        "PGID": "1000",
@@ -70,7 +66,7 @@
        "6767"
      ],
      "volumes": [
-        "${dir:config}:/config",
+        "/services/bazarr/config:/config",
        "/services/media/movies:/movies",
        "/services/media/series:/series",
        "/services/media/anime:/anime",
@@ -80,7 +76,7 @@
    {
      "id": "runtime-config",
      "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/mesh/bazarr/config.json",
      "mode": "0600",
      "content": "{}\n",
      "merge": "json"
@@ -92,12 +88,14 @@
      "network": "host",
      "volumes": [
        "/var/lib/mesh/bazarr/broker:/run/secrets/broker:ro",
-        "${dir:state}/config.json:/run/config/config.json:ro",
+        "/var/lib/mesh/bazarr/api-key:/run/secrets/api-key:ro",
-        "${dir:config}:/var/lib/bazarr/config:ro"
+        "/var/lib/mesh/bazarr/config.json:/run/config/config.json:ro",
        "/services/bazarr/config:/var/lib/bazarr/config:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BAZARR_URL": "http://127.0.0.1:${port:6767}",
+        "MESH_BAZARR_URL": "http://127.0.0.1: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"
      },
@@ -105,42 +103,10 @@
        "runtime-config"
      ],
      "artifact": "runtime"
    },
    {
      "id": "servarr",
      "type": "container",
      "name": "mesh-bazarr-servarr",
      "network": "host",
      "run-once": true,
      "volumes": [
        "${dir:config}:/var/lib/bazarr/config: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"
      ],
      "env": {
        "MESH_BAZARR_URL": "http://127.0.0.1:${port:6767}",
        "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config",
        "MESH_SERVARR_DIR": "/run/servarr"
      },
      "args": [
        "run",
        "/app/modules/bazarr/dist/servarr/index.js"
      ],
      "restart-on": [
        "bound-sonarr-api",
        "secret-sonarr-api",
        "bound-radarr-api",
        "secret-radarr-api"
      ],
      "artifact": "runtime"
    }
  ],
  "requires": [
-    "radarr-api",
+    "route"
    "route",
    "sonarr-api"
  ],
  "contributes": {
    "route": {
@@ -149,13 +115,7 @@
    }
  },
  "binds": {
-    "route": "${dir:state}/route.json",
+    "route": "/var/lib/mesh/bazarr/route.json"
    "sonarr-api": "${dir:state}/sonarr-api.json",
    "radarr-api": "${dir:state}/radarr-api.json"
  },
  "secrets": {
    "sonarr-api": "${dir:state}/sonarr-api.secret",
    "radarr-api": "${dir:state}/radarr-api.secret"
  },
  "build": {
    "on": [
@@ -4,11 +4,6 @@
  "description": "bazarr — subtitle management. Its API client, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc apikey.ts 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"
  },
@@ -1,63 +0,0 @@
 // bazarr's Servarr step — run once by the host after bazarr'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**: 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, a
 // bazarr that would not keep the settings — 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
 // bazarr'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; and bazarr's own key from bazarr's own config.yaml
 // under MESH_BAZARR_CONFIG_DIR. Never prints a key.
 import { join } from "node:path";
 import { apiKeyFromConfigDir } from "../apikey.js";
 import { APPS, bazarrReady, readBinding, readIfThere, reconcileApp, type Http } from "./settings.js";
 const dir = process.env.MESH_SERVARR_DIR ?? "/run/servarr";
 const url = process.env.MESH_BAZARR_URL ?? "http://127.0.0.1:6767";
 const waitSeconds = Number(process.env.MESH_BAZARR_WAIT_SECONDS ?? "180");
 const http: Http = { fetch: (u, init) => fetch(u, init) };
 const bazarrUp = await bazarrReady(http, { url, apiKey: "" }, waitSeconds * 1000);
 if (!bazarrUp) {
  console.error(`[bazarr-servarr] bazarr did not answer at ${url} within ${waitSeconds}s`);
  process.exit(1);
 }
 // Read after bazarr answers: on a first start bazarr writes its config.yaml, key included, as it boots.
 const apiKey = apiKeyFromConfigDir(process.env.MESH_BAZARR_CONFIG_DIR);
 if (!apiKey) {
  console.error("[bazarr-servarr] no bazarr API key in bazarr's config/config.yaml under MESH_BAZARR_CONFIG_DIR");
  process.exit(1);
 }
 const bazarr = { url, apiKey };
 let failed = 0;
 for (const spec of APPS) {
  const outcome = await reconcileApp(
    http,
    bazarr,
    spec,
    await readBinding(join(dir, `${spec.provision}.json`)),
    await readIfThere(join(dir, `${spec.provision}.secret`)),
  );
  switch (outcome.result) {
    case "unchanged":
      console.log(`[bazarr-servarr] ${outcome.app}: already as the mesh says; key taken by ${outcome.app}`);
      break;
    case "written":
      console.log(`[bazarr-servarr] ${outcome.app}: wrote ${outcome.fields.join(", ")}; key taken by ${outcome.app}`);
      break;
    case "refused":
      failed++;
      console.error(`[bazarr-servarr] ${outcome.app}: ${outcome.problem}`);
      break;
  }
 }
 process.exitCode = failed > 0 ? 1 : 0;
@@ -1,290 +0,0 @@
 // Where bazarr reaches Sonarr and Radarr — decided by the mesh, written into bazarr by bazarr's own
 // API.
 //
 // **Why this exists.** bazarr keeps its connection to each app in its own `config/config.yaml`, which
 // it holds in memory and writes back whenever its settings change — so the mesh cannot own that file
 // without the two overwriting each other. bazarr requires `sonarr-api` and `radarr-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, novox/hq ADR 0092). This step reads those files and
 // makes bazarr's settings say the same thing, through `POST /api/system/settings` — the call bazarr's
 // own settings screen makes, which also restarts bazarr's SignalR feed from the app.
 //
 // **Only the connection, and only when it differs.** Host, port, TLS, base path and API key. Whether
 // bazarr uses the app at all (`general.use_sonarr`), sync intervals, excluded tags, path mappings and
 // every other choice the operator made are left exactly as they are: the mesh knows where the app is,
 // not what bazarr should do with it.
 //
 // **A credential the app refuses is never written.** Until the operator accepts the app's key for this
 // pair the mesh delivers a value it minted, which no Servarr app accepts. Writing it would replace a
 // working key in bazarr 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.
 //
 // The same shape as ombi's step (modules/ombi/servarr), repeated rather than shared because a module
 // is built from its own directory and nothing else (novox/hq ADR 0069). Pure logic and a small HTTP
 // seam, tested against fakes (test/servarr.test.ts).
 import { readFile } from "node:fs/promises";
 /** One Servarr app bazarr connects to. */
 export interface ServarrApp {
  /** The section of bazarr's settings that holds the connection: settings.<app>.* */
  app: "sonarr" | "radarr";
  /** 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;
 }
 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" },
 ];
 /** The connection fields bazarr keeps for an app — the only ones this step ever writes. */
 export interface Connection {
  ip: string;
  port: number;
  ssl: boolean;
  /** bazarr's base_url: "" at the root, otherwise "/base". */
  base_url: string;
  apikey: string;
 }
 /** What the mesh wrote at `binds.<provision>`: the binding document. */
 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 bazarr should use. Refused rather than guessed when the binding cannot
 * be dialled from bazarr's own container: a loopback `at` is bazarr's container itself.
 */
 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 bazarr's own container is ` +
        `bazarr 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 bazarr 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 bazarr 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", base_url: baseUrlOf(serves["url-base"]), apikey: key },
  };
 }
 /** A URL base as bazarr stores it: "" for none, else one leading slash and no trailing one. */
 export function baseUrlOf(urlBase: unknown): string {
  const trimmed = typeof urlBase === "string" ? urlBase.trim().replace(/^\/+|\/+$/g, "") : "";
  return trimmed === "" ? "" : `/${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 bazarr 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 (baseUrlOf(now.base_url) !== want.base_url) out.push("base_url");
  if (String(now.apikey ?? "") !== want.apikey) out.push("apikey");
  return out;
 }
 /**
 * The form bazarr's settings endpoint takes for the differing fields: `settings-<app>-<field>`.
 * bazarr casts "true"/"false" to booleans and digit strings to integers itself.
 */
 export function settingsForm(spec: ServarrApp, want: Connection, fields: readonly (keyof Connection)[]): URLSearchParams {
  const form = new URLSearchParams();
  for (const f of fields) {
    const v = want[f];
    form.append(`settings-${spec.app}-${f}`, typeof v === "boolean" ? (v ? "true" : "false") : String(v));
  }
  return form;
 }
 /** The app's base URL as the step dials it — the same host and port bazarr 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.base_url}`;
 }
 /** 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 bazarr 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 Bazarr {
  url: string;
  apiKey: string;
 }
 async function bazarrCall(http: Http, bazarr: Bazarr, method: string, path: string, form?: URLSearchParams): Promise<unknown> {
  const res = await http.fetch(`${bazarr.url.replace(/\/$/, "")}/api${path}`, {
    method,
    headers: {
      "X-API-KEY": bazarr.apiKey,
      Accept: "application/json",
      ...(form ? { "Content-Type": "application/x-www-form-urlencoded" } : {}),
    },
    body: form ? form.toString() : undefined,
  });
  const text = await res.text();
  if (res.status < 200 || res.status >= 300) {
    // bazarr's error body is a message, never a request echo, so it carries no key.
    throw new Error(`bazarr ${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.
 */
 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 bazarr. 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> bazarr ${spec.provision} --provider ${from || "<its node>"} ` +
    `--from <file holding ${spec.app}'s ApiKey>\``
  );
 }
 /**
 * Bring bazarr's connection to one app in line with the mesh: check the key against the app, compare,
 * write only the differing connection fields, then read bazarr's settings back to confirm they took.
 * Never throws: every failure is an outcome with a reason.
 */
 export async function reconcileApp(
  http: Http,
  bazarr: Bazarr,
  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 before = await sectionOf(http, bazarr, spec);
    const fields = differing(before, want);
    if (fields.length === 0) return { app: spec.app, result: "unchanged" };
    await bazarrCall(http, bazarr, "POST", "/system/settings", settingsForm(spec, want, fields));
    const still = differing(await sectionOf(http, bazarr, spec), want);
    if (still.length > 0) {
      return { app: spec.app, result: "refused", problem: `bazarr did not keep its ${spec.app} settings (${still.join(", ")})` };
    }
    return { app: spec.app, result: "written", fields };
  } catch (err) {
    return { app: spec.app, result: "refused", problem: message(err) };
  }
 }
 async function sectionOf(http: Http, bazarr: Bazarr, spec: ServarrApp): Promise<Record<string, unknown> | undefined> {
  const doc = (await bazarrCall(http, bazarr, "GET", "/system/settings")) as Record<string, unknown> | undefined;
  return doc?.[spec.app] as Record<string, unknown> | undefined;
 }
 /** Wait for bazarr to answer, because the step runs right after its container starts. */
 export async function bazarrReady(http: Http, bazarr: Bazarr, waitMs: number, pauseMs = 2000): Promise<boolean> {
  const until = Date.now() + waitMs;
  for (;;) {
    try {
      const res = await http.fetch(`${bazarr.url.replace(/\/$/, "")}/api/system/ping`, { 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);
 }
@@ -1,156 +0,0 @@
 // What holds bazarr's Servarr step (servarr/settings.ts): the connection bazarr keeps for Sonarr and
 // Radarr is made to say what the mesh bound — host, port, TLS, base path, key — and nothing else
 // bazarr keeps is sent; nothing is written when nothing differs; 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. Also: bazarr's own key is found in its config.yaml's `auth`
 // section and not in the `sonarr`/`radarr` sections that also carry an `apikey`.
 //
 // bazarr and the apps are fakes answering as the real ones do (checked against
 // lscr.io/linuxserver/bazarr v1.6.1-ls364: GET/POST /api/system/settings with X-API-KEY, the form
 // keys `settings-<section>-<field>`, 204 on save).
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { apiKeyFromConfigYaml } from "../apikey.ts";
 import { APPS, baseUrlOf, differing, reconcileApp, 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 THE_KEY = "the-apps-own-key";
 const BAZARR = { url: "http://127.0.0.1:6767", apiKey: "bazarr-key" };
 function binding(provision: string, port: number, at = "ace.internal"): Binding {
  return { binding: 1, provision, from: "ace", at, as: "mesh_ace_bazarr", serves: { scheme: "http", port, "url-base": "" } } as Binding;
 }
 interface Call {
  method: string;
  url: string;
  body?: string;
 }
 /** bazarr's settings (one document, sections per app) and the apps' key check, behind one fetch. */
 function fakes(settings: Record<string, 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";
      calls.push({ method, url, body: init?.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?.["X-API-KEY"] !== BAZARR.apiKey) return reply(401);
      if (u.pathname !== "/api/system/settings") return reply(404);
      if (method === "GET") return reply(200, settings);
      // bazarr's save_settings: split the key, cast as bazarr casts, store.
      for (const [k, raw] of new URLSearchParams(init?.body ?? "")) {
        const [, section, field] = k.split("-");
        let v: unknown = raw;
        if (raw === "true") v = true;
        else if (raw === "false") v = false;
        else if (/^\d+$/.test(raw)) v = Number(raw);
        settings[section] = { ...(settings[section] ?? {}), [field]: v };
      }
      return reply(204);
    },
  };
  return { http, calls, settings };
 }
 /** ace's bazarr today: the apps by container name on HAL's shared network. */
 function aceToday(): Record<string, Record<string, unknown>> {
  return {
    general: { use_sonarr: true, use_radarr: true, port: 6767 },
    sonarr: { ip: "sonarr", port: 8989, ssl: false, base_url: "", apikey: THE_KEY, series_sync: 15, excluded_series_types: ["anime"] },
    radarr: { ip: "radarr", port: 7878, ssl: false, base_url: "", apikey: THE_KEY, movies_sync: 15 },
  };
 }
 test("moving an app writes only host and port, and leaves every other setting alone", async () => {
  const f = fakes(aceToday());
  const out = await reconcileApp(f.http, BAZARR, SONARR, binding("sonarr-api", 20010), THE_KEY);
  assert.deepEqual(out, { app: "sonarr", result: "written", fields: ["ip", "port"] });
  const post = f.calls.find((c) => c.method === "POST");
  assert.ok(post);
  assert.deepEqual([...new URLSearchParams(post.body ?? "").keys()].sort(), ["settings-sonarr-ip", "settings-sonarr-port"]);
  assert.equal(f.settings.sonarr.ip, "ace.internal");
  assert.equal(f.settings.sonarr.port, 20010);
  assert.deepEqual(f.settings.sonarr.excluded_series_types, ["anime"]);
  assert.equal(f.settings.radarr.ip, "radarr", "radarr is its own app and was not touched");
 });
 test("nothing is written when bazarr already says what the mesh says", async () => {
  const s = aceToday();
  s.radarr = { ...s.radarr, ip: "ace.internal", port: 20011 };
  const f = fakes(s);
  const out = await reconcileApp(f.http, BAZARR, RADARR, binding("radarr-api", 20011), THE_KEY);
  assert.deepEqual(out, { app: "radarr", result: "unchanged" });
  assert.equal(f.calls.filter((c) => c.method === "POST").length, 0);
 });
 test("a key the app refuses is never written, and the remedy is named", async () => {
  const f = fakes(aceToday());
  const out = await reconcileApp(f.http, BAZARR, SONARR, binding("sonarr-api", 20010), "a-value-the-mesh-minted");
  assert.equal(out.result, "refused");
  assert.match((out as { problem: string }).problem, /secret accept <this node> bazarr sonarr-api --provider ace/);
  assert.equal(f.calls.filter((c) => c.method === "POST").length, 0);
  assert.equal(f.settings.sonarr.apikey, THE_KEY, "the working key stays");
  assert.equal(f.settings.sonarr.ip, "sonarr", "nothing moved either");
 });
 test("an unreachable app writes nothing", async () => {
  const f = fakes(aceToday(), { reachable: false });
  const out = await reconcileApp(f.http, BAZARR, SONARR, binding("sonarr-api", 20010), THE_KEY);
  assert.equal(out.result, "refused");
  assert.equal(f.calls.filter((c) => c.method === "POST").length, 0);
 });
 test("a loopback binding is refused: from bazarr's container that is bazarr", () => {
  const w = wanted(SONARR, binding("sonarr-api", 8989, "127.0.0.1"), THE_KEY);
  assert.equal(w.ok, false);
 });
 test("a new key is written when the operator accepted a different one", async () => {
  const s = aceToday();
  s.sonarr = { ...s.sonarr, ip: "ace.internal", port: 20010, apikey: "an-old-key" };
  const f = fakes(s);
  const out = await reconcileApp(f.http, BAZARR, SONARR, binding("sonarr-api", 20010), THE_KEY);
  assert.deepEqual(out, { app: "sonarr", result: "written", fields: ["apikey"] });
  assert.equal(f.settings.sonarr.apikey, THE_KEY);
 });
 test("base paths compare as bazarr stores them", () => {
  assert.equal(baseUrlOf(""), "");
  assert.equal(baseUrlOf("/"), "");
  assert.equal(baseUrlOf("sonarr/"), "/sonarr");
  const want = { ip: "a", port: 1, ssl: false, base_url: "", apikey: "k" };
  assert.deepEqual(differing({ ip: "a", port: 1, ssl: false, base_url: "/", apikey: "k" }, want), []);
 });
 test("bazarr's own key is auth.apikey, not an app's", () => {
  const yaml = [
    "analytics:",
    "  enabled: false",
    "auth:",
    "  apikey: 0123456789abcdef0123456789abcdef",
    "  password: ''",
    "  type: form",
    "general:",
    "  port: 6767",
    "sonarr:",
    "  apikey: not-this-one",
    "",
  ].join("\n");
  assert.equal(apiKeyFromConfigYaml(yaml), "0123456789abcdef0123456789abcdef");
  assert.equal(apiKeyFromConfigYaml("sonarr:\n  apikey: x\n"), undefined);
  assert.equal(apiKeyFromConfigYaml("auth:\n  apikey: ''\n"), undefined);
  assert.equal(apiKeyFromConfigYaml("auth:\r\n  apikey: 'abc'\r\n"), "abc");
 });
@@ -8,5 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["apikey.ts", "client.ts", "index.ts", "tools/index.ts", "servarr/settings.ts", "servarr/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts"]
 }
@@ -76,7 +76,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BOOKSHELF_URL": "http://127.0.0.1:${port:8787}",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
        "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
      },
      "artifact": "runtime"
@@ -5,7 +5,7 @@
    "alert.firing"
  ],
  "own-secrets": {
-    "admin": "/var/lib/grafana-module/admin.secret",
+    "admin": "/var/lib/mesh/grafana/admin",
    "broker": "/var/lib/mesh/grafana/broker"
  },
  "capabilities": [
@@ -30,45 +30,87 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/grafana-module",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
      "id": "data",
      "type": "directory",
      "path": "/services/grafana/data",
      "mode": "0700",
      "owner": "472:472"
    },
    {
-      "id": "server-env",
+      "id": "admin-secret",
      "type": "file",
-      "path": "/var/lib/grafana-module/server.env",
+      "path": "${dir:state}/admin.secret",
-      "mode": "0600",
+      "mode": "0400",
-      "content": "GF_SECURITY_ADMIN_PASSWORD=${secret:admin}\n"
+      "owner": "472:472",
      "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:f772d434e8fab0049deb2b1b30abd43342bcfca1537614aa8d36080232cf4283",
+      "image": "grafana/grafana@sha256:ac461fb352abc50da10a51c7d02462e9c05488f11f53f14b3ad79a8145f638a0",
      "ports": [
        "3000"
      ],
      "volumes": [
-        "/services/grafana/data:/var/lib/grafana"
+        "${dir: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": [
-        "/var/lib/grafana-module/server.env"
+        "${dir:state}/oidc.env"
      ],
-      "secrets-in-environment": "grafana honours GF_SECURITY_ADMIN_PASSWORD__FILE; convertible, awaiting a bed that exercises the admin password (assigned-grafana serves tools only)"
+      "restart-on": [
        "oidc-env",
        "oidc-secret",
        "influxdb-datasource",
        "influxdb-secret"
      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
      "path": "/var/lib/mesh/grafana/config.json",
      "mode": "0600",
-      "content": "{}\n",
+      "content": "{\n  \"user\": \"admin\",\n  \"password\": \"${secret:admin}\"\n}\n",
      "merge": "json"
    },
    {
@@ -82,7 +124,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_GRAFANA_URL": "http://127.0.0.1:3000",
+        "MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
        "MESH_GRAFANA_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
@@ -92,16 +134,32 @@
    }
  ],
  "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": "/var/lib/mesh/grafana/route.json"
+    "route": "${dir:state}/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/influxdb
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts grants.ts provisioner/index.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
+ENV MESH_TOOL_MODULES=/app/modules/influxdb/dist/tools/index.js,/app/modules/influxdb/dist/provisioner/index.js
@@ -17,6 +17,25 @@ 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 {};
@@ -24,13 +43,20 @@ 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,
-    private readonly org: string,
+    readonly org: string,
  ) {
    this.baseUrl = url.replace(/\/$/, "");
  }
@@ -43,8 +69,10 @@ 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"}`;
-    const token = cfg.token ?? env.MESH_INFLUXDB_TOKEN;
+    // The token reaches the process as a file (novox/hq ADR 0086); the environment variable stays
-    if (!token) throw new Error("no InfluxDB token — set MESH_INFLUXDB_TOKEN");
+    // only for a workstation running the tools by hand.
    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);
  }
@@ -61,6 +89,93 @@ 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;
@@ -0,0 +1,186 @@
 // 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,6 +1,12 @@
 {
  "module": "influxdb",
  "version": "1",
  "provides": [
    {
      "name": "influxdb-api",
      "scope": "mesh"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
@@ -13,9 +19,23 @@
      "port": 8086,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "queries and writes, over http"
+      "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"
    }
  ],
  "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",
@@ -26,46 +46,50 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/influxdb-module",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
      "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": [
-        "/var/lib/influxdb-module/server.env"
+        "${dir:state}/server.env"
      ],
      "ports": [
        "8086"
      ],
      "volumes": [
-        "/services/influxdb/data:/var/lib/influxdb2",
+        "${dir:data}:/var/lib/influxdb2",
-        "/services/influxdb/config:/etc/influxdb2"
+        "${dir:config}:/etc/influxdb2",
-      ],
+        "${dir:state}/admin.secret:/run/secrets/admin:ro",
-      "secrets-in-environment": "the image honours DOCKER_INFLUXDB_INIT_PASSWORD_FILE and _ADMIN_TOKEN_FILE; convertible, awaiting a bed that proves it"
+        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro"
      ]
    },
    {
      "id": "runtime-config",
@@ -83,13 +107,15 @@
      "volumes": [
        "/var/lib/mesh/influxdb/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/influxdb/config.json:/run/config/config.json:ro",
-        "/services/influxdb/config:/var/lib/influxdb/config:ro"
+        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro",
        "${dir:grants}:${dir:grants}:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_INFLUXDB_URL": "http://127.0.0.1:8086",
+        "MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
        "MESH_INFLUXDB_CONFIG_FILE": "/run/config/config.json",
-        "MESH_INFLUXDB_CONFIG_DIR": "/var/lib/influxdb/config"
+        "MESH_INFLUXDB_TOKEN_FILE": "/run/secrets/admin-token",
        "MESH_RECEIVES": "${dir:grants}/mesh.json"
      },
      "restart-on": [
        "runtime-config"
@@ -97,6 +123,22 @@
      "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": [
      {
@@ -117,14 +159,5 @@
        "from": "Dockerfile"
      }
    ]
  },
  "requires": [
    "secret"
  ],
  "secrets": {
    "secret": {
      "admin": "/var/lib/influxdb-module/admin.secret",
      "admin-token": "/var/lib/influxdb-module/admin-token.secret"
    }
  }
 }
@@ -1,9 +1,14 @@
 {
  "name": "@novox/module-influxdb",
  "version": "0.1.0",
-  "description": "influxdb — time-series database. Its API client and tools live here (novox/hq ADR 0039).",
+  "description": "influxdb — time-series database; provides the mesh influxdb-api interface. Its API client, provisioner 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"
  },
@@ -0,0 +1,54 @@
 // 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);
    },
  });
 }
@@ -0,0 +1,246 @@
 // 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,5 +8,10 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "tools/index.ts"]
+  "include": [
    "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 index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts oidc.ts index.ts provisioner/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
+ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js,/app/modules/keycloak/dist/provisioner/index.js
@@ -12,6 +12,45 @@ 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;
@@ -40,8 +79,13 @@ 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";
-    const adminPass = cfg.password ?? env.MESH_KEYCLOAK_PASSWORD ?? env.KEYCLOAK_ADMIN_PASSWORD;
+    // The admin password reaches the runtime as a file (novox/hq ADR 0086): the module's own `admin`
-    if (!adminPass) throw new Error("no Keycloak admin password — set MESH_KEYCLOAK_PASSWORD");
+    // secret, mounted read-only. The environment forms stay for a co-located server that has them.
    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);
  }
@@ -159,6 +203,50 @@ 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,6 +1,12 @@
 {
  "module": "keycloak",
  "version": "1",
  "provides": [
    {
      "name": "oidc-client",
      "scope": "mesh"
    }
  ],
  "requires": [
    "postgres-database",
    "route"
@@ -41,6 +47,19 @@
      "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"
@@ -58,6 +77,12 @@
      "path": "/var/lib/keycloak",
      "mode": "0700"
    },
    {
      "id": "grants",
      "type": "directory",
      "path": "/var/lib/keycloak/grants",
      "mode": "0700"
    },
    {
      "id": "admin-env",
      "type": "file",
@@ -77,6 +102,13 @@
      "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",
@@ -90,17 +122,20 @@
        "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",
@@ -117,12 +152,16 @@
      "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"
@@ -0,0 +1,185 @@
 // 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,11 +1,15 @@
 {
  "name": "@novox/module-keycloak",
  "version": "0.1.0",
-  "description": "keycloak — identity and access. Its admin API client, tools and events live here (novox/hq ADR 0039).",
+  "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).",
  "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.0"
+    "@novox/mesh-sdk": "^0.1.1"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
@@ -0,0 +1,73 @@
 // 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);
  },
 });
@@ -0,0 +1,239 @@
 // 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", "index.ts", "tools/index.ts"]
+  "include": ["client.ts", "oidc.ts", "index.ts", "provisioner/index.ts", "tools/index.ts"]
 }
@@ -1,19 +1,6 @@
 {
  "module": "lidarr",
  "version": "1",
  "provides": [
    {
      "name": "lidarr-api",
      "scope": "mesh"
    }
  ],
  "serves": {
    "lidarr-api": {
      "scheme": "http",
      "port": 8686,
      "url-base": ""
    }
  },
  "capabilities": [
    "container-runtime"
  ],
@@ -88,7 +75,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_LIDARR_URL": "http://127.0.0.1:${port:8686}",
+        "MESH_LIDARR_URL": "http://127.0.0.1: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:${port:6789}",
+        "MESH_NZBGET_URL": "http://127.0.0.1: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 servarr/settings.ts servarr/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}
@@ -22,6 +22,3 @@ 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,15 +28,10 @@
      "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"
    },
@@ -44,7 +39,7 @@
      "id": "server",
      "type": "container",
      "name": "ombi",
-      "image": "lscr.io/linuxserver/ombi@sha256:22d6ebadbaaa728571353e74dc2173719e0fb02d4eaec551a7e9d2ee99ef68ac",
+      "image": "lscr.io/linuxserver/ombi@sha256:a6f76ac521ba01eee2e9f0c23a3fed22e56630d97a04d5eeaeaa36c1e681640d",
      "env": {
        "PUID": "1000",
        "PGID": "1000",
@@ -54,7 +49,7 @@
        "3579"
      ],
      "volumes": [
-        "${dir:config}:/config"
+        "/services/ombi/config:/config"
      ]
    },
    {
@@ -73,59 +68,24 @@
      "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:${port:3579}",
+        "MESH_OMBI_URL": "http://127.0.0.1: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": [
-    "lidarr-api",
+    "route"
    "radarr-api",
    "route",
    "sonarr-api"
  ],
  "contributes": {
    "route": {
@@ -134,15 +94,7 @@
    }
  },
  "binds": {
-    "route": "${dir:state}/route.json",
+    "route": "/var/lib/mesh/ombi/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,11 +4,6 @@
  "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"
  },
@@ -1,59 +0,0 @@
 // 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;
@@ -1,304 +0,0 @@
 // 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);
 }
@@ -1,147 +0,0 @@
 // 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", "servarr/settings.ts", "servarr/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts"]
 }
@@ -82,7 +82,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_QBITTORRENT_URL": "http://127.0.0.1:${port:8080}",
+        "MESH_QBITTORRENT_URL": "http://127.0.0.1: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,19 +1,6 @@
 {
  "module": "radarr",
  "version": "1",
  "provides": [
    {
      "name": "radarr-api",
      "scope": "mesh"
    }
  ],
  "serves": {
    "radarr-api": {
      "scheme": "http",
      "port": 7878,
      "url-base": ""
    }
  },
  "capabilities": [
    "container-runtime"
  ],
@@ -88,7 +75,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RADARR_URL": "http://127.0.0.1:${port:7878}",
+        "MESH_RADARR_URL": "http://127.0.0.1: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:${port:8080}",
+        "MESH_SEARXNG_URL": "http://127.0.0.1:8080",
        "MESH_SEARXNG_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
@@ -1,19 +1,6 @@
 {
  "module": "sonarr",
  "version": "1",
  "provides": [
    {
      "name": "sonarr-api",
      "scope": "mesh"
    }
  ],
  "serves": {
    "sonarr-api": {
      "scheme": "http",
      "port": 8989,
      "url-base": ""
    }
  },
  "capabilities": [
    "container-runtime"
  ],
@@ -93,7 +80,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SONARR_URL": "http://127.0.0.1:${port:8989}",
+        "MESH_SONARR_URL": "http://127.0.0.1:8989",
        "MESH_SONARR_CONFIG_DIR": "/var/lib/sonarr/config"
      },
      "artifact": "runtime"
Author	SHA1	Message	Date
jschoubben	d2f03736fa	grafana: its InfluxDB data source comes from the influxdb-api provision ace's grafana reads InfluxDB through a data source somebody typed into its database: a LAN address, a database InfluxDB 2 does not have, and a password for a v1 user of an earlier instance. Nothing in the mesh knew it existed, so migrating influxdb could only break it further. grafana now requires influxdb-api, contributes read access, and the mesh renders a provisioning file grafana reads at start: the address, port, org's default bucket (as the InfluxQL database) and its own login from the binding, the password by $__file from the pair credential the mesh delivers, 0400 for grafana's uid 472. It is a data source of its own name and uid, read-only in the UI and not the default, so the data source a person made is never overwritten; a changed binding or a rotated password restarts grafana, which re-reads the file. Includes #152 (merged into this branch): influxdb provides influxdb-api.	2026-09-30 13:02:11 +02:00
jschoubben	c5e273e232	Merge feat/influxdb-for-ace (#152 ) into feat/oidc-client-provision grafana's data source requires influxdb-api, which influxdb provides only on #152's branch; merged so this branch's catalogue has the provider of everything grafana requires. #152 should merge first.	2026-09-30 12:55:43 +02:00
jschoubben	323ef9ec7e	influxdb: provide influxdb-api, one mesh-made v1 credential per consumer grafana's data source and Node-RED's influxdb nodes reached ace's InfluxDB by a LAN IP or a public name nobody routes, with a credential somebody made by hand. Now a consumer requires influxdb-api and is told where it is, which org and default bucket it serves, and signs in with the password the mesh minted for the pair. The credential is a v1-compatibility authorization, made per grant by the new provisioner: InfluxDB 2.x generates API tokens itself and ignores one the caller sends, so a v2 token could only be accepted by hand per pair; a v1 authorization takes a caller-chosen password (8-72 characters, the mesh mints 40) and reads/writes every bucket as a database of its name over InfluxQL and line protocol. A consumer contributes `access` (read, write, read-write) and, for writing, the buckets; a missing bucket is made and never deleted. Only authorizations named mesh_* and marked [mesh] are ever changed or removed; anything else of that name is refused and left alone. The org and default bucket are served facts the assignment's settings set, reaching both the consumers and the provisioner's config.json.	2026-09-30 12:55:38 +02:00
jschoubben	5a906b757d	keycloak, grafana: their public names come from the mesh, not the manifest GF_SERVER_ROOT_URL=https://grafana.zurag.be, KC_HOSTNAME=https://keycloak.novox.be and the served issuer's novox default were domains in definitions — wrong on every other machine (ADR 0112). The names now come from ${bound:route:name} (mesh-controller #149, hq 122): grafana's in oidc.env, keycloak's in a hostname.env its server reads. The issuer includes the realm and stays the assignment's, with no default: unset, a consumer asking for it is refused and the provisioner says so, rather than both quietly using novox's URL. Rendered through mesh-controller #149 from these manifests on a zurag.be node: KC_HOSTNAME=https://keycloak.zurag.be, GF_SERVER_ROOT_URL= https://grafana.zurag.be, OIDC URLs from the issuer setting. Needs #149 merged and rolled out first.	2026-09-30 00:49:08 +02:00
jschoubben	d8ee88e487	grafana: log in through keycloak's oidc-client provision HAL's grafana logged in through a hand-made Keycloak client whose secret sat in its .env. Requiring oidc-client gives it a client the mesh makes and keeps: the id and URLs come from the binding, the secret arrives as a file grafana reads itself (__FILE), and the callback it contributes is what keycloak registers as its redirect. GF_SERVER_ROOT_URL is still a literal: a module cannot yet learn the public name the mesh composes for its own endpoint (hq issue 122), and without it grafana sends a redirect Keycloak refuses.	2026-09-30 00:39:16 +02:00
jschoubben	54557b77bf	keycloak: provide oidc-client, one mesh-made client per consumer A module that logs people in through Keycloak had to be given a client by hand, with its secret copied into the consumer's environment. As a provision the mesh derives the client id (the consumer's identity, mesh_<node>_<module>) and mints its secret, and delivers both ends: keycloak creates exactly that confidential client, the consumer names it through ${bound:oidc-client:as}. The consumer says where its browser comes back to (`callback`) and which endpoint it is reached on (`label`/`endpoint`), so the redirect is built from the same names the mesh composes for its route. keycloak serves the issuer and the endpoint paths under it; the issuer is the one value an assignment sets, and the realm is read out of it, so consumer and client cannot disagree. Only what the mesh made is touched: its clients carry mesh.provisioned=true; a client of the same id without the mark is refused, never adopted, updated or deleted. The runtime now gets the admin password as a file, which its tools also needed and never had.	2026-09-30 00:39:16 +02:00
jschoubben	a5e21cb438	grafana: its directories are placed, its admin password is a file, and it runs the build in use The module stated /var/lib/grafana-module and /services/grafana/data, a layout no definition may carry (ADR 0112). State and data are now placed directories; the admin secret lives beside the broker account under the mesh's own state. The admin password reached grafana through an env-file. Grafana honours GF_SECURITY_ADMIN_PASSWORD__FILE, so it is now a 0400 file owned by the image's user (472) and mounted, and "secrets-in-environment" is gone (ADR 0086). The runtime sidecar was given no credential at all - its config file was "{}", so GrafanaClient.fromEnv threw and the tools and the alert watcher did nothing. It now carries user/password from the same secret, and it calls grafana on the machine port the mesh assigned (${port:3000}) rather than a literal 3000. Image pinned to the 13.2.2 build ace's predecessor runs; the old pin was 13.2.1, older than the data it would open. Verified: catalogue tests with MESH_CATALOGUE pointing here; a throwaway container of the pinned image with the file-mounted secret answers /api/health and authenticates admin with the file's value (default admin/admin refused); restarted over the same data with a different file value, the original password still holds - so a migrated instance's password must be accepted, not minted; data owned by another uid fails to start, so a moved data directory must be chowned to 472.	2026-09-29 23:43:00 +02:00
jschoubben	fe0ed3b74e	influxdb: place its directories, hand secrets over as files, name its UI The manifest named /services/influxdb and /var/lib/influxdb-module — one machine's paths — and passed the admin password and token through the environment. ace is moving its 2022 instance onto the mesh, so the module has to be what it is on any machine. - data, config and state are placed directories; the data keeps 1000:1000, the image's influxdb user, which is who owns ace's data today. - the init secrets reach the image through its own DOCKER_INFLUXDB_INIT_{PASSWORD,ADMIN_TOKEN}_FILE; the vault's files are mounted read-only. secrets-in-environment is gone. - the sidecar reads its token from the same file (MESH_INFLUXDB_TOKEN_FILE, added to client.ts) and reaches the server at its assigned machine port (${port:8086}) instead of assuming 8086. The unused config-dir mount, which held the CLI's copy of the admin token, is dropped. - the api endpoint contributes a route: the web UI is how people use it, and reach is the assignment's to say. Verified: catalogue tests pass with MESH_CATALOGUE pointed at this tree. The pinned 2.9.1 image, run on a scratch copy of ace's 2.4.0 data, opens it, runs its metadata migrations (backing up the pre-upgrade bolt/sqlite) and hashes the two stored tokens; /health passes. A fresh setup through the _FILE variables, with dummy secrets as root-owned 0600 files, accepts the token (200 on /api/v2/buckets) and the password (204 on /signin). client.ts typechecks strict and reads the token file, tolerating the endpoints key in its config.	2026-09-29 23:42:18 +02:00