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.

modules/ca-trust/module.json

@@ -0,0 +1,56 @@
+{
+  "module": "ca-trust",
+  "version": "1",
+  "slug": "catrust",
+  "capabilities": [
+    "service-manager"
+  ],
+  "requires": [
+    "internal-acme-ca"
+  ],
+  "seats": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "claims": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
+    {
+      "id": "anchor",
+      "type": "file",
+      "path": "${dir:state}/anchor",
+      "mode": "0755",
+      "content": "#!/bin/sh\n# The mesh's internal certificate authority, trusted by this machine.\n#\n# Written by the mesh from the ca-trust module's manifest (novox/hq ADR 0147).\n# Editing it here lasts until the next apply.\n#\n# There is no prior trust to verify the fetch against \u2014 this is the thing that\n# establishes it \u2014 so it is made over the mesh's own private network, which is\n# what authenticates it (novox/hq ADR 0098, the same reasoning that lets the\n# route proxy fetch this root for itself). What comes back is checked here: a\n# body that is not a certificate is refused now, rather than believed and then\n# failed by whatever reads the trust store next.\nset -eu\n\nROOTS='https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:roots}'\nANCHORS=/etc/ca-certificates/trust-source/anchors\nANCHOR=\"$ANCHORS/mesh-internal-ca.crt\"\n\n# Arch's layout, said out loud rather than assumed: a machine that keeps its\n# anchors elsewhere fails here, visibly, instead of writing a file nothing\n# reads. That failure is the signal that this belongs in the host, where one\n# operating system's difference lives (novox/hq ADR 0147, option 2).\n[ -d \"$ANCHORS\" ] || {\n\techo \"this machine keeps no trust anchors in $ANCHORS; ca-trust is written for that layout\" >&2\n\texit 1\n}\n\ncase \"${1:-}\" in\ninstall)\n\ttmp=$(mktemp)\n\ttrap 'rm -f \"$tmp\"' EXIT\n\t# The authority may still be starting, or this machine may have come up\n\t# before it: two minutes of asking, then an honest failure.\n\tn=0\n\twhile [ \"$n\" -lt 60 ]; do\n\t\tif curl --fail --silent --show-error --insecure --max-time 10 \\\n\t\t\t--output \"$tmp\" \"$ROOTS\" &&\n\t\t\tgrep -q 'BEGIN CERTIFICATE' \"$tmp\"; then\n\t\t\tinstall -m 0644 \"$tmp\" \"$ANCHOR\"\n\t\t\tupdate-ca-trust\n\t\t\texit 0\n\t\tfi\n\t\tn=$((n + 1))\n\t\tsleep 2\n\tdone\n\techo \"the authority at $ROOTS did not serve a certificate within two minutes\" >&2\n\texit 1\n\t;;\nremove)\n\t# What stopping the unit does, and therefore what being unassigned does.\n\trm -f \"$ANCHOR\"\n\tupdate-ca-trust\n\t;;\n*)\n\techo \"usage: $(basename \"$0\") install|remove\" >&2\n\texit 2\n\t;;\nesac\n"
+    },
+    {
+      "id": "unit",
+      "type": "file",
+      "path": "/etc/systemd/system/mesh-ca-trust.service",
+      "mode": "0644",
+      "content": "[Unit]\nDescription=The mesh's internal certificate authority, trusted by this machine\n# novox/hq ADR 0147. Starting this unit places the mesh's root among this\n# machine's trust anchors; stopping it takes the root away again, which is what\n# the host does when the module is no longer assigned here.\nWants=network-online.target\nAfter=network-online.target\n\n[Service]\nType=oneshot\nRemainAfterExit=yes\nExecStart=${dir:state}/anchor install\nExecStop=${dir:state}/anchor remove\n\n[Install]\nWantedBy=multi-user.target\n"
+    },
+    {
+      "id": "trust",
+      "type": "service",
+      "unit": "mesh-ca-trust.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "anchor",
+        "unit"
+      ]
+    }
+  ]
+}

modules/grafana/module.json

@@ -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,68 @@
     {
       "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": "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"
       ],
+      "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"
+      ]
     },
     {
       "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 +105,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 +115,26 @@
     }
   ],
   "requires": [
-    "route"
+    "route",
+    "oidc-client"
   ],
   "contributes": {
     "route": {
       "label": "grafana",
       "endpoint": "web"
+    },
+    "oidc-client": {
+      "label": "grafana",
+      "endpoint": "web",
+      "callback": "/login/generic_oauth"
     }
   },
   "binds": {
-    "route": "/var/lib/mesh/grafana/route.json"
+    "route": "${dir:state}/route.json",
+    "oidc-client": "${dir:state}/oidc.json"
+  },
+  "secrets": {
+    "oidc-client": "/var/lib/mesh/grafana/oidc-client"
   },
   "build": {
     "on": [

modules/keycloak/Dockerfile

@@ -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

modules/keycloak/client.ts

@@ -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" });
   }

modules/keycloak/module.json

@@ -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"

modules/keycloak/oidc.ts

@@ -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";
+  }
+}

modules/keycloak/package.json

@@ -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",

modules/keycloak/provisioner/index.ts

@@ -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);
+  },
+});

modules/keycloak/test/oidc.test.ts

@@ -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);
+});

modules/keycloak/tsconfig.json

@@ -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"]
 }

modules/network-checker/check/index.ts

@@ -1,84 +0,0 @@
-// Dial everything the mesh claims is reachable, and say what was found (novox/hq ADR 0145).
-//
-// Runs on a cadence, from this machine, in this module's own container — the same position every other
-// module on the machine calls from. That is the whole point: a check run by the host or by the control
-// plane reaches these addresses by a path no ordinary caller uses, and would have passed throughout the
-// outage that produced this module (novox/hq 04-ISSUES/145).
-//
-// It reports and does nothing else. A checker that repaired things would be a second control plane.
-
-import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-import { dial, tally, targetsFor, type Counts, type Result, type Roster } from "../reach.js";
-
-/** Where the mesh renders this machine's view of the others, and where the counts are kept between runs. */
-const rosterFile = process.env.MESH_NETWORK_CHECKER_ROSTER ?? "/run/config/roster.json";
-const stateDir = process.env.MESH_NETWORK_CHECKER_STATE ?? "/run/state";
-const probePort = Number(process.env.MESH_NETWORK_CHECKER_PORT ?? "9876");
-const publicPort = process.env.MESH_NETWORK_CHECKER_PUBLIC_PORT
-  ? Number(process.env.MESH_NETWORK_CHECKER_PUBLIC_PORT)
-  : undefined;
-const timeoutMs = Number(process.env.MESH_NETWORK_CHECKER_TIMEOUT_MS ?? "4000");
-const threshold = Number(process.env.MESH_NETWORK_CHECKER_THRESHOLD ?? "2");
-
-/** read is a JSON file or a stated failure — never a silent default, which is how a checker comes to
- *  report that everything is fine because it read nothing. */
-function read<T>(path: string, whenMissing: T | null): T {
-  try {
-    return JSON.parse(readFileSync(path, "utf8")) as T;
-  } catch (err) {
-    if (whenMissing !== null) return whenMissing;
-    console.error(`network-checker: cannot read ${path}: ${(err as Error).message}`);
-    process.exit(1);
-  }
-}
-
-function writeAtomically(path: string, body: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const temp = `${path}.writing`;
-  writeFileSync(temp, body);
-  renameSync(temp, path);
-}
-
-async function main(): Promise<void> {
-  const roster = read<Roster>(rosterFile, null);
-  if (!roster.machines?.length) {
-    console.error("network-checker: the roster names no machines; nothing to check");
-    process.exit(1);
-  }
-
-  const targets = targetsFor(roster, probePort, publicPort);
-  // In parallel, because a machine that is away should not delay the rest: a run that takes
-  // machines × timeout would outlast its own cadence on a mesh of any size.
-  const results: Result[] = await Promise.all(targets.map((t) => dial(t, timeoutMs)));
-
-  const countsFile = join(stateDir, "consecutive.json");
-  const { counts, broken } = tally(results, read<Counts>(countsFile, {}), threshold);
-  writeAtomically(countsFile, JSON.stringify(counts, null, 1));
-
-  // Written whole, every run: a reader asking "what does this machine reach" gets an answer about now
-  // rather than the last time something changed.
-  writeAtomically(join(stateDir, "reach.json"), JSON.stringify({
-    node: roster.node,
-    at: new Date().toISOString(),
-    checked: results.length,
-    broken: broken.length,
-    results,
-  }, null, 1));
-
-  for (const b of broken) {
-    console.error(
-      `network-checker: ${roster.node} cannot reach ${b.machine} (${b.claim}) at ${b.at}:${b.port} — ` +
-      `${b.failed} failed${b.detail ? `: ${b.detail}` : ""}, ${b.consecutive} run(s) running`);
-  }
-  if (broken.length === 0) {
-    console.log(`network-checker: ${roster.node} reaches all ${results.length} checked path(s)`);
-  }
-
-  // A broken path is not this process failing. It did its job; exiting non-zero would make the mesh
-  // read the checker as the fault, and a scheduled step that fails is retried rather than believed.
-  process.exit(0);
-}
-
-void main();

modules/network-checker/module.json

@@ -1,61 +0,0 @@
-{
-  "module": "network-checker",
-  "version": "1",
-  "slug": "netcheck",
-  "listens": [
-    {
-      "name": "probe",
-      "port": 9876,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "what the other machines' checkers dial. Deliberately this module's own endpoint and nothing else's: it is admitted by exactly the rule that governs every internally-exposed service, so it fails when that rule is wrong. A probe on a port that is never closed — ssh, say — would have passed throughout the outage this module exists to catch (novox/hq ADR 0145)"
-    }
-  ],
-  "facts": {
-    "roster": {
-      "path": "/var/lib/network-checker/roster.json",
-      "template": "{\n \"generated\": \"by the mesh — do not edit; replaced whenever a machine joins or leaves\",\n \"node\": \"{{.Node}}\",\n \"machines\": [{{range $i, $m := .Machines}}{{if $i}},{{end}}\n  { \"name\": \"{{$m.Name}}\", \"fqdn\": \"{{$m.FQDN}}\", \"address\": \"{{$m.Address}}\" }{{end}}\n ]\n}\n"
-    }
-  },
-  "build": {
-    "artifacts": [
-      {
-        "name": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": ["probe/index.js", "check/index.js"]
-      }
-    ]
-  },
-  "resources": [
-    {
-      "id": "state",
-      "type": "directory",
-      "path": "/var/lib/network-checker",
-      "mode": "0700"
-    },
-    {
-      "id": "probe",
-      "type": "container",
-      "name": "mesh-network-checker-probe",
-      "args": ["run", "/app/modules/network-checker/dist/probe/index.js"],
-      "ports": ["9876"],
-      "state": "running",
-      "env": { "MESH_NETWORK_CHECKER_PORT": "9876" }
-    },
-    {
-      "id": "check",
-      "type": "container",
-      "name": "mesh-network-checker-check",
-      "network": "host",
-      "schedule": "*/5 * * * *",
-      "args": ["run", "/app/modules/network-checker/dist/check/index.js"],
-      "volumes": ["/var/lib/network-checker:/run/state"],
-      "env": {
-        "MESH_NETWORK_CHECKER_ROSTER": "/run/state/roster.json",
-        "MESH_NETWORK_CHECKER_STATE": "/run/state",
-        "MESH_NETWORK_CHECKER_PORT": "${port:9876}"
-      }
-    }
-  ]
-}

modules/network-checker/package.json

@@ -1,8 +0,0 @@
-{
-  "name": "@novox/module-network-checker",
-  "version": "0.1.0",
-  "description": "network-checker — dials what the mesh claims is reachable, from where the callers are, and says what it found.",
-  "type": "module",
-  "private": true,
-  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" }
-}

modules/network-checker/probe/index.ts

@@ -1,31 +0,0 @@
-// The endpoint the other machines' checkers dial (novox/hq ADR 0145).
-//
-// **This module's own endpoint is the instrument.** It is declared reachable over the private network
-// like any other service, so it is admitted by exactly the rule that governs every internally-exposed
-// service and it fails when that rule is wrong. A probe on a port that is never closed — ssh, say —
-// would have passed throughout the outage this module exists to catch.
-//
-// It accepts a connection and closes it. Answering anything would make this a protocol, and then the
-// question would be whether the protocol worked rather than whether the path did.
-
-import { createServer } from "node:net";
-
-const port = Number(process.env.MESH_NETWORK_CHECKER_PORT ?? "9876");
-
-const server = createServer((socket) => {
-  // Written before closing so a person dialling it by hand sees something, and so a half-open
-  // connection is not mistaken for a working path by a client that only checks the handshake.
-  socket.end("mesh network-checker\n");
-});
-
-server.on("error", (err: Error) => {
-  // Said and fatal: a probe that cannot listen must not look like a probe that nothing dialled.
-  console.error(`network-checker: cannot serve the probe on ${port}: ${err.message}`);
-  process.exit(1);
-});
-
-server.listen(port, () => console.log(`network-checker: probe listening on ${port}`));
-
-for (const signal of ["SIGTERM", "SIGINT"] as const) {
-  process.on(signal, () => server.close(() => process.exit(0)));
-}

modules/network-checker/reach.ts

@@ -1,155 +0,0 @@
-// What the mesh claims is reachable, and how to find out (novox/hq ADR 0145).
-//
-// The mesh asserts three things are callable (ADR 0144): what runs on the same machine, another
-// machine's service exposed to the private network, and another machine's service exposed publicly.
-// This decides what to dial for each and reads the answers. It opens connections and nothing more —
-// the module that owns a service is the one that knows whether it is working.
-//
-// **The target is this module's own endpoint, and that is deliberate.** The obvious thing to dial is a
-// service every machine has, and the services every machine has are the ones never closed — ssh above
-// all. Dialling one of those would have passed throughout the outage this exists to catch, because what
-// broke was a service exposed to the private network and ssh is admitted unconditionally. A probe on a
-// port that cannot fail measures nothing.
-
-import { connect } from "node:net";
-import { lookup } from "node:dns";
-
-/** One machine as the mesh's roster describes it. */
-export interface Machine {
-  name: string;
-  fqdn: string;
-  address: string;
-  /** The name this machine is reached by from outside, where it has one. Absent for most machines, and
-   *  a machine with no public face has no public claim to check. */
-  public?: string;
-}
-
-/** The roster the mesh renders for this module: who this machine is, and who the others are. */
-export interface Roster {
-  node: string;
-  machines: Machine[];
-}
-
-/** Which of the mesh's three claims a check is about, so a failure says which one broke. */
-export type Claim = "this machine" | "the private network" | "the public network";
-
-/** One thing to dial. */
-export interface Target {
-  claim: Claim;
-  machine: string;
-  /** What to dial — a name where the point is that names resolve, an address where it is not. */
-  at: string;
-  port: number;
-  /** Whether `at` is a name that must resolve first, so a resolution failure is reported as one. */
-  byName: boolean;
-}
-
-/** What one dial found. */
-export interface Result extends Target {
-  ok: boolean;
-  /** Which step failed, so a reader is sent to the right place: the resolver, or the filter. */
-  failed?: "resolution" | "connection";
-  detail?: string;
-  ms: number;
-}
-
-/**
- * targetsFor is everything this machine should be able to reach, from the roster it was given.
- *
- * Its own machine first, because that is the case that distinguishes a caller on the machine from a
- * caller in one of its containers — the one that broke. Then every other machine over the private
- * network. The public claim is only checked where a public address is known for a machine, because a
- * machine with no public face has nothing to fail.
- */
-export function targetsFor(roster: Roster, probePort: number, publicPort?: number): Target[] {
-  const out: Target[] = [];
-  for (const m of roster.machines) {
-    const own = m.name === roster.node;
-    out.push({
-      claim: own ? "this machine" : "the private network",
-      machine: m.name,
-      at: m.address,
-      port: probePort,
-      byName: false,
-    });
-    // And by name, because a name that does not resolve and a port that does not answer are different
-    // faults with different owners.
-    out.push({
-      claim: own ? "this machine" : "the private network",
-      machine: m.name,
-      at: m.fqdn,
-      port: probePort,
-      byName: true,
-    });
-  }
-  if (publicPort !== undefined) {
-    for (const m of roster.machines) {
-      if (!m.public) continue;
-      out.push({
-        claim: "the public network",
-        machine: m.name,
-        at: m.public,
-        port: publicPort,
-        byName: true,
-      });
-    }
-  }
-  return out;
-}
-
-/** dial opens a connection and closes it. Whether the port accepts is the whole of what is asked. */
-export function dial(target: Target, timeoutMs: number): Promise<Result> {
-  const began = Date.now();
-  const done = (ok: boolean, failed?: Result["failed"], detail?: string): Result => ({
-    ...target, ok, failed, detail, ms: Date.now() - began,
-  });
-
-  return new Promise<Result>((resolve) => {
-    const open = () => {
-      const socket = connect({ host: target.at, port: target.port });
-      const finish = (r: Result) => { socket.destroy(); resolve(r); };
-      socket.setTimeout(timeoutMs);
-      socket.once("connect", () => finish(done(true)));
-      socket.once("timeout", () => finish(done(false, "connection", "timed out")));
-      socket.once("error", (err: Error) => finish(done(false, "connection", err.message)));
-    };
-
-    if (!target.byName) { open(); return; }
-    // Resolved first and reported separately: a checker that says "unreachable" for a name the
-    // resolver never answered sends a reader to the filter, which is not where the fault is.
-    lookup(target.at, (err) => {
-      if (err) { resolve(done(false, "resolution", err.message)); return; }
-      open();
-    });
-  });
-}
-
-/** A path's running count of consecutive failures, keyed so it survives between runs. */
-export type Counts = Record<string, number>;
-
-/** keyOf names one path, stably, so a count follows it across runs. */
-export function keyOf(t: Target): string {
-  return `${t.claim}|${t.machine}|${t.at}|${t.port}`;
-}
-
-/**
- * tally folds this run's results into the counts carried from the last one.
- *
- * **One failure is not a fault.** A machine rebooting is ordinary, and a checker that cries at the
- * first missed dial trains a reader to ignore it — which is worse than not checking (ADR 0145). A path
- * is broken once it has failed on consecutive runs, and the count travels with the result so a reader
- * can tell "briefly away" from "never worked".
- */
-export function tally(results: Result[], before: Counts, threshold: number): {
-  counts: Counts; broken: Array<Result & { consecutive: number }>;
-} {
-  const counts: Counts = {};
-  const broken: Array<Result & { consecutive: number }> = [];
-  for (const r of results) {
-    const key = keyOf(r);
-    const n = r.ok ? 0 : (before[key] ?? 0) + 1;
-    if (n > 0) counts[key] = n;
-    if (n >= threshold) broken.push({ ...r, consecutive: n });
-  }
-  return { counts, broken };
-}

modules/network-checker/test/reach.test.ts

@@ -1,72 +0,0 @@
-import { strict as assert } from "node:assert";
-import test from "node:test";
-
-import { keyOf, tally, targetsFor, type Result, type Roster } from "../reach.js";
-
-const roster: Roster = {
-  node: "here",
-  machines: [
-    { name: "here", fqdn: "here.internal", address: "10.0.0.1" },
-    { name: "there", fqdn: "there.internal", address: "10.0.0.2", public: "there.example.test" },
-  ],
-};
-
-test("its own machine is checked, which is the case that distinguishes a caller on it from one in a container", () => {
-  const own = targetsFor(roster, 9876).filter((t) => t.claim === "this machine");
-  assert.equal(own.length, 2, "its own machine by address and by name");
-  assert.ok(own.some((t) => t.at === "10.0.0.1" && !t.byName));
-  assert.ok(own.some((t) => t.at === "here.internal" && t.byName));
-});
-
-test("every other machine is checked over the private network", () => {
-  const other = targetsFor(roster, 9876).filter((t) => t.claim === "the private network");
-  assert.deepEqual(other.map((t) => t.machine), ["there", "there"]);
-});
-
-test("the public claim is only checked where a machine has a public name", () => {
-  const pub = targetsFor(roster, 9876, 443).filter((t) => t.claim === "the public network");
-  assert.equal(pub.length, 1, "only the machine with a public name");
-  assert.equal(pub[0]!.at, "there.example.test");
-  assert.equal(pub[0]!.port, 443);
-});
-
-test("no public claim is made when no public port was given", () => {
-  assert.equal(targetsFor(roster, 9876).filter((t) => t.claim === "the public network").length, 0);
-});
-
-const failed = (at: string): Result => ({
-  claim: "this machine", machine: "here", at, port: 9876, byName: false,
-  ok: false, failed: "connection", ms: 1,
-});
-const passed = (at: string): Result => ({
-  claim: "this machine", machine: "here", at, port: 9876, byName: false, ok: true, ms: 1,
-});
-
-test("one failure is not a fault — a machine rebooting is ordinary", () => {
-  const { counts, broken } = tally([failed("10.0.0.1")], {}, 2);
-  assert.equal(broken.length, 0, "one missed dial says nothing");
-  assert.equal(counts[keyOf(failed("10.0.0.1"))], 1, "and is remembered");
-});
-
-test("a path that keeps failing is broken, and the count travels with it", () => {
-  const first = tally([failed("10.0.0.1")], {}, 2);
-  const second = tally([failed("10.0.0.1")], first.counts, 2);
-  assert.equal(second.broken.length, 1);
-  assert.equal(second.broken[0]!.consecutive, 2, "so a reader can tell briefly away from never worked");
-});
-
-test("a path that recovers stops being counted", () => {
-  const first = tally([failed("10.0.0.1")], {}, 2);
-  const second = tally([passed("10.0.0.1")], first.counts, 2);
-  assert.equal(second.broken.length, 0);
-  assert.deepEqual(second.counts, {}, "nothing carried forward for a path that works");
-});
-
-test("a count follows one path and not another", () => {
-  const a = failed("10.0.0.1");
-  const b = failed("10.0.0.2");
-  const first = tally([a, b], {}, 2);
-  const second = tally([a], first.counts, 2);
-  assert.equal(second.broken.length, 1, "only the path dialled this run is judged");
-  assert.equal(second.broken[0]!.at, "10.0.0.1");
-});

modules/network-checker/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": ["reach.ts", "probe/index.ts", "check/index.ts", "test/*.ts"]
-}

modules/searxng/module.json

@@ -5,7 +5,7 @@
     "container-runtime"
   ],
   "own-secrets": {
-    "secret": "/var/lib/searxng-module/secret.secret",
+    "secret": "/var/lib/mesh/searxng/secret",
     "broker": "/var/lib/mesh/searxng/broker"
   },
   "listens": [
@@ -27,22 +27,14 @@
     {
       "id": "state",
       "type": "directory",
-      "path": "/var/lib/searxng-module",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
     },
     {
       "id": "valkey-data",
       "type": "directory",
-      "path": "/var/lib/searxng-module/valkey-data",
       "mode": "0700"
     },
-    {
-      "id": "server-env",
-      "type": "file",
-      "path": "/var/lib/searxng-module/server.env",
-      "mode": "0600",
-      "content": "SEARXNG_SECRET=${secret:secret}\nSEARXNG_VALKEY_URL=valkey://valkey:6379/0\n"
-    },
     {
       "id": "net",
       "type": "network",
@@ -63,30 +55,39 @@
         "warning"
       ],
       "volumes": [
-        "/var/lib/searxng-module/valkey-data:/data"
+        "${dir:valkey-data}:/data"
       ]
     },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.yml",
+      "mode": "0600",
+      "merge": "json",
+      "content": "{\n  \"use_default_settings\": true,\n  \"server\": {\n    \"secret_key\": \"${secret:secret}\",\n    \"base_url\": false,\n    \"limiter\": false,\n    \"image_proxy\": false,\n    \"public_instance\": false\n  },\n  \"search\": {\n    \"formats\": [\"html\", \"json\"]\n  },\n  \"valkey\": {\n    \"url\": \"valkey://valkey:6379/0\"\n  }\n}\n"
+    },
     {
       "id": "server",
       "type": "container",
       "name": "searxng",
-      "image": "searxng/searxng@sha256:c7cc75852051bf6254afda6ed1b920dd1677d8efe4ab141bf558f02e582f4371",
+      "image": "searxng/searxng@sha256:cd8812607ab73730a0b1a0dc4990223fe1b9e383f6f35947114d0bef7f8bb441",
       "network": "searxng",
-      "env-file": [
-        "/var/lib/searxng-module/server.env"
-      ],
       "ports": [
         "8080"
       ],
-      "secrets-in-environment": "SEARXNG_SECRET is env-only, but settings.yml carries server.secret_key; convertible by mounting a generated settings.yml, not yet done"
+      "volumes": [
+        "${dir:state}/settings.yml:/etc/searxng/settings.yml:ro"
+      ],
+      "restart-on": [
+        "settings"
+      ]
     },
     {
       "id": "runtime-config",
       "type": "file",
       "path": "/var/lib/mesh/searxng/config.json",
       "mode": "0600",
-      "content": "{}\n",
+      "content": "{}\n"
-      "merge": "json"
     },
     {
       "id": "runtime",
@@ -118,7 +119,7 @@
     }
   },
   "binds": {
-    "route": "/var/lib/searxng-module/route.json"
+    "route": "${dir:state}/route.json"
   },
   "build": {
     "on": [