n8n: its own image built from source, placed data, and what its workflows use

The module named /var/lib/n8n, /services/n8n/n8n-data and n8n.novox.be - paths and a domain no definition may carry (ADR 0112). State and data are placed directories; the public name is ${bound:route:name} (depends on mesh-controller #149), for N8N_HOST and WEBHOOK_URL alike. The endpoint said 5682 while the container publishes 5678. 5682 was one machine's host port; the endpoint is the software's port and the mesh assigns the machine's (ADR 0038). n8n had been run from an image in a registry that no longer exists: the upstream image plus shadow, a `media` group (2000) with `node` in it, and a global `uuid`. That recipe is now this module's Dockerfile, built on the upstream 1.71.3 image named in build.on by digest, with uuid pinned to the version the running image carries (14.0.1) - Code nodes require() it. The media group is how the container writes into the shared media library, a read-write `access` (ADR 0051), mounted where workflows expect it, /media-library. The workflows also use a redis (the Redis nodes of the chat workflows) and a Selenium Chrome (the scraper), which the previous deployment ran beside n8n. Both are containers on the module's own network, publishing nothing, pinned to the digests in use; redis keeps its append-only file in a placed directory. The basic-auth secret is gone: N8N_BASIC_AUTH_* was removed in n8n 1.0 and did nothing. The grant's password is a 0400 file owned by `node`, read through DB_POSTGRESDB_PASSWORD_FILE, so nothing secret is in the environment. The credentials' encryption key is n8n's own, in the data directory (config), and moves with it - nothing to mint or accept. Verified: catalogue tests with MESH_CATALOGUE set; the Dockerfile built against the pinned base gives n8n 1.71.3, uid 1000 in group 2000, uuid 14.0.1 - the running image's shape. Throwaway containers: an instance on PostgreSQL 15 with an owner, a workflow and an encrypted credential; stopped, copied, dumped from the copy, restored (--no-owner --role, the uuid-ossp extension pre-made by the superuser) into a grant-shaped database on the postgres module's pgvector image (PG17); the new shape (password from the file, data dir copied) serves /healthz, the owner logs in, the workflow is listed, and the credential decrypts with the carried key. The node user writes into a root:2000 0775 library through the media group; redis and Selenium resolve by name on the module network and Selenium reports ready. Test containers and data removed.
Merge pull request 'gitea: the tools' token carries write:admin; a kept token is re-minted when it lacks a scope' (#192 ) from feat/gitea-token-write-admin into main
2026-09-30 21:26:08 +02:00 · 2026-09-30 19:06:05 +00:00 · 2026-09-30 21:05:52 +02:00 · 2026-09-30 19:01:49 +00:00 · 2026-09-30 21:01:47 +02:00 · 2026-09-30 18:56:26 +00:00
130 changed files with 4811 additions and 1475 deletions
@@ -1,56 +0,0 @@
 {
  "module": "amqp-email-forwarder",
  "version": "1",
  "slug": "emailfwd",
  "capabilities": [
    "container-runtime"
  ],
  "requires": [
    "amqp"
  ],
  "contributes": {},
  "binds": {
    "amqp": "/var/lib/amqp-email-forwarder/amqp.json"
  },
  "secrets": {
    "amqp": "/var/lib/amqp-email-forwarder/amqp.secret"
  },
  "own-secrets": {
    "smtp-user": "/var/lib/amqp-email-forwarder/smtp-user.secret",
    "smtp-password": "/var/lib/amqp-email-forwarder/smtp-password.secret"
  },
  "resources": [
    {
      "id": "state",
      "type": "directory",
      "path": "/var/lib/amqp-email-forwarder",
      "mode": "0700"
    },
    {
      "id": "app-env",
      "type": "file",
      "path": "/var/lib/amqp-email-forwarder/app.env",
      "mode": "0600",
      "content": "AMQP_HOST=${bound:amqp:at}\nAMQP_PORT=${bound:amqp:port}\nAMQP_USER=${bound:amqp:as}\nAMQP_VHOST=EMAILDELIVERY_T\nAMQP_EXCHANGE=News.TransactionalEmailing.Command\nAMQP_QUEUE=email-forwarder\nAMQP_URL=amqp://${bound:amqp:as}:${secret:amqp}@${bound:amqp:at}:${bound:amqp:port}/EMAILDELIVERY_T\nSMTP_HOST=mail.novox.be\nSMTP_PORT=587\nSMTP_USER=${secret:smtp-user}\nSMTP_PASSWORD=${secret:smtp-password}\n"
    },
    {
      "id": "net",
      "type": "network",
      "name": "amqp-email-forwarder"
    },
    {
      "id": "app",
      "type": "container",
      "name": "amqp-email-forwarder",
      "image": "registry-api.novox.be/novox/amqp-email-forwarder@sha256:f76d34646d9d3b2098c72688a63f6ae656f1888ffcb2f90a9c8dd2a44ad7f8af",
      "network": "amqp-email-forwarder",
      "env-file": [
        "/var/lib/amqp-email-forwarder/app.env"
      ],
      "restart-on": [
        "app-env"
      ],
      "secrets-in-environment": "the application's own code reads AMQP_URL, SMTP_USER and SMTP_PASSWORD from the environment (amqp-email-forwarder app.js); converting is that repository's change"
    }
  ]
 }
@@ -1,31 +0,0 @@
 # amqp-ping's runtime: the tool runtime, carrying this module's compiled code.
 #
 # **Built from this module's own directory and nothing else.** The sdk and the tool runtime are not
 # copied out of neighbouring checkouts — they are in the base image, which is published like any
 # other artifact. That is what makes this buildable by the mesh from a repository and a path
 # (novox/hq ADR 0069) rather than only on a workstation that happens to have the siblings.
 #
 # Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
 # They are different images on purpose — the first carries a compiler and the second must not, or
 # every running container would carry one it never invokes. The mesh answers both with the copies it
 # holds, because a fingerprint written here would name one particular copy and no other mesh has it
 # (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
 # nobody told stops here and says which module to build first.
 ARG BUILD_BASE
 ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 # Compiled under /app/modules, so resolving `@novox/mesh-sdk` walks up to the base's own
 # node_modules — the module is compiled against exactly the sdk it will run against.
 WORKDIR /app/modules/amqp-ping
 COPY . .
 # The compiler is invoked by its real path, not through node_modules/.bin. Those are symlinks to
 # a launcher that requires its library relatively, and the base image resolves them when copying —
 # leaving a launcher whose relative require no longer points at anything.
 RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/amqp-ping/dist /app/modules/amqp-ping/dist
 # Declared rather than derived from which files happen to exist: the module knows what it serves.
 ENV MESH_TOOL_MODULES=/app/modules/amqp-ping/dist/index.js
@@ -1,191 +0,0 @@
 // amqp-ping's AMQP client — the demo consumer's own code (novox/hq ADR 0039). It speaks AMQP 0-9-1
 // directly over a raw TCP socket (node:net), the way redis's client speaks RESP: the module carries
 // NO npm dependency beyond @novox/mesh-sdk — no amqplib, no CLI in the image. It does exactly one
 // thing, the round-trip that proves the grant works: connect, authenticate with PLAIN to the vhost
 // the mesh named, declare a queue, publish one message and get it back.
 //
 // This is the consumer half of the `amqp` interface. It connects as the login the mesh derived
 // (`${bound:amqp:as}`) with the password the mesh minted (`${secret:amqp}`) to a vhost of that SAME
 // name — the provider named the vhost after the login, so the consumer must too. Nothing here is
 // hardcoded: user AND vhost are both the bound login, and a wrong vhost is refused by the broker.
 import { createConnection, type Socket } from "node:net";
 import { readFileSync } from "node:fs";
 const FRAME_END = 0xce;
 const PROTOCOL_HEADER = Buffer.from([0x41, 0x4d, 0x51, 0x50, 0x00, 0x00, 0x09, 0x01]); // "AMQP" 0-9-1
 export interface AmqpConn {
  readonly host: string;
  readonly port: number;
  readonly user: string;
  readonly password: string;
  readonly vhost: string;
 }
 /** Build the connection facts from the environment the mesh's env-file set (see the module manifest). */
 export function connFromEnv(env: NodeJS.ProcessEnv = process.env): AmqpConn {
  const host = env.MESH_AMQP_HOST ?? "";
  const port = Number(env.MESH_AMQP_PORT ?? "5672") || 5672;
  const user = env.MESH_AMQP_USER ?? "";
  const vhost = env.MESH_AMQP_VHOST ?? user; // the provider names the vhost after the login
  const password = env.MESH_AMQP_PASSWORD ?? readMaybe(env.MESH_AMQP_PASSWORD_FILE);
  if (!host || !user || !password) {
    throw new Error(`amqp-ping: connection is not fully set yet (host=${host} user=${user} password=${password ? "set" : "unset"})`);
  }
  return { host, port, user, password, vhost };
 }
 // --- wire helpers ---------------------------------------------------------------------------------
 function shortstr(s: string): Buffer {
  const b = Buffer.from(s, "utf8");
  const o = Buffer.alloc(1 + b.length);
  o.writeUInt8(b.length, 0);
  b.copy(o, 1);
  return o;
 }
 function longstr(s: Buffer | string): Buffer {
  const b = Buffer.isBuffer(s) ? s : Buffer.from(s, "utf8");
  const o = Buffer.alloc(4 + b.length);
  o.writeUInt32BE(b.length, 0);
  b.copy(o, 4);
  return o;
 }
 function u16(n: number): Buffer {
  const o = Buffer.alloc(2);
  o.writeUInt16BE(n, 0);
  return o;
 }
 function u32(n: number): Buffer {
  const o = Buffer.alloc(4);
  o.writeUInt32BE(n, 0);
  return o;
 }
 function frame(type: number, channel: number, payload: Buffer): Buffer {
  const o = Buffer.alloc(7 + payload.length + 1);
  o.writeUInt8(type, 0);
  o.writeUInt16BE(channel, 1);
  o.writeUInt32BE(payload.length, 3);
  payload.copy(o, 7);
  o.writeUInt8(FRAME_END, 7 + payload.length);
  return o;
 }
 function method(channel: number, classId: number, methodId: number, ...parts: Buffer[]): Buffer {
  return frame(1, channel, Buffer.concat([u16(classId), u16(methodId), ...parts]));
 }
 interface MethodWaiter {
  classId: number;
  methodId: number;
  resolve: (args: Buffer) => void;
  reject: (e: Error) => void;
 }
 /**
 * Connect, authenticate to the vhost, declare a queue, publish one message and get it back. Returns
 * the body that came back — the caller checks it equals what went out. Throws on any protocol error,
 * including the broker's `NOT_ALLOWED` refusal of a vhost the login has no permission on (the
 * isolation the provider builds, seen from the consumer's side).
 */
 export function roundTrip(conn: AmqpConn, queue = "amqp-ping", payload?: string): Promise<string> {
  const body = Buffer.from(payload ?? `ping-${Date.now()}`);
  return new Promise<string>((resolve, reject) => {
    const sock: Socket = createConnection({ host: conn.host, port: conn.port });
    let buf = Buffer.alloc(0);
    const waiters: MethodWaiter[] = [];
    let lastBody: Buffer | null = null;
    let done = false;
    const fail = (e: Error): void => {
      if (done) return;
      done = true;
      sock.destroy();
      reject(e);
    };
    const expect = (classId: number, methodId: number): Promise<Buffer> =>
      new Promise((res, rej) => waiters.push({ classId, methodId, resolve: res, reject: rej }));
    sock.on("error", (e) => fail(e));
    sock.on("close", () => fail(new Error("amqp connection closed before the round-trip completed")));
    sock.on("data", (chunk: Buffer) => {
      buf = Buffer.concat([buf, chunk]);
      for (;;) {
        if (buf.length < 7) return;
        const type = buf.readUInt8(0);
        const size = buf.readUInt32BE(3);
        if (buf.length < 7 + size + 1) return;
        const framePayload = buf.subarray(7, 7 + size);
        buf = buf.subarray(7 + size + 1);
        if (type === 1) {
          const classId = framePayload.readUInt16BE(0);
          const methodId = framePayload.readUInt16BE(2);
          const args = framePayload.subarray(4);
          const w = waiters.shift();
          if (!w) continue;
          if (w.classId === classId && w.methodId === methodId) w.resolve(args);
          else w.reject(new Error(`expected method ${w.classId}/${w.methodId}, got ${classId}/${methodId}: ${args.toString("utf8")}`));
        } else if (type === 3) {
          lastBody = framePayload; // a content body frame
        }
        // type 2 (content header) and type 8 (heartbeat) need no handling for this round-trip.
      }
    });
    sock.on("connect", () => {
      void (async () => {
        try {
          sock.write(PROTOCOL_HEADER);
          await expect(10, 10); // Connection.Start
          const response = Buffer.concat([
            Buffer.from([0]), Buffer.from(conn.user, "utf8"), Buffer.from([0]), Buffer.from(conn.password, "utf8"),
          ]);
          // Connection.Start-Ok: empty client-properties table, PLAIN, the SASL response, locale.
          sock.write(method(0, 10, 11, u32(0), shortstr("PLAIN"), longstr(response), shortstr("en_US")));
          const tune = await expect(10, 30); // Connection.Tune
          const frameMax = tune.readUInt32BE(2) || 131072;
          sock.write(method(0, 10, 31, u16(tune.readUInt16BE(0)), u32(frameMax), u16(0))); // Tune-Ok, no heartbeat
          sock.write(method(0, 10, 40, shortstr(conn.vhost), shortstr(""), Buffer.from([0]))); // Connection.Open
          await expect(10, 41); // Open-Ok — authenticated and into the vhost
          sock.write(method(1, 20, 10, shortstr(""))); // Channel.Open
          await expect(20, 11);
          // Queue.Declare: reserved, queue, bits(auto-delete=1), empty arguments table.
          sock.write(method(1, 50, 10, u16(0), shortstr(queue), Buffer.from([0b00001000]), u32(0)));
          await expect(50, 11);
          // Basic.Publish to the default exchange, routing-key = queue; then content header + body.
          sock.write(method(1, 60, 40, u16(0), shortstr(""), shortstr(queue), Buffer.from([0])));
          const bodySize = Buffer.alloc(8);
          bodySize.writeBigUInt64BE(BigInt(body.length), 0);
          sock.write(frame(2, 1, Buffer.concat([u16(60), u16(0), bodySize, u16(0)]))); // content header, no properties
          sock.write(frame(3, 1, body)); // content body
          await new Promise((r) => setTimeout(r, 200));
          lastBody = null;
          sock.write(method(1, 60, 70, u16(0), shortstr(queue), Buffer.from([1]))); // Basic.Get, no-ack
          await expect(60, 71); // Get-Ok (a Get-Empty would arrive as 60/72 and reject the expect)
          await new Promise((r) => setTimeout(r, 200));
          const received = lastBody ? (lastBody as Buffer).toString("utf8") : "";
          sock.write(method(0, 10, 50, u16(200), shortstr("bye"), u16(0), u16(0))); // Connection.Close
          await expect(10, 51).catch(() => undefined);
          done = true;
          sock.end();
          resolve(received);
        } catch (e) {
          fail(e instanceof Error ? e : new Error(String(e)));
        }
      })();
    });
  });
 }
 function readMaybe(path: string | undefined): string {
  if (!path) return "";
  try {
    return readFileSync(path, "utf8").replace(/\n$/, "");
  } catch {
    return "";
  }
 }
@@ -1,53 +0,0 @@
 // amqp-ping — a tiny demo consumer of the mesh `amqp` interface, run as a long-lived container by
 // `mesh-tools run` (it never returns, so the container stays up). It exists to PROVE the grant end to
 // end: the mesh gave it a scoped login and a vhost of that name on the lavinmq provider, and this
 // connects with exactly those and round-trips a message.
 //
 // The connection facts arrive the way every consumer's do — the mesh writes them into an env-file the
 // container reads (novox/hq ADR 0048): MESH_AMQP_HOST/PORT from the binding, MESH_AMQP_USER and
 // MESH_AMQP_VHOST both from `${bound:amqp:as}` (the provider named the vhost after the login, so the
 // consumer uses the login for both — the db-name lesson applied to AMQP), and MESH_AMQP_PASSWORD from
 // `${secret:amqp}`.
 //
 // It retries: on first boot the provider may not have provisioned this consumer yet (the reconcile is
 // asynchronous and cross-container), so a refused or unreachable connection is a "not yet", not a
 // failure — it waits and tries again until the round-trip succeeds, then holds the connection idle
 // and re-pings on a slow cadence so the container is a stable, running proof.
 import { connFromEnv, roundTrip } from "./client.js";
 async function sleep(ms: number): Promise<void> {
  await new Promise((r) => setTimeout(r, ms));
 }
 async function pingOnce(): Promise<boolean> {
  try {
    const conn = connFromEnv();
    const sent = `ping-${Date.now()}`;
    const got = await roundTrip(conn, "amqp-ping", sent);
    if (got === sent) {
      console.log(`[amqp-ping] round-trip ok as ${conn.user} on vhost ${conn.vhost} (${conn.host}:${conn.port})`);
      return true;
    }
    console.error(`[amqp-ping] round-trip mismatch: sent ${sent}, got ${got}`);
    return false;
  } catch (err) {
    console.error(`[amqp-ping] not ready yet: ${err instanceof Error ? err.message : err}`);
    return false;
  }
 }
 // Wait for the first successful round-trip — the proof this consumer's grant works — then stay up.
 let first = false;
 for (let i = 0; !first; i++) {
  first = await pingOnce();
  if (!first) await sleep(3000);
 }
 console.log("[amqp-ping] connected and round-tripped; holding steady");
 for (;;) {
  await sleep(30000);
  await pingOnce();
 }
 // changed by the one-node test at build 66e54af151df
 // changed by the one-node test at build 4fb41636cffd
 // changed by the one-node test at build a69f083bf6a6
@@ -1,89 +0,0 @@
 {
  "module": "amqp-ping",
  "slug": "ping",
  "version": "1",
  "capabilities": [
    "container-runtime"
  ],
  "requires": [
    "amqp"
  ],
  "contributes": {},
  "binds": {
    "amqp": "/var/lib/amqp-ping/amqp.json"
  },
  "secrets": {
    "amqp": "/var/lib/amqp-ping/amqp.secret"
  },
  "own-secrets": {
    "broker": "/var/lib/mesh/amqp-ping/broker"
  },
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "path": "/var/lib/mesh/amqp-ping",
      "mode": "0700"
    },
    {
      "id": "state",
      "type": "directory",
      "path": "/var/lib/amqp-ping",
      "mode": "0700"
    },
    {
      "id": "amqp-env",
      "type": "file",
      "path": "/var/lib/amqp-ping/amqp.env",
      "mode": "0600",
      "content": "MESH_AMQP_HOST=${bound:amqp:at}\nMESH_AMQP_PORT=${bound:amqp:port}\nMESH_AMQP_USER=${bound:amqp:as}\nMESH_AMQP_VHOST=${bound:amqp:as}\n"
    },
    {
      "id": "net",
      "type": "network",
      "name": "amqp-ping"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "amqp-ping",
      "network": "amqp-ping",
      "volumes": [
        "/var/lib/mesh/amqp-ping/broker:/run/secrets/broker:ro",
        "/var/lib/amqp-ping/amqp.secret:/run/secrets/amqp:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
        "MESH_AMQP_PASSWORD_FILE": "/run/secrets/amqp"
      },
      "env-file": [
        "/var/lib/amqp-ping/amqp.env"
      ],
      "restart-on": [
        "amqp-env"
      ],
      "artifact": "runtime"
    }
  ],
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
        "name": "runtime",
        "kind": "image",
        "from": "Dockerfile"
      }
    ]
  }
 }
@@ -1,14 +0,0 @@
 {
  "name": "@novox/module-amqp-ping",
  "version": "0.1.0",
  "description": "amqp-ping — a demo consumer of the mesh amqp interface. Connects with its scoped grant and round-trips one message to prove the broker the mesh gave it (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.6.0"
  }
 }
@@ -2,12 +2,15 @@
 // module's tools and anything else baserow-specific import it; nothing outside baserow does.
 //
 // Baserow authenticates a person with email + password, exchanged for a JWT at /api/user/token-auth/.
-// Those credentials are the mesh's own: a person signs up in Baserow (the standard image creates no
+// The standard image creates no admin from env, so the account is one a person made in Baserow: its
-// admin from env), and the credential is placed in the runtime config file the mesh mounts. Until
+// password is the module's `admin` secret, accepted from the operator, and its email and the public
-// that happens fromEnv throws and the module simply exposes no tools — the same dormant-until-
+// host Baserow answers to reach the runtime config file the mesh mounts (the email from the
-// configured shape gitea uses for its token.
+// assignment's settings). Until both are there fromEnv throws and the module exposes no tools — the
 // same dormant-until-configured shape gitea uses for its token.
 import { readFileSync } from "node:fs";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 export interface BaserowApplication {
  id: number;
@@ -68,35 +71,63 @@ export class BaserowClient {
    return h;
  }
-  /** Exchange email + password for a JWT, caching it for the client's lifetime. Handles both the
+  /**
   * One HTTP exchange. Not `fetch`: Node's fetch drops a caller's Host header and sends the URL's
   * own, and Baserow answers only the host of its BASEROW_PUBLIC_URL — any other Host is looked up
   * as a published builder site and gets 404, `/api/_health/` included. A co-located caller reaching
   * it by container name must present the public host, so the request is made with node:http, which
   * sends the Host it is given.
   */
  private send(path: string, method: string, headers: Record<string, string>, body?: string): Promise<{ status: number; text: string }> {
    const url = new URL(`${this.baseUrl}${path}`);
    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
    // A length, never chunked: Baserow's server reads a chunked body as empty.
    const sent = body === undefined ? headers : { ...headers, "Content-Length": String(Buffer.byteLength(body)) };
    return new Promise((resolve, reject) => {
      const req = request(url, { method, headers: sent }, (res) => {
        let text = "";
        res.setEncoding("utf8");
        res.on("data", (chunk: string) => (text += chunk));
        res.on("end", () => resolve({ status: res.statusCode ?? 0, text }));
        res.on("error", reject);
      });
      req.on("error", reject);
      if (body !== undefined) req.write(body);
      req.end();
    });
  }
  /** Exchange email + password for a JWT, caching it until Baserow refuses it. Handles both the
   *  older `{ token }` and the newer `{ access_token }` response shapes. */
  async authenticate(): Promise<string> {
    if (this.token) return this.token;
-    const res = await fetch(`${this.baseUrl}/api/user/token-auth/`, {
+    const res = await this.send(
-      method: "POST",
+      "/api/user/token-auth/",
-      headers: this.headers(),
+      "POST",
-      body: JSON.stringify({ email: this.email, password: this.password }),
+      this.headers(),
-    });
+      JSON.stringify({ email: this.email, password: this.password }),
-    if (!res.ok) throw new Error(`baserow auth failed: ${res.status} ${await res.text()}`);
+    );
-    const data = (await res.json()) as { token?: string; access_token?: string };
+    if (res.status < 200 || res.status >= 300) throw new Error(`baserow auth failed: ${res.status} ${res.text}`);
    const data = JSON.parse(res.text) as { token?: string; access_token?: string };
    const token = data.access_token ?? data.token;
    if (!token) throw new Error("baserow auth returned no token");
    this.token = token;
    return token;
  }
-  private async authed<T>(path: string, options: RequestInit = {}): Promise<T> {
+  /** An authenticated GET. A refused token is dropped and the call made once more with a fresh one:
-    const token = await this.authenticate();
+   *  Baserow's access tokens expire after minutes, and the runtime lives for weeks. */
-    const res = await fetch(`${this.baseUrl}${path}`, {
+  private async authed<T>(path: string): Promise<T> {
-      ...options,
+    for (let attempt = 0; ; attempt++) {
-      headers: this.headers({
+      const token = await this.authenticate();
-        Authorization: `JWT ${token}`,
+      const res = await this.send(path, "GET", this.headers({ Authorization: `JWT ${token}` }));
-        ...(options.headers as Record<string, string> | undefined),
+      if (res.status === 401 && attempt === 0) {
-      }),
+        this.token = null;
-    });
+        continue;
-    if (!res.ok) throw new Error(`baserow ${path}: ${res.status} ${await res.text()}`);
+      }
-    const text = await res.text();
+      if (res.status < 200 || res.status >= 300) throw new Error(`baserow ${path}: ${res.status} ${res.text}`);
-    return (text ? JSON.parse(text) : null) as T;
+      return (res.text ? JSON.parse(res.text) : null) as T;
    }
  }
  /** The applications (databases) the account can see, across all its workspaces. */
@@ -14,26 +14,27 @@
    },
    "route": {
      "label": "baserow",
-      "port": 80
+      "endpoint": "web"
    }
  },
  "binds": {
-    "postgres-database": "/var/lib/baserow/database.json",
+    "postgres-database": "${dir:state}/database.json",
-    "route": "/var/lib/baserow/route.json"
+    "route": "${dir:state}/route.json"
  },
  "secrets": {
-    "postgres-database": "/var/lib/baserow/database.secret"
+    "postgres-database": "${dir:state}/database.secret"
  },
  "own-secrets": {
-    "secret-key": "/var/lib/baserow/secret-key.secret",
+    "admin": "${dir:state}/admin.secret",
    "broker": "/var/lib/mesh/baserow/broker"
  },
  "listens": [
    {
      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the Baserow web UI and REST API; a public name is a route grant later"
+      "why": "the Baserow web UI and REST API, served by the image's own Caddy; a public name is the route's"
    }
  ],
  "resources": [
@@ -46,22 +47,21 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/baserow",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
      "id": "data",
      "type": "directory",
      "path": "/services/baserow/data",
      "mode": "0755",
      "owner": "9999:9999"
    },
    {
      "id": "server-env",
      "type": "file",
-      "path": "/var/lib/baserow/server.env",
+      "path": "${dir:state}/server.env",
      "mode": "0600",
-      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD=${secret:postgres-database}\nSECRET_KEY=${secret:secret-key}\nBASEROW_PUBLIC_URL=http://localhost\n"
+      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD_FILE=/run/secrets/database\nDISABLE_EMBEDDED_PSQL=true\nBASEROW_PUBLIC_URL=https://${bound:route:name}\n"
    },
    {
      "id": "net",
@@ -72,25 +72,25 @@
      "id": "server",
      "type": "container",
      "name": "baserow",
-      "image": "baserow/baserow@sha256:834424a10413798567f76428f255dc259445b7f8dcec56598c05b4073bb2a124",
+      "image": "baserow/baserow@sha256:263ea6c4b72c9eccabcd975ffe9fdebf23913a293a514bec6a3897a5e0a5a080",
      "network": "baserow",
      "env-file": [
-        "/var/lib/baserow/server.env"
+        "${dir:state}/server.env"
      ],
      "ports": [
        "80"
      ],
      "volumes": [
-        "/services/baserow/data:/baserow/data"
+        "${dir:data}:/baserow/data",
-      ],
+        "${dir:state}/database.secret:/run/secrets/database:ro"
-      "secrets-in-environment": "baserow reads DATABASE_PASSWORD and SECRET_KEY with os.getenv and has no _FILE twin (settings/base.py); not convertible"
+      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
      "path": "/var/lib/mesh/baserow/config.json",
      "mode": "0600",
-      "content": "{}\n",
+      "content": "{\n  \"password\": \"${secret:admin}\",\n  \"host\": \"${bound:route:name}\"\n}\n",
      "merge": "json"
    },
    {
@@ -13,6 +13,7 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 6767,
      "protocol": "tcp",
      "from": "mesh",
@@ -110,7 +111,7 @@
  "contributes": {
    "route": {
      "label": "subs",
-      "port": 6767
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -15,6 +15,7 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 8787,
      "protocol": "tcp",
      "from": "mesh",
@@ -87,7 +88,7 @@
  "contributes": {
    "route": {
      "label": "books",
-      "port": 8787
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -69,7 +69,8 @@
        "kind": "image",
        "from": "Dockerfile",
        "context": {
-          "repository": "https://git.novox.be/novox/mesh-controller.git",
+          "seat": "git",
          "repository": "novox/mesh-controller",
          "ref": "main"
        }
      }
@@ -77,7 +78,7 @@
    "on": [
      {
        "arg": "GO_BASE",
-        "image": "golang@sha256:1ae0735f00daffa3aaf1363a5184c0d2dc55c78e3db4ec70241cdac97bf84b59"
+        "image": "golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c"
      },
      {
        "arg": "ALPINE_BASE",
@@ -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"
      ]
    }
  ]
 }
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "de-spiegel",
-      "port": 35621
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -23,10 +23,11 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 35621,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the de-spiegel site and its /contact endpoint over http; the public name de-spiegel.novox.be is a route grant, and route-proxy reaches it on this published port"
+      "why": "the de-spiegel site and its /contact endpoint over http; its public name is a route grant, and route-proxy reaches it on this published port"
    }
  ],
  "resources": [
@@ -60,7 +61,10 @@
      "ports": [
        "35621"
      ],
-      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change"
+      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change",
      "names-on-purpose": {
        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
      }
    }
  ]
 }
@@ -29,6 +29,7 @@
  },
  "listens": [
    {
      "name": "registry",
      "port": 5000,
      "protocol": "tcp",
      "from": "mesh",
@@ -33,7 +33,7 @@
      "type": "file",
      "path": "/etc/fail2ban/jail.local",
      "mode": "0644",
-      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range}\n\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\nbanaction = ufw\nbanaction_allports = iptables-allports\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
+      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range}\n\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
    },
    {
      "id": "jail-sshd",
@@ -42,6 +42,14 @@
      "mode": "0644",
      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 5\n"
    },
    {
      "id": "log",
      "type": "file",
      "path": "/var/log/fail2ban.log",
      "mode": "0640",
      "create-once": true,
      "content": ""
    },
    {
      "id": "jail-recidive",
      "type": "file",
@@ -9,6 +9,8 @@ import { ConfiguredToken, MintedToken, type TokenSource } from "./token.js";
 /** A repository, trimmed to what the mesh cares about. */
 export interface GiteaRepo {
  full_name: string;
  /** The URL a build clones — what a module records as its source. */
  clone_url?: string;
  name: string;
  owner: string;
  private: boolean;
@@ -34,6 +36,9 @@ export interface GiteaPull {
  title: string;
  state: string;
  merged: boolean;
  /** The commit the merge produced — what a build of the base branch is made from. */
  merge_commit_sha?: string;
  merged_at?: string;
  user?: string;
  head?: string;
  base?: string;
@@ -90,6 +95,13 @@ export class GiteaClient {
    if (res.status === 401) {
      token = await this.tokens.renew(token);
      res = await this.send(path, options, token);
    } else if (res.status === 403) {
      // A kept token minted before a scope was added lacks it. The forge says so; the source
      // re-mints with the whole list and the call is retried once. Any other 403 stays a 403.
      const text = await res.text();
      if (!MintedToken.lacksScope(res.status, text)) throw new Error(`Gitea API ${path}: 403 ${text}`);
      token = await this.tokens.renew(token);
      res = await this.send(path, options, token);
    }
    if (!res.ok) throw new Error(`Gitea API ${path}: ${res.status} ${await res.text()}`);
    if (res.status === 204) return null as T;
@@ -116,9 +128,23 @@ export class GiteaClient {
  // ---- Repositories ----
  /** Every repository this token can see, one page. `/user/repos` is only what the token's own
   *  user owns — for the mesh's administrator that is nothing, which is how the forge watched an
   *  empty list and announced no merge (2026-09-28). The search endpoint is the forge's whole view. */
  async listRepos(page = 1, limit = 20): Promise<GiteaRepo[]> {
-    const repos = await this.request<any[]>(`/user/repos?page=${page}&limit=${limit}`);
+    const found = await this.request<{ data?: any[] }>(`/repos/search?page=${page}&limit=${limit}`);
-    return (repos ?? []).map(GiteaClient.mapRepo);
+    return (found?.data ?? []).map(GiteaClient.mapRepo);
  }
  /** Every repository, all pages. */
  async listAllRepos(): Promise<GiteaRepo[]> {
    const all: GiteaRepo[] = [];
    for (let page = 1; page < 100; page++) {
      const batch = await this.listRepos(page, 50);
      all.push(...batch);
      if (batch.length < 50) break;
    }
    return all;
  }
  async createRepo(data: {
@@ -210,6 +236,17 @@ export class GiteaClient {
    return GiteaClient.mapPull(await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`));
  }
  /** The files a merged pull request changed, as paths from the repository's root.
   *
   *  `limit` is what is asked for, and a merge that changed more says so rather than being read
   *  page by page: what the mesh does with a partial list is treat the whole repository as changed,
   *  so more pages would buy nothing. */
  async listPullFiles(owner: string, repo: string, index: number, limit = 100): Promise<{ paths: string[]; truncated: boolean }> {
    const files = await this.request<any[]>(`/repos/${owner}/${repo}/pulls/${index}/files?limit=${limit}`);
    const paths = (files ?? []).map((f) => String(f?.filename ?? "")).filter((p) => p !== "");
    return { paths, truncated: paths.length >= limit };
  }
  async createPullRequest(
    owner: string,
    repo: string,
@@ -232,6 +269,7 @@ export class GiteaClient {
  private static mapRepo(r: any): GiteaRepo {
    return {
      full_name: r.full_name,
      clone_url: r.clone_url ?? undefined,
      name: r.name,
      owner: r.owner?.login ?? r.full_name?.split("/")[0] ?? "unknown",
      private: Boolean(r.private),
@@ -259,6 +297,8 @@ export class GiteaClient {
      title: p.title,
      state: p.state,
      merged: Boolean(p.merged),
      merge_commit_sha: p.merge_commit_sha ?? undefined,
      merged_at: p.merged_at ?? undefined,
      user: p.user?.login,
      head: p.head?.ref,
      base: p.base?.ref,
@@ -31,7 +31,7 @@ try {
 const seen = new Set<string>();
 let primed = false;
 async function pollRepos(client: GiteaClient): Promise<void> {
-  const repos = await client.listRepos(1, 50);
+  const repos = await client.listAllRepos();
  for (const repo of repos) {
    if (!seen.has(repo.full_name)) {
      if (primed) {
@@ -49,6 +49,83 @@ async function pollRepos(client: GiteaClient): Promise<void> {
  primed = true;
 }
 // **A merge is announced whoever made it.** The merge tool below emits at the instant it acts; a
 // merge made in the forge's own pages or over its API would emit nothing, and the mesh would go on
 // believing every module current with its source (novox/hq 04-ISSUES/131). So merged pull requests
 // are watched the way repositories are: what the forge holds, asked for on a tick, announced once.
 // What has been announced is kept beside the module's state, so a restart does not announce the
 // whole history again — and the first tick on a machine with no record announces nothing, because
 // everything it sees then predates the watching.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 const mergedRecord = process.env.MESH_GITEA_STATE_DIR ? join(process.env.MESH_GITEA_STATE_DIR, "merged-announced.json") : null;
 const announced = new Set<string>();
 let primedMerges = false;
 // since is the moment the watching began: a merge made before it is history, whatever page of the
 // forge's listing it surfaces on. Without it, an old merge past the first page — pushed into view
 // as newer pull requests were updated — was announced as if it had just happened, and the mesh
 // rebuilt everything built from that repository, once per old merge (2026-09-28).
 let since = "";
 if (mergedRecord && existsSync(mergedRecord)) {
  try {
    const kept = JSON.parse(readFileSync(mergedRecord, "utf8")) as string[] | { announced: string[]; since: string };
    const list = Array.isArray(kept) ? kept : kept.announced;
    for (const sha of list) announced.add(sha);
    since = Array.isArray(kept) ? new Date().toISOString() : kept.since;
    primedMerges = true;
  } catch {
    // An unreadable record is treated as no record: prime again rather than re-announce history.
  }
 }
 function keepAnnounced(): void {
  if (!mergedRecord) return;
  mkdirSync(join(mergedRecord, ".."), { recursive: true });
  const tmp = mergedRecord + ".tmp";
  writeFileSync(tmp, JSON.stringify({ announced: [...announced].slice(-2000), since }));
  renameSync(tmp, mergedRecord);
 }
 async function pollMerged(client: GiteaClient): Promise<void> {
  const repos = await client.listAllRepos();
  let changed = false;
  for (const repo of repos) {
    const pulls = await client.listPullRequests(repo.owner, repo.name, { state: "closed", sort: "recentupdate", limit: "20" });
    for (const pull of pulls) {
      if (!pull.merged || !pull.merge_commit_sha || announced.has(pull.merge_commit_sha)) continue;
      // Announced only if merged since the watching began; recorded either way, so it is looked
      // at once.
      const fresh = !!pull.merged_at && !!since && pull.merged_at > since;
      if (primedMerges && fresh) {
        // What it changed, asked for only now: a module is rebuilt because a file inside its own
        // directory moved, and without this every module built from a repository is rebuilt for a
        // change to any of them (novox/hq 04-ISSUES/131).
        const changed = await client.listPullFiles(repo.owner, repo.name, pull.number);
        await emit("pull.merged", {
          owner: repo.owner,
          repo: repo.name,
          number: pull.number,
          title: pull.title,
          head: pull.head,
          base: pull.base,
          merge_commit_sha: pull.merge_commit_sha,
          merged_at: pull.merged_at,
          clone_url: repo.clone_url,
          html_url: pull.html_url,
          paths: changed.paths,
          paths_truncated: changed.truncated,
        });
        // Said, because a trigger that fires silently is indistinguishable from one that did not
        // fire (novox/hq 04-ISSUES/131) — this line is how an operator knows the mesh was told.
        console.log(`[gitea] announced merge ${repo.full_name}#${pull.number} (${pull.merge_commit_sha.slice(0, 8)}) into ${pull.base}`);
      }
      announced.add(pull.merge_commit_sha);
      changed = true;
    }
  }
  if (!primedMerges) since = new Date().toISOString();
  if (!primedMerges || changed) keepAnnounced();
  primedMerges = true;
 }
 if (gitea) {
  const client = gitea;
  // A poll that fails says so once, not once a minute: the same reason repeating (the forge not up
@@ -70,5 +147,6 @@ if (gitea) {
    run();
  };
  tick(() => pollRepos(client), 60_000);
-  console.log("[gitea] watching for new repositories");
+  tick(() => pollMerged(client), 30_000);
  console.log("[gitea] watching for new repositories and merged pull requests");
 }
@@ -13,7 +13,7 @@
    "route": {
      "web": {
        "label": "git",
-        "port": 3000
+        "endpoint": "web"
      },
      "internal-api-refused": {
        "label": "git",
@@ -44,12 +44,14 @@
  ],
  "listens": [
    {
      "name": "web",
      "port": 3000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the forge, over http"
    },
    {
      "name": "ssh",
      "port": 22,
      "protocol": "tcp",
      "from": "mesh",
@@ -29,6 +29,7 @@ interface Forge {
  mints: number;
  lastScopes: string[] | null;
  tokens: Map<string, string>;
  scopesOf: Map<string, string[]>;
  admins: Map<string, string>;
  close(): Promise<void>;
 }
@@ -85,6 +86,20 @@ function fakeForge(): Promise<Forge> {
      }
      return json(res, 405, { message: "method not allowed" });
    }
    if (url.pathname === "/api/v1/repos/search") {
      // The client lists through the search endpoint since 2026-09-28 (the forge's whole view);
      // it sits under `repository`, which write:repository covers.
      const h = req.headers.authorization ?? "";
      const value = h.startsWith("token ") ? h.slice(6) : "";
      if (![...forge.tokens.values()].includes(value)) return json(res, 401, { message: "token is required" });
      if (!covers(forge.scopesOf.get(value) ?? [], "read:repository")) {
        return json(res, 403, { message: `token does not have at least one of required scope(s), required=[read:repository]` });
      }
      return json(res, 200, {
        ok: true,
        data: [{ full_name: "novox/hq", name: "hq", owner: { login: "novox" }, private: true, html_url: "http://fake/novox/hq" }],
      });
    }
    if (url.pathname === "/api/v1/user/repos") {
      const h = req.headers.authorization ?? "";
      const value = h.startsWith("token ") ? h.slice(6) : "";
@@ -101,6 +116,21 @@ function fakeForge(): Promise<Forge> {
        { full_name: "novox/hq", name: "hq", owner: { login: "novox" }, private: true, html_url: "http://fake/novox/hq" },
      ]);
    }
    const adminUser = url.pathname.match(/^\/api\/v1\/admin\/users\/([^/]+)$/);
    if (adminUser && req.method === "PATCH") {
      const h = req.headers.authorization ?? "";
      const value = h.startsWith("token ") ? h.slice(6) : "";
      if (![...forge.tokens.values()].includes(value)) return json(res, 401, { message: "token is required" });
      if (!covers(forge.scopesOf.get(value) ?? [], "write:admin")) {
        return json(res, 403, {
          message: `token does not have at least one of required scope(s), required=[write:admin]`,
        });
      }
      const login = decodeURIComponent(adminUser[1]);
      if (login === "untouchable") return json(res, 403, { message: "user untouchable may not be edited" });
      const patch = await body(req);
      return json(res, 200, { login, is_admin: patch?.admin === true });
    }
    return json(res, 404, { message: "no such route in the fake" });
  });
  return new Promise((resolve) => {
@@ -111,6 +141,7 @@ function fakeForge(): Promise<Forge> {
        get mints() { return forge.mints; },
        get lastScopes() { return forge.lastScopes; },
        tokens: forge.tokens,
        scopesOf: forge.scopesOf,
        admins: forge.admins,
        close: () => new Promise((r) => server.close(() => r())),
      });
@@ -152,14 +183,14 @@ function minted(env: NodeJS.ProcessEnv, logs: string[]): GiteaClient {
 const forge = await fakeForge();
 after(() => forge.close());
-test("first start: mints with the admin account, keeps the token at 0600, asks for two scopes only", async () => {
+test("first start: mints with the admin account, keeps the token at 0600, asks for the tools' scopes only", async () => {
  const { env, file, logs } = await delivered(forge);
  const repos = await minted(env, logs).listRepos();
  assert.equal(repos[0]?.full_name, "novox/hq");
  assert.equal(forge.mints, 1);
-  assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user"]);
+  assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user", "write:admin"]);
  assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]);
  const token = forge.tokens.get("mesh-tools")!;
  assert.equal(await readFile(file, "utf8"), token + "\n");
@@ -197,6 +228,34 @@ test("the forge rejects the kept token (its data was restored): minted afresh, o
  assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n"));
 });
 test("a kept token from before write:admin: the forge refuses the admin route for the scope, the token is re-minted with the whole list, and the call goes through", async () => {
  const { env, file, logs } = await delivered(forge);
  const client = minted(env, logs);
  await client.listRepos();
  const before = forge.mints;
  const old = forge.tokens.get("mesh-tools")!;
  forge.scopesOf.set(old, ["write:repository", "write:issue", "read:user"]); // minted by the previous build
  const user = await client.api<{ login: string; is_admin: boolean }>("/admin/users/mesh_novox_builder", {
    method: "PATCH",
    body: JSON.stringify({ admin: true }),
  });
  assert.equal(user.is_admin, true);
  assert.equal(forge.mints, before + 1);
  assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]);
  assert.notEqual(forge.tokens.get("mesh-tools"), old);
  assert.equal(await readFile(file, "utf8"), forge.tokens.get("mesh-tools") + "\n");
  assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n"));
  // A 403 that is not about scopes is the forge's answer, not a reason to mint.
  const again = forge.mints;
  await assert.rejects(
    client.api("/admin/users/untouchable", { method: "PATCH", body: JSON.stringify({ admin: true }) }),
    /403 .*untouchable/,
  );
  assert.equal(forge.mints, again);
 });
 test("the kept file is gone but the forge still holds a token by that name: replaced, not refused", async () => {
  const { env, file, logs } = await delivered(forge);
  await minted(env, logs).listRepos();
@@ -34,15 +34,21 @@ export const TOKEN_NAME = "mesh-tools";
 *                      It sits under the `user` category despite listing repositories, not `repository`
 *                      — confirmed against the running forge (1.27.3), which answered
 *                      `required=[read:user]` to a token carrying only the other two.
- * Nothing under /admin, /orgs or write:user — the escape-hatch tool reaches only what these three cover.
+ *   write:admin      — /admin/users: the forge's own users are the mesh's to settle, such as making
 *                      the builder's login a site admin so every repository the mesh may build is
 *                      clonable (novox/hq 229). Nothing under /orgs or write:user.
 *
 * A token kept from before a scope was added lacks it: the forge answers such a call with
 * `403 token does not have at least one of required scope(s)`, and the client treats that like a
 * 401 — the source re-mints by name, with the whole list, and the call is retried once.
 */
-export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user"];
+export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user", "write:admin"];
 /** Where a client's token comes from, and what to do when the forge says it is wrong. */
 export interface TokenSource {
  /** The token to authenticate with now; minted, read or configured. */
  current(): Promise<string>;
-  /** The forge answered 401 to `rejected`. A fresh token, or a plain error when there is nothing to renew with. */
+  /** The forge answered 401 to `rejected`, or 403 for a scope it lacks. A fresh token, or a plain error when there is nothing to renew with. */
  renew(rejected: string): Promise<string>;
 }
@@ -170,6 +176,11 @@ export class MintedToken implements TokenSource {
    return this.mint("the forge rejected the kept token — minting a fresh one");
  }
  /** What the forge's scoped tokens say when a kept token predates a scope the tools now need. */
  static lacksScope(status: number, body: string): boolean {
    return status === 403 && /required scope/i.test(body);
  }
  /** One mint at a time: concurrent first calls share it, rather than each minting its own. */
  private mint(why: string): Promise<string> {
    if (this.inflight === null) {
@@ -231,6 +231,11 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
        // Read the PR first, so the merged event carries a title and branches, not just a number.
        const pull = await gitea.getPullRequest(owner, repo, number);
        await gitea.mergePullRequest(owner, repo, number, method, deleteBranch);
        // Read it again: the merge commit only exists now, and it is what a build is made from.
        const merged = await gitea.getPullRequest(owner, repo, number);
        // And what it changed, so the mesh rebuilds the modules whose own files moved rather than
        // every module built from the repository (novox/hq 04-ISSUES/131).
        const changed = await gitea.listPullFiles(owner, repo, number);
        await emit("pull.merged", {
          owner,
          repo,
@@ -238,8 +243,12 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
          title: pull.title,
          head: pull.head,
          base: pull.base,
          merge_commit_sha: merged.merge_commit_sha,
          merged_at: merged.merged_at,
          method,
          html_url: pull.html_url,
          paths: changed.paths,
          paths_truncated: changed.truncated,
        });
        return { merged: true, number, method, deleted_branch: deleteBranch };
      },
@@ -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": [
@@ -13,6 +13,7 @@
  ],
  "listens": [
    {
      "name": "web",
      "port": 3000,
      "protocol": "tcp",
      "from": "mesh",
@@ -29,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"
    },
    {
@@ -81,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": [
@@ -91,16 +134,32 @@
    }
  ],
  "requires": [
-    "route"
+    "route",
    "oidc-client",
    "influxdb-api"
  ],
  "contributes": {
    "route": {
      "label": "grafana",
-      "port": 3000
+      "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": [
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "hello",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -19,6 +19,7 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 8123,
      "protocol": "tcp",
      "from": "mesh",
@@ -85,7 +86,7 @@
  "contributes": {
    "route": {
      "label": "home-assistant",
-      "port": 8123
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -1,6 +1,26 @@
 {
  "module": "icecast",
  "version": "1",
  "requires": [
    "route",
    "secret"
  ],
  "contributes": {
    "route": {
      "label": "icecast",
      "endpoint": "stream"
    }
  },
  "binds": {
    "route": "${dir:state}/route.json"
  },
  "secrets": {
    "secret": {
      "source": "${dir:state}/source.secret",
      "admin": "${dir:state}/admin.secret",
      "relay": "${dir:state}/relay.secret"
    }
  },
  "capabilities": [
    "container-runtime"
  ],
@@ -13,10 +33,11 @@
  },
  "listens": [
    {
      "name": "stream",
      "port": 8000,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "streams in from sources and out to listeners"
+      "why": "streams in from sources (HTTP PUT) and out to listeners, plus the status and admin pages; a public name is its route"
    }
  ],
  "resources": [
@@ -29,28 +50,43 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/icecast-module",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
-      "id": "server-env",
+      "id": "logs",
      "type": "directory",
      "mode": "0700",
      "owner": "100:101"
    },
    {
      "id": "server-conf",
      "type": "file",
-      "path": "/var/lib/icecast-module/server.env",
+      "path": "${dir:state}/icecast.xml",
      "mode": "0600",
-      "content": "ICECAST_SOURCE_PASSWORD=${secret:source}\nICECAST_ADMIN_PASSWORD=${secret:admin}\nICECAST_RELAY_PASSWORD=${secret:relay}\nICECAST_ADMIN_USERNAME=admin\n"
+      "content": "<icecast>\n    <!-- Written by the mesh (modules/icecast). Passwords arrive as secrets rendered into this file,\n         never as environment: the image's entrypoint seds ICECAST_* variables into the file only\n         when they are set, and none are. -->\n    <location>Earth</location>\n    <admin>icemaster@localhost</admin>\n    <limits>\n        <clients>100</clients>\n        <sources>2</sources>\n        <queue-size>524288</queue-size>\n        <client-timeout>30</client-timeout>\n        <header-timeout>15</header-timeout>\n        <source-timeout>10</source-timeout>\n        <burst-on-connect>1</burst-on-connect>\n        <burst-size>65535</burst-size>\n    </limits>\n    <authentication>\n        <source-password>${secret:source}</source-password>\n        <relay-password>${secret:relay}</relay-password>\n        <admin-user>admin</admin-user>\n        <admin-password>${secret:admin}</admin-password>\n    </authentication>\n    <!-- The name icecast writes into playlists (.m3u/.xspf: http://<hostname>:<port>/<mount>) and\n         would announce to YP (none configured). A machine's own name belongs to its assignment, and\n         an assignment merges only into JSON; this XML cannot take it, so the neutral default stays. -->\n    <hostname>localhost</hostname>\n    <listen-socket>\n        <port>8000</port>\n    </listen-socket>\n    <http-headers>\n        <header name=\"Access-Control-Allow-Origin\" value=\"*\" />\n    </http-headers>\n    <fileserve>1</fileserve>\n    <paths>\n        <basedir>/usr/share/icecast</basedir>\n        <logdir>/var/log/icecast</logdir>\n        <webroot>/usr/share/icecast/web</webroot>\n        <adminroot>/usr/share/icecast/admin</adminroot>\n        <alias source=\"/\" destination=\"/status.xsl\"/>\n    </paths>\n    <logging>\n        <accesslog>access.log</accesslog>\n        <errorlog>error.log</errorlog>\n        <loglevel>3</loglevel>\n        <logsize>10000</logsize>\n    </logging>\n    <security>\n        <chroot>0</chroot>\n        <!-- Starts as root, reads this 0600 root-owned file, then drops to the image's icecast user\n             (uid 100, group icecast 101) before serving. -->\n        <changeowner>\n            <user>icecast</user>\n            <group>icecast</group>\n        </changeowner>\n    </security>\n</icecast>\n"
    },
    {
      "id": "net",
      "type": "network",
      "name": "icecast"
    },
    {
      "id": "server",
      "type": "container",
      "name": "icecast",
      "image": "infiniteproject/icecast@sha256:cd506cf3dfe31ce05fd37d7e672dbd1213e7255cc93d28ecf5a3b547af4e162c",
-      "env-file": [
+      "network": "icecast",
        "/var/lib/icecast-module/server.env"
      ],
      "ports": [
        "8000"
      ],
-      "secrets-in-environment": "the image seds ICECAST_*_PASSWORD into icecast.xml and has no _FILE; convertible by mounting a generated icecast.xml, not yet done"
+      "volumes": [
        "${dir:state}/icecast.xml:/etc/icecast.xml:ro",
        "${dir:logs}:/var/log/icecast"
      ],
      "restart-on": [
        "server-conf"
      ]
    },
    {
      "id": "runtime-config",
@@ -64,14 +100,14 @@
      "id": "runtime",
      "type": "container",
      "name": "mesh-icecast",
-      "network": "host",
+      "network": "icecast",
      "volumes": [
        "/var/lib/mesh/icecast/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/icecast/config.json:/run/config/config.json:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_ICECAST_URL": "http://127.0.0.1:8000",
+        "MESH_ICECAST_URL": "http://icecast:8000",
        "MESH_ICECAST_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
@@ -100,15 +136,5 @@
        "from": "Dockerfile"
      }
    ]
  },
  "requires": [
    "secret"
  ],
  "secrets": {
    "secret": {
      "source": "/var/lib/icecast-module/source.secret",
      "admin": "/var/lib/icecast-module/admin.secret",
      "relay": "/var/lib/icecast-module/relay.secret"
    }
  }
 }
@@ -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,20 +1,43 @@
 {
  "module": "influxdb",
  "version": "1",
  "provides": [
    {
      "name": "influxdb-api",
      "scope": "mesh"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "own-secrets": {
-    "broker": "/var/lib/mesh/influxdb/broker"
+    "broker": "/var/lib/mesh/influxdb/broker",
    "admin": "${dir:state}/admin.secret",
    "admin-token": "${dir:state}/admin-token.secret"
  },
  "listens": [
    {
      "name": "api",
      "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",
@@ -25,46 +48,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",
@@ -82,13 +109,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"
@@ -96,6 +125,15 @@
      "artifact": "runtime"
    }
  ],
  "requires": [
    "route"
  ],
  "contributes": {
    "route": {
      "label": "influxdb",
      "endpoint": "api"
    }
  },
  "build": {
    "on": [
      {
@@ -116,14 +154,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,11 +17,11 @@
    "route": {
      "site": {
        "label": "invoicing",
-        "port": 80
+        "endpoint": "web"
      },
      "api": {
        "label": "invoicing-api",
-        "port": 9000
+        "endpoint": "api"
      }
    }
  },
@@ -36,12 +36,14 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the invoicing web frontend; a public name is a route grant later"
    },
    {
      "name": "api",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
@@ -85,7 +87,10 @@
      },
      "ports": [
        "80"
-      ]
+      ],
      "names-on-purpose": {
        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
      }
    },
    {
      "id": "api",
@@ -103,7 +108,10 @@
      "ports": [
        "9000"
      ],
-      "secrets-in-environment": "the application's own code reads MONGO_URL and MINIO_SECRET from the environment (invoicing-app server/src/config.js); converting is that repository's change"
+      "secrets-in-environment": "the application's own code reads MONGO_URL and MINIO_SECRET from the environment (invoicing-app server/src/config.js); converting is that repository's change",
      "names-on-purpose": {
        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
      }
    }
  ]
 }
@@ -2,7 +2,8 @@
 // an indexer proxy: it normalises many torrent trackers behind one Torznab surface. This client
 // talks its /api/v2.0 REST API, and only jackett's tools import it.
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 export interface JackettIndexer {
  id: string;
@@ -43,18 +44,36 @@ export class JackettClient {
  /**
   * Build from the module's resolved environment. Jackett's REST API is keyed, so both the URL and
-   * the key must be present — without them there is nothing to talk to, so this throws and the
+   * the key must be present. The key is read from the settings-merged config or MESH_JACKETT_API_KEY,
-   * module contributes no tools rather than failing half-configured.
+   * or, failing those, discovered from Jackett's own ServerConfig.json under MESH_JACKETT_CONFIG_DIR
   * — the file Jackett writes it to, as sonarr/radarr read theirs from config.xml — so a running
   * server needs no key configured by hand and no secret has to be put in an assignment. Without a
   * URL or key there is nothing to talk to, so this throws and the module contributes no tools
   * rather than failing half-configured.
   */
  static fromEnv(env: NodeJS.ProcessEnv = process.env): JackettClient {
    const cfg = meshConfig(env.MESH_JACKETT_CONFIG_FILE);
    const url = cfg.url ?? env.MESH_JACKETT_URL;
-    const apiKey = cfg.apiKey ?? env.MESH_JACKETT_API_KEY;
+    const apiKey = cfg.apiKey ?? env.MESH_JACKETT_API_KEY
      ?? JackettClient.detectApiKey(env.MESH_JACKETT_CONFIG_DIR ?? "/config");
    if (!url) throw new Error("no Jackett URL — set MESH_JACKETT_URL");
-    if (!apiKey) throw new Error("no Jackett API key — set MESH_JACKETT_API_KEY");
+    if (!apiKey) throw new Error("no Jackett API key — set MESH_JACKETT_API_KEY or make the config dir readable");
    return new JackettClient(url, apiKey);
  }
  /** Discover the API key from Jackett's ServerConfig.json (the linuxserver image keeps it at
   *  <config>/Jackett/ServerConfig.json), falling back to null. */
  static detectApiKey(configDir: string): string | null {
    for (const file of [join(configDir, "Jackett", "ServerConfig.json"), join(configDir, "ServerConfig.json")]) {
      if (!existsSync(file)) continue;
      try {
        const key = (JSON.parse(readFileSync(file, "utf8")) as { APIKey?: unknown }).APIKey;
        if (typeof key === "string" && key) return key;
      } catch { /* unreadable or mid-write: try the next, then give up */ }
    }
    return null;
  }
  private async get(path: string, params: Record<string, string> = {}): Promise<any> {
    const url = new URL(`${this.baseUrl}${path}`);
    url.searchParams.set("apikey", this.apiKey);
@@ -64,18 +83,36 @@ export class JackettClient {
    return res.json();
  }
-  /** The configured indexers Jackett proxies. `configured=false` also lists the ones not set up. */
+  /**
   * The configured indexers Jackett proxies. `configured=false` also lists the ones not set up.
   * Read from the Torznab `t=indexers` feed, not /api/v2.0/indexers: that one is the web UI's and
   * wants a login cookie (it answers an API-key request with a redirect), while the Torznab feed is
   * what the key is for. The feed carries no last error, so `lastError` stays unset.
   */
  async getIndexers(configuredOnly = true): Promise<JackettIndexer[]> {
-    const raw = await this.get("/api/v2.0/indexers", { configured: configuredOnly ? "true" : "false" });
+    const url = new URL(`${this.baseUrl}/api/v2.0/indexers/all/results/torznab/api`);
-    const list = Array.isArray(raw) ? raw : [];
+    url.searchParams.set("apikey", this.apiKey);
-    return list.map((i: any) => ({
+    url.searchParams.set("t", "indexers");
-      id: i.id,
+    url.searchParams.set("configured", configuredOnly ? "true" : "false");
-      name: i.name,
+    const res = await fetch(url.toString(), { headers: { Accept: "application/xml" } });
-      type: i.type,
+    if (!res.ok) throw new Error(`Jackett API torznab t=indexers: ${res.status} ${await res.text()}`);
-      configured: i.configured ?? false,
+    const xml = await res.text();
-      siteLink: i.site_link,
+    // Torznab reports failures (a wrong key among them) as 200 with an <error> body.
-      lastError: i.last_error || undefined,
+    const err = xml.match(/<error code="(\d+)" description="([^"]*)"/);
-    }));
+    if (err) throw new Error(`Jackett API torznab t=indexers: error ${err[1]} ${err[2]}`);
    const text = (block: string, tag: string) =>
      block.match(new RegExp(`<${tag}>([^<]*)</${tag}>`))?.[1];
    const out: JackettIndexer[] = [];
    for (const m of xml.matchAll(/<indexer id="([^"]+)" configured="([^"]+)">([\s\S]*?)<\/indexer>/g)) {
      out.push({
        id: m[1],
        name: text(m[3], "title") ?? m[1],
        type: text(m[3], "type") ?? "unknown",
        configured: m[2] === "true",
        siteLink: text(m[3], "link"),
      });
    }
    return out;
  }
  /**
@@ -1,15 +1,29 @@
 {
  "module": "jackett",
  "version": "1",
  "provides": [
    {
      "name": "jackett-api",
      "scope": "mesh"
    }
  ],
  "serves": {
    "jackett-api": {
      "scheme": "http",
      "port": 9117,
      "url-base": ""
    }
  },
  "capabilities": [
    "container-runtime"
  ],
  "listens": [
    {
      "name": "web",
      "port": 9117,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the indexer proxy"
+      "why": "the indexer proxy: its web UI, and the Torznab feeds the *arr apps search through, which other modules reach as jackett-api"
    }
  ],
  "resources": [
@@ -19,10 +33,15 @@
      "path": "/var/lib/mesh/jackett",
      "mode": "0700"
    },
    {
      "id": "state",
      "type": "directory",
      "mode": "0700",
      "place": "."
    },
    {
      "id": "config",
      "type": "directory",
      "path": "/services/jackett/config",
      "mode": "0700",
      "owner": "1000:1000"
    },
@@ -30,7 +49,7 @@
      "id": "server",
      "type": "container",
      "name": "jackett",
-      "image": "lscr.io/linuxserver/jackett@sha256:fd72d42b731ebf750b5de9711127251cf3b3f609419c32083ea8b3b3ee840b77",
+      "image": "lscr.io/linuxserver/jackett@sha256:7b19f4f6ac33d855ca9226600ecbd096ee678f66da28b13a7c09980b035ff583",
      "env": {
        "PUID": "1000",
        "PGID": "1000",
@@ -40,13 +59,13 @@
        "9117"
      ],
      "volumes": [
-        "/services/jackett/config:/config"
+        "${dir:config}:/config"
      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
-      "path": "/var/lib/mesh/jackett/config.json",
+      "path": "${dir:state}/config.json",
      "mode": "0600",
      "content": "{}\n",
      "merge": "json"
@@ -58,12 +77,12 @@
      "network": "host",
      "volumes": [
        "/var/lib/mesh/jackett/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/jackett/config.json:/run/config/config.json:ro",
+        "${dir:state}/config.json:/run/config/config.json:ro",
-        "/services/jackett/config:/var/lib/jackett/config:ro"
+        "${dir:config}:/var/lib/jackett/config:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_JACKETT_URL": "http://127.0.0.1:9117",
+        "MESH_JACKETT_URL": "http://127.0.0.1:${port:9117}",
        "MESH_JACKETT_CONFIG_FILE": "/run/config/config.json",
        "MESH_JACKETT_CONFIG_DIR": "/var/lib/jackett/config"
      },
@@ -82,11 +101,11 @@
  "contributes": {
    "route": {
      "label": "indexers",
-      "port": 9117
+      "endpoint": "web"
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/jackett/route.json"
+    "route": "${dir:state}/route.json"
  },
  "build": {
    "on": [
@@ -9,7 +9,7 @@ export function getJackettTools(jackett: JackettClient): ToolDefinition[] {
  return [
    {
      name: "jackett_indexers",
-      description: "List the indexers Jackett proxies, with their type and any last error.",
+      description: "List the indexers Jackett proxies, with their type and site.",
      input: { all: { type: "boolean", description: "include indexers not yet configured (default false)" } },
      run: async (args) => {
        const indexers = await jackett.getIndexers(!args.all);
@@ -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"
@@ -11,7 +17,7 @@
    },
    "route": {
      "label": "keycloak",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -34,12 +40,26 @@
  ],
  "listens": [
    {
      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
      "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"
@@ -57,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",
@@ -76,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",
@@ -89,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",
@@ -116,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,42 +0,0 @@
 # lavinmq's runtime: the tool runtime, carrying this module's compiled bootstrap, provisioner,
 # tools and event consumer.
 #
 # **Built from this module's own directory and nothing else.** The sdk is in the base image, so
 # nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
 # repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
 # the siblings.
 #
 # Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
 # They are different images on purpose — the first carries a compiler and the second must not, or
 # every running container would carry one it never invokes. The mesh answers both with the copies it
 # holds, because a fingerprint written here would name one particular copy and no other mesh has it
 # (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
 # nobody told stops here and says which module to build first.
 ARG BUILD_BASE
 ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 # Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
 # node_modules — the module is compiled against exactly the sdk it will run against.
 WORKDIR /app/modules/lavinmq
 COPY . .
 # The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
 # symlinks to a launcher that requires its library relatively — resolved away when the base image
 # was assembled.
 #
 # Four entrypoints and a client, because this module is four things: a run-once bootstrap that
 # writes the broker's configuration before it first starts, a provisioner that grants consumers
 # their own vhost and user, a set of tools, and an event consumer.
 RUN node /app/node_modules/typescript/bin/tsc \
      client.ts index.ts bootstrap/index.ts provisioner/index.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/lavinmq/dist /app/modules/lavinmq/dist
 # What the runtime loads from this module in serve mode: its event consumer, its tools, and its
 # provisioner — all three in one process, so the provisioner's reconcile loop runs with the broker
 # connected (novox/hq issues 060/061; the provisioner used to be run as a separate container `args`
 # command, which meant it served no tools and, once, ran nowhere at all). The run-once bootstrap is
 # NOT listed here — it is named in its own container's `args`, because it runs to completion before
 # the broker starts rather than serving. One image, because they are one module and share a client.
 ENV MESH_TOOL_MODULES=/app/modules/lavinmq/dist/index.js,/app/modules/lavinmq/dist/tools/index.js,/app/modules/lavinmq/dist/provisioner/index.js
@@ -1,45 +0,0 @@
 // lavinmq's run-once bootstrap — lavinmq's own code (novox/hq ADR 0039), run once before the broker
 // first starts (ADR 0052). lavinmq's default admin is set at first boot from a config file's
 // `default_password_hash`, and that value is a HASH of the mesh-minted admin password, not the
 // password itself — a form the mesh's plain-secret delivery cannot produce and no `${secret:...}`
 // placeholder can compute. So this step computes it: it reads the admin password the mesh minted and
 // the host unsealed, hashes it the way lavinmq expects (see client.rabbitHash), and writes the config
 // file the broker container reads with `--config`. The host runs it to completion and only then
 // starts the broker the manifest places after it — so the broker's first boot finds a config with an
 // admin it can authenticate, and the provisioner (which reaches the management API as that admin)
 // can do its work.
 //
 // It runs in the module's own runtime image, under the module's own account, as `mesh-tools run`
 // imports it — no broker connection, because writing a config file is an offline operation and there
 // is no broker to reach yet.
 //
 // lavinmq consults `default_user`/`default_password_hash` only on a first boot with an empty data
 // dir; a later boot uses the persisted user database and ignores them. So this seeds the admin once,
 // and a rotation of the admin secret does not re-key an already-initialised broker — the same
 // first-boot-only shape the RabbitMQ-compatible default user has always had.
 import { writeFileSync } from "node:fs";
 import { readFileSync } from "node:fs";
 import { rabbitHash } from "../client.js";
 const adminUser = process.env.MESH_PROVISION_ADMIN_USER ?? process.env.MESH_LAVINMQ_ADMIN_USER ?? "mesh-admin";
 const passwordFile = process.env.MESH_PROVISION_PASSWORD_FILE ?? process.env.MESH_LAVINMQ_ADMIN_PASSWORD_FILE ?? "/run/secrets/default";
 const configOut = process.env.MESH_LAVINMQ_CONFIG_OUT ?? "/var/lib/lavinmq-module/lavinmq.ini";
 const dataDir = process.env.MESH_LAVINMQ_DATA_DIR ?? "/var/lib/lavinmq";
 const password = readFileSync(passwordFile, "utf8").replace(/\n$/, "");
 if (!password) {
  throw new Error(`[lavinmq:bootstrap] admin password file ${passwordFile} is empty — cannot seed the admin`);
 }
 // The broker reads only what it needs to authenticate its admin on first boot; bind/ports come from
 // the container's entrypoint (`-b 0.0.0.0`), so this file names the admin and nothing else about the
 // network.
 const ini =
  "[main]\n" +
  `data_dir = ${dataDir}\n` +
  `default_user = ${adminUser}\n` +
  `default_password_hash = ${rabbitHash(password)}\n`;
 writeFileSync(configOut, ini, { mode: 0o600 });
 console.log(`[lavinmq:bootstrap] wrote ${configOut} with admin '${adminUser}' (password hashed for lavinmq)`);
@@ -1,183 +0,0 @@
 // lavinmq's admin client — lavinmq's own code, living in the module (novox/hq ADR 0039). Both this
 // module's tools and its provisioner import it, and nothing outside lavinmq does.
 //
 // It drives lavinmq through its HTTP management API (the RabbitMQ-compatible surface lavinmq serves
 // on 15672), not a hand-rolled AMQP admin stack: the module may take NO npm dependency beyond
 // @novox/mesh-sdk, and the management API is exactly the admin surface — create/remove a vhost, a
 // user, and its permissions — reached with `fetch` (global on node 22) and HTTP Basic auth. One
 // boundary, `api()`, and every method is built on it. This is the module's one impure seam, the way
 // postgres's is `psql` and redis's is a RESP socket.
 //
 // **The login and password are the mesh's, not the provisioner's (novox/hq ADR 0048).** The mesh
 // derives the login and hands it to both ends so they agree, and mints the password and delivers a
 // copy to each. lavinmq creates exactly that user with exactly that password on a vhost of the same
 // name — a name or password the provisioner invented is one the consumer could never present.
 import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 export interface LavinmqConn {
  /** Base URL of the management API, e.g. http://lavinmq:15672 (no trailing /api). */
  readonly base: string;
  readonly adminUser: string;
  readonly adminPassword: string;
 }
 export class LavinmqClient {
  constructor(private readonly conn: LavinmqConn) {}
  /**
   * Build from the module's resolved environment. Reads MESH_LAVINMQ_* first (the documented
   * names), falling back to the MESH_PROVISION_* keys the manifest already sets on the provisioner
   * container so the module runs unchanged there. Throws if it cannot find a management endpoint and
   * an admin password — the right failure, because without them nothing it does can work.
   */
  static fromEnv(env: NodeJS.ProcessEnv = process.env): LavinmqClient {
    const base = (env.MESH_LAVINMQ_MANAGEMENT ?? env.MESH_PROVISION_LAVINMQ ?? "").replace(/\/+$/, "");
    const adminUser = env.MESH_LAVINMQ_ADMIN_USER ?? env.MESH_PROVISION_ADMIN_USER ?? "mesh-admin";
    const adminPassword = env.MESH_LAVINMQ_ADMIN_PASSWORD ?? readSecretFile(env.MESH_PROVISION_PASSWORD_FILE);
    if (!base || !adminPassword) {
      throw new Error("lavinmq management endpoint or admin password is not set — lavinmq's own code cannot reach the server");
    }
    return new LavinmqClient({ base, adminUser, adminPassword });
  }
  /** One request against the management API. A non-2xx reply rejects, carrying the body for the log. */
  async api(method: string, path: string, body?: unknown): Promise<unknown> {
    const headers: Record<string, string> = {
      Authorization: "Basic " + Buffer.from(`${this.conn.adminUser}:${this.conn.adminPassword}`).toString("base64"),
    };
    if (body !== undefined) headers["Content-Type"] = "application/json";
    const resp = await fetch(`${this.conn.base}/api${path}`, {
      method,
      headers,
      body: body !== undefined ? JSON.stringify(body) : undefined,
    });
    if (!resp.ok) {
      throw new Error(`lavinmq management API ${method} ${path} -> ${resp.status}: ${await resp.text()}`);
    }
    const text = await resp.text();
    return text ? JSON.parse(text) : null;
  }
  /** True once the management API answers — the server has finished starting. */
  async ready(): Promise<boolean> {
    try {
      await this.api("GET", "/overview");
      return true;
    } catch {
      return false;
    }
  }
  /** Block until the management API answers, or throw once the budget is spent. */
  async waitReady(retries = 30, delayMs = 1000): Promise<void> {
    for (let i = 0; i < retries; i++) {
      if (await this.ready()) return;
      await new Promise((r) => setTimeout(r, delayMs));
    }
    throw new Error("lavinmq management API did not become ready");
  }
  /**
   * Create (or reset to a known state) one consumer's broker: a vhost and a user both named for the
   * consumer's login, with the login owning full permissions on exactly that vhost. Idempotent — a
   * PUT of a vhost or user that exists is a no-op or a password reset, so a reconcile can call it
   * again without harm. The consumer connects as `<login>` to vhost `<login>` and can reach nothing
   * else (novox/hq ADR 0048).
   */
  async createConsumer(login: string, password: string): Promise<void> {
    const v = encodeURIComponent(login);
    const u = encodeURIComponent(login);
    await this.api("PUT", `/vhosts/${v}`);
    await this.api("PUT", `/users/${u}`, { password, tags: "" });
    await this.api("PUT", `/permissions/${v}/${u}`, { configure: ".*", write: ".*", read: ".*" });
  }
  /**
   * Whether a consumer's user exists with exactly this password and full permissions on its own
   * vhost. Read-only: the stored hash is salted SHA-256, the scheme `rabbitHash` writes, so the
   * password is checked by hashing it with the stored salt rather than by logging in. `false` when
   * the user or its permission is gone or the password differs; an unreachable API rejects
   * (novox/hq issue 120).
   */
  async holdsConsumer(login: string, password: string): Promise<boolean> {
    const v = encodeURIComponent(login);
    const u = encodeURIComponent(login);
    const user = await this.getOrNull<{ password_hash?: string; hashing_algorithm?: string }>(`/users/${u}`);
    if (!user?.password_hash) return false;
    if (user.hashing_algorithm && !/sha256/i.test(user.hashing_algorithm)) {
      throw new Error(`lavinmq user ${login} is hashed with ${user.hashing_algorithm}, which this check cannot verify`);
    }
    const stored = Buffer.from(user.password_hash, "base64");
    if (stored.length < 5 || rabbitHash(password, stored.subarray(0, 4)) !== user.password_hash) return false;
    const perm = await this.getOrNull<{ configure?: string; write?: string; read?: string }>(`/permissions/${v}/${u}`);
    return perm?.configure === ".*" && perm?.write === ".*" && perm?.read === ".*";
  }
  /** A GET that answers null for a 404 and rejects on anything else that is not 2xx. */
  private async getOrNull<T>(path: string): Promise<T | null> {
    const resp = await fetch(`${this.conn.base}/api${path}`, {
      headers: {
        Authorization: "Basic " + Buffer.from(`${this.conn.adminUser}:${this.conn.adminPassword}`).toString("base64"),
      },
    });
    if (resp.status === 404) return null;
    if (!resp.ok) throw new Error(`lavinmq management API GET ${path} -> ${resp.status}: ${await resp.text()}`);
    return (await resp.json()) as T;
  }
  /** Remove a consumer's vhost and user, idempotently. A DELETE of what is already gone is tolerated. */
  async removeConsumer(login: string): Promise<void> {
    const v = encodeURIComponent(login);
    const u = encodeURIComponent(login);
    try {
      await this.api("DELETE", `/vhosts/${v}`);
    } catch (err) {
      console.error(`[lavinmq] delete vhost ${login} failed (continuing): ${err}`);
    }
    try {
      await this.api("DELETE", `/users/${u}`);
    } catch (err) {
      console.error(`[lavinmq] delete user ${login} failed (continuing): ${err}`);
    }
  }
  /** The vhosts, for the amqp_list_vhosts tool. */
  async listVhosts(): Promise<{ name: string; messages: number }[]> {
    const vhosts = (await this.api("GET", "/vhosts")) as { name: string; messages?: number }[];
    return vhosts.map((v) => ({ name: v.name, messages: v.messages ?? 0 }));
  }
  /** The queues on one vhost (default the root vhost), for the amqp_list_queues tool. */
  async listQueues(vhost = "/"): Promise<{ name: string; messages: number; consumers: number }[]> {
    const queues = (await this.api("GET", `/queues/${encodeURIComponent(vhost)}`)) as
      { name: string; messages?: number; consumers?: number }[];
    return queues.map((q) => ({ name: q.name, messages: q.messages ?? 0, consumers: q.consumers ?? 0 }));
  }
 }
 /**
 * The RabbitMQ-compatible SHA-256 password hash lavinmq's `default_password_hash` expects:
 * base64( salt[4] || sha256( salt || utf8(password) ) ). The salt is any four bytes — random here,
 * because a fixed salt buys nothing and a fresh one is free. Verified against `lavinmqctl
 * hash_password`: a hash produced here is accepted by the server unchanged.
 */
 export function rabbitHash(password: string, salt: Buffer = randomBytes(4)): string {
  const digest = createHash("sha256").update(Buffer.concat([salt, Buffer.from(password, "utf8")])).digest();
  return Buffer.concat([salt, digest]).toString("base64");
 }
 /** Generate a URL-safe password. */
 export function generatePassword(): string {
  return randomBytes(24).toString("base64url");
 }
 function readSecretFile(path: string | undefined): string | undefined {
  if (!path) return undefined;
  try {
    return readFileSync(path, "utf8").trim();
  } catch {
    return undefined;
  }
 }
@@ -1,25 +0,0 @@
 // lavinmq's events entrypoint, loaded by the per-node tool host (the provisioner container runs
 // ./provisioner separately). The broker lifecycle events are EMITTED from the provisioner, where the
 // lifecycle actually happens (novox/hq ADR 0041/0042):
 //   module.lavinmq.amqp.provisioned    — a consumer's vhost + user was created
 //   module.lavinmq.amqp.deprovisioned  — that vhost + user was removed
 // Here in the tool host we react to them, keeping a lightweight audit trail of who was granted a
 // broker and who lost one — observability the provider itself is best placed to log.
 import { on } from "@novox/mesh-sdk/events";
 interface AmqpEvent {
  consumer?: string;
  user: string;
  vhost?: string;
 }
 await on<AmqpEvent>("amqp.provisioned", async (e) => {
  console.log(`[lavinmq] broker provisioned for ${e.body.consumer ?? "?"} (user ${e.body.user}, vhost ${e.body.vhost})`);
 });
 await on<AmqpEvent>("amqp.deprovisioned", async (e) => {
  console.log(`[lavinmq] broker deprovisioned (user ${e.body.user})`);
 });
 console.log("[lavinmq] auditing broker lifecycle events");
@@ -1,145 +0,0 @@
 {
  "module": "lavinmq",
  "version": "1",
  "provides": [
    {
      "name": "amqp",
      "scope": "mesh"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "emits": [
    "amqp.provisioned",
    "amqp.deprovisioned"
  ],
  "consumes": [
    "lavinmq.amqp.provisioned",
    "lavinmq.amqp.deprovisioned"
  ],
  "serves": {
    "amqp": {
      "port": 5672
    }
  },
  "receives": {
    "amqp": "/var/lib/lavinmq-module/grants/mesh.json"
  },
  "grants": {
    "amqp": "/var/lib/lavinmq-module/grants"
  },
  "own-secrets": {
    "admin": "/var/lib/lavinmq-module/admin.secret",
    "broker": "/var/lib/mesh/lavinmq/broker"
  },
  "listens": [
    {
      "port": 5671,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the mesh bus \u2014 amqps, every module's events and the control plane, reached over the overlay"
    },
    {
      "port": 5672,
      "protocol": "tcp",
      "from": "mesh",
      "why": "modules on any machine that were granted a queue"
    }
  ],
  "guards": [
    15672
  ],
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "path": "/var/lib/mesh/lavinmq",
      "mode": "0700"
    },
    {
      "id": "state",
      "type": "directory",
      "path": "/var/lib/lavinmq-module",
      "mode": "0700"
    },
    {
      "id": "grants-dir",
      "type": "directory",
      "path": "/var/lib/lavinmq-module/grants",
      "mode": "0700"
    },
    {
      "id": "broker-data",
      "type": "directory",
      "path": "/var/lib/mesh-broker",
      "mode": "0700"
    },
    {
      "id": "server",
      "type": "container",
      "name": "mesh-broker",
      "image": "cloudamqp/lavinmq@sha256:3eb54c12916d700a978c2ea86e6362cd4974b0e3189508718006d4e6d341246b",
      "ports": [
        "5671:5671",
        "5672:5672",
        "127.0.0.1:15672:15672"
      ],
      "volumes": [
        "/var/lib/mesh-broker:/var/lib/lavinmq",
        "/var/lib/mesh-broker-tls:/tls:ro"
      ],
      "args": [
        "--amqps-port=5671",
        "--cert=/tls/tls.crt",
        "--key=/tls/tls.key"
      ]
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-lavinmq",
      "artifact": "runtime",
      "network": "host",
      "volumes": [
        "/var/lib/mesh/lavinmq/broker:/run/secrets/broker:ro",
        "/var/lib/lavinmq-module/grants:/var/lib/lavinmq-module/grants:ro",
        "/var/lib/lavinmq-module/admin.secret:/run/secrets/admin:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
        "MESH_RECEIVES": "/var/lib/lavinmq-module/grants/mesh.json",
        "MESH_PROVISION_LAVINMQ": "http://127.0.0.1:15672",
        "MESH_PROVISION_ADMIN_USER": "guest",
        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/admin"
      }
    }
  ],
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
        "name": "runtime",
        "kind": "image",
        "from": "Dockerfile"
      }
    ]
  },
  "accesses": [
    {
      "path": "/var/lib/mesh-broker-tls",
      "mode": "read"
    }
  ]
 }
@@ -1,14 +0,0 @@
 {
  "name": "@novox/module-lavinmq",
  "version": "0.1.0",
  "description": "lavinmq — provides the mesh amqp interface (a per-consumer AMQP message broker). Its management client, provisioner, run-once bootstrap, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.1"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.6.0"
  }
 }
@@ -1,56 +0,0 @@
 // lavinmq's provisioner — the adapter that makes lavinmq a provider of the mesh `amqp` interface.
 // The reconcile loop, the contributions file, and reading the mesh's minted password are the sdk
 // harness's; this writes only the per-service half: how lavinmq creates and removes a consumer's own
 // broker (novox/hq ADR 0039/0040/0048).
 //
 // The `amqp` interface: a consumer connects as `as` with the password the mesh minted, to a vhost
 // named for that same login — its own message broker, isolated from every other consumer's by the
 // vhost boundary. It is a broker of its own, not a shared account on the mesh's control-plane broker.
 //
 // **The login and password are the mesh's, not the provisioner's (novox/hq ADR 0048).** The mesh
 // derives the login and hands it to both ends so they agree, and mints the password and delivers a
 // copy to each. lavinmq creates exactly that user with exactly that password — a name or password the
 // provisioner invented is one the consumer could never present.
 //
 // Vhost-per-login is the isolation model, the exact analog of postgres's database-per-login: the
 // consumer owns one vhost, named for its login, and a user with full rights on that vhost and no
 // rights anywhere else. lavinmq enforces it — a user with no permission on `/` is refused the moment
 // it opens that vhost (`NOT_ALLOWED`), so a login is a broker the consumer alone can reach.
 import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
 import { emit } from "@novox/mesh-sdk/events";
 import { LavinmqClient } from "../client.js";
 const lavinmq = LavinmqClient.fromEnv();
 /** 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:amqp] emit ${type} failed: ${err}`);
  }
 }
 runProvisioner("amqp", {
  async create(p: Provision): Promise<void> {
    // The vhost and the user share the consumer's login, so one cannot reach another's broker.
    await lavinmq.waitReady();
    await lavinmq.createConsumer(p.as, p.password);
    await announce("amqp.provisioned", {
      consumer: p.consumer ?? "",
      user: p.as,
      vhost: p.as,
    });
  },
  async remove(p: { as: string }): Promise<void> {
    await lavinmq.removeConsumer(p.as);
    await announce("amqp.deprovisioned", { user: p.as, vhost: p.as });
  },
  // Asked every minute by the harness: whether the backend still holds this consumer exactly as
  // the mesh gave it, so a login lost behind the provisioner's back is made again (novox/hq issue 120).
  async holds(p: Provision): Promise<boolean> {
    return lavinmq.holdsConsumer(p.as, p.password);
  },
 });
@@ -1,32 +0,0 @@
 // lavinmq's tools — lavinmq's own code (novox/hq ADR 0039), importing lavinmq's own management
 // client. They return structured data; the mesh serves them through the sdk's tool harness.
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { LavinmqClient } from "../client.js";
 export function getLavinmqTools(lavinmq: LavinmqClient): ToolDefinition[] {
  return [
    {
      name: "amqp_list_vhosts",
      description: "List the lavinmq virtual hosts — one per consumer that was granted a broker.",
      input: {},
      run: async () => ({ vhosts: await lavinmq.listVhosts() }),
    },
    {
      name: "amqp_list_queues",
      description: "List the queues on a vhost with message and consumer counts. Omit vhost for the root '/'.",
      input: { vhost: { type: "string", description: "the vhost to list, e.g. a consumer's login; defaults to '/'" } },
      run: async (args) => ({ queues: await lavinmq.listQueues(args.vhost ? String(args.vhost) : undefined) }),
    },
  ];
 }
 // The tools exist only when the server can be reached from the environment; without it, lavinmq
 // contributes none rather than failing the whole tool runtime.
 registerModuleTools("lavinmq", (env) => {
  try {
    return getLavinmqTools(LavinmqClient.fromEnv(env));
  } catch {
    return [];
  }
 });
@@ -1,12 +0,0 @@
 {
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["client.ts", "index.ts", "provisioner/index.ts", "tools/index.ts", "bootstrap/index.ts"]
 }
@@ -1,10 +1,10 @@
 // The Letta API client — letta's own code, living in the module (novox/hq ADR 0039). Its tools
 // import it; nothing outside letta does.
 //
-// Letta authenticates with a single server password, presented as a Bearer token. That password is
+// Letta authenticates with a single server password. That password is a mesh own-secret handed to
-// a mesh own-secret, minted once and handed to both the server (LETTA_SERVER_PASSWORD) and this
+// both the server (LETTA_SERVER_PASSWORD) and this client, through the runtime config file the mesh
-// client (MESH_LETTA_PASSWORD) — so the module's tools are live without anything configured by hand.
+// mounts (its `password` key) — so the module's tools are live without anything configured by hand.
-// The runtime config file may still override the URL or password.
+// Where a server already has clients, the password is accepted rather than minted.
 import { readFileSync } from "node:fs";
@@ -58,6 +58,10 @@ export class LettaClient {
      ...options,
      headers: {
        "Content-Type": "application/json",
        // The server's --secure mode checks X-BARE-PASSWORD ("password <it>") and answers a Bearer
        // token alone with 401 (letta/server/rest_api/app.py, 0.6.x). Both are sent: Bearer is what
        // later servers read.
        "X-BARE-PASSWORD": `password ${this.password}`,
        Authorization: `Bearer ${this.password}`,
        ...(options.headers as Record<string, string> | undefined),
      },
@@ -5,29 +5,37 @@
    "container-runtime"
  ],
  "requires": [
-    "postgres-database"
+    "postgres-database",
    "route"
  ],
  "contributes": {
    "postgres-database": {
      "name": "letta"
    },
    "route": {
      "label": "letta",
      "endpoint": "web"
    }
  },
  "binds": {
-    "postgres-database": "/var/lib/letta/database.json"
+    "postgres-database": "${dir:state}/database.json",
    "route": "${dir:state}/route.json"
  },
  "secrets": {
-    "postgres-database": "/var/lib/letta/database.secret"
+    "postgres-database": "${dir:state}/database.secret"
  },
  "own-secrets": {
-    "server-password": "/var/lib/letta/server-password.secret",
+    "server-password": "${dir:state}/server-password.secret",
    "openai-api-key": "${dir:state}/openai-api-key.secret",
    "broker": "/var/lib/mesh/letta/broker"
  },
  "listens": [
    {
      "name": "web",
      "port": 8283,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the Letta agent server REST API and web UI; a public name is a route grant later"
+      "why": "the Letta agent server REST API and web UI, password-protected (--secure); a public name is the route's"
    }
  ],
  "resources": [
@@ -40,15 +48,15 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/letta",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
      "id": "server-env",
      "type": "file",
-      "path": "/var/lib/letta/server.env",
+      "path": "${dir:state}/server.env",
      "mode": "0600",
-      "content": "LETTA_PG_URI=postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\nLETTA_SERVER_PASSWORD=${secret:server-password}\nSECURE=true\nTZ=Europe/Brussels\n"
+      "content": "LETTA_PG_URI=postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\nLETTA_SERVER_PASSWORD=${secret:server-password}\nOPENAI_API_KEY=${secret:openai-api-key}\nSECURE=true\nTZ=Europe/Brussels\n"
    },
    {
      "id": "net",
@@ -59,31 +67,24 @@
      "id": "server",
      "type": "container",
      "name": "letta",
-      "image": "letta/letta@sha256:1d2e0692514287c5ed1a483e14e16ed945f8632d315539f5e66373bb7d7c471b",
+      "image": "letta/letta@sha256:bfd1e49ce45b9a208c941e832c1d1d194017ff210a3784b0ca6c323aed767a29",
      "network": "letta",
      "env-file": [
-        "/var/lib/letta/server.env"
+        "${dir:state}/server.env"
      ],
      "ports": [
        "8283"
      ],
-      "secrets-in-environment": "the letta image is env-driven and its file-source support could not be verified; the mesh runtime can take its password from config.json (client.ts) \u2014 not yet converted"
+      "secrets-in-environment": "letta 0.6.x reads its settings from the environment only (pydantic settings, no secrets_dir or _FILE twin), and its startup.sh starts an embedded PostgreSQL unless LETTA_PG_URI is set - so the database password travels inside that URI (startup.sh also echoes it to the log); LETTA_SERVER_PASSWORD and OPENAI_API_KEY have no file source either"
    },
    {
      "id": "runtime-config",
      "type": "file",
      "path": "/var/lib/mesh/letta/config.json",
      "mode": "0600",
-      "content": "{}\n",
+      "content": "{\n  \"password\": \"${secret:server-password}\"\n}\n",
      "merge": "json"
    },
    {
      "id": "runtime-env",
      "type": "file",
      "path": "/var/lib/letta/runtime.env",
      "mode": "0600",
      "content": "MESH_LETTA_PASSWORD=${secret:server-password}\n"
    },
    {
      "id": "runtime",
      "type": "container",
@@ -98,14 +99,10 @@
        "MESH_LETTA_URL": "http://letta:8283",
        "MESH_LETTA_CONFIG_FILE": "/run/config/config.json"
      },
      "env-file": [
        "/var/lib/letta/runtime.env"
      ],
      "restart-on": [
        "runtime-config"
      ],
-      "artifact": "runtime",
+      "artifact": "runtime"
      "secrets-in-environment": "the letta image is env-driven and its file-source support could not be verified; the mesh runtime can take its password from config.json (client.ts) \u2014 not yet converted"
    }
  ],
  "build": {
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 8686,
      "protocol": "tcp",
      "from": "mesh",
@@ -86,7 +87,7 @@
  "contributes": {
    "route": {
      "label": "lidarr",
-      "port": 8686
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -0,0 +1,17 @@
 # mailu
 Mail — Mailu, with its provisioner (the `smtp` provision) and tools, on the tool runtime.
 ## Settings
 A definition names no mesh (novox/hq ADR 0112, ADR 0155), so the values that are this
 installation's are settings on the assignment, `settings set mailu <file>`:
 ```json
 {"domain": "…", "sitename": "…", "website": "https://…", "proxy-address": "…"}
 ```
 `domain` is the mail domain (also the provisioner's, for a consumer's address); `sitename` and
 `website` are shown by the web front; `proxy-address` is what `REAL_IP_FROM` trusts a real-IP
 header from — the address the proxy forwards with. The front's own hostname is the name of its
 `web` route, told to it by the mesh.
@@ -16,27 +16,27 @@
    "route": {
      "web": {
        "label": "mail",
-        "port": 7443,
+        "endpoint": "web-tls",
        "scheme": "https",
        "insecure": true
      },
      "acme": {
        "label": "mail",
        "path": "/.well-known/acme-challenge",
-        "port": 7080,
+        "endpoint": "web",
        "priority": 100
      },
      "autoconfig": {
        "label": "autoconfig",
-        "port": 4243
+        "endpoint": "autoconfig"
      },
      "autodiscover": {
        "label": "autodiscover",
-        "port": 4243
+        "endpoint": "autoconfig"
      },
      "automx": {
        "label": "automx",
-        "port": 4243
+        "endpoint": "autoconfig"
      }
    }
  },
@@ -60,6 +60,7 @@
  ],
  "listens": [
    {
      "name": "smtp",
      "port": 25,
      "protocol": "tcp",
      "from": "anywhere",
@@ -67,6 +68,7 @@
      "fixed": true
    },
    {
      "name": "pop3",
      "port": 110,
      "protocol": "tcp",
      "from": "anywhere",
@@ -74,6 +76,7 @@
      "fixed": true
    },
    {
      "name": "imap",
      "port": 143,
      "protocol": "tcp",
      "from": "anywhere",
@@ -81,6 +84,7 @@
      "fixed": true
    },
    {
      "name": "smtps",
      "port": 465,
      "protocol": "tcp",
      "from": "anywhere",
@@ -88,6 +92,7 @@
      "fixed": true
    },
    {
      "name": "submission",
      "port": 587,
      "protocol": "tcp",
      "from": "anywhere",
@@ -95,6 +100,7 @@
      "fixed": true
    },
    {
      "name": "imaps",
      "port": 993,
      "protocol": "tcp",
      "from": "anywhere",
@@ -102,6 +108,7 @@
      "fixed": true
    },
    {
      "name": "pop3s",
      "port": 995,
      "protocol": "tcp",
      "from": "anywhere",
@@ -109,22 +116,25 @@
      "fixed": true
    },
    {
      "name": "web",
      "port": 7080,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the web front over http; only the ACME HTTP-01 passthrough is routed here \u2014 everything else 301s to https and would loop a proxy"
+      "why": "the web front over http; only the ACME HTTP-01 passthrough is routed here — everything else 301s to https and would loop a proxy"
    },
    {
      "name": "web-tls",
      "port": 7443,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the web front over its own TLS (admin, webmail, API); the public name mail.novox.be is a route grant reaching it here"
+      "why": "the web front over its own TLS (admin, webmail, API); its public name is a route grant reaching it here"
    },
    {
      "name": "autoconfig",
      "port": 4243,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "automx: mail client autoconfiguration; autoconfig/autodiscover/automx.novox.be are route grants reaching it here"
+      "why": "automx: mail client autoconfiguration; the autoconfig, autodiscover and automx names are route grants reaching it here"
    }
  ],
  "own-secrets": {
@@ -158,7 +168,7 @@
      "type": "file",
      "path": "${dir:state}/mailu.env",
      "mode": "0644",
-      "content": "ADMIN_ADDRESS=mailu-admin\nANTISPAM_ADDRESS=mailu-antispam\nANTIVIRUS_ADDRESS=mailu-antivirus\nIMAP_ADDRESS=mailu-imap\nSMTP_ADDRESS=mailu-smtp\nFRONT_ADDRESS=mailu-front\nWEBMAIL_ADDRESS=mailu-webmail\nWEBDAV_ADDRESS=mailu-webdav\nREDIS_ADDRESS=mailu-redis\nPORTS=25,80,443,465,993,995,4190,110,143,587\nDOMAIN=novox.be\nHOSTNAMES=mail.novox.be\nPOSTMASTER=admin\nSITENAME=Novox\nWEBSITE=https://novox.be\nTLS_FLAVOR=letsencrypt\nSUBNET=192.168.203.0/24\nCOMPOSE_PROJECT_NAME=mailu\nANTIVIRUS=clamav\nWEBMAIL=roundcube\nWEBDAV=radicale\nFETCHMAIL_ENABLED=True\nFETCHMAIL_DELAY=600\nADMIN=true\nWEB_ADMIN=/admin\nWEB_WEBMAIL=/webmail\nWEBROOT_REDIRECT=/webmail\nAPI=true\nWEB_API=/api\nAUTH_RATELIMIT_IP=6000/hour\nAUTH_RATELIMIT_USER=1000/day\nCREDENTIAL_ROUNDS=12\nPASSWORD_SCHEME=PBKDF2\nDISABLE_STATISTICS=True\nMESSAGE_SIZE_LIMIT=50000000\nMESSAGE_RATELIMIT=200/day\nRECIPIENT_DELIMITER=+\nPOSTFIX_MYNETWORKS=127.0.0.0/8 [::1]/128\nRELAYNETS=\nRELAYHOST=\nREJECT_UNLISTED_RECIPIENT=\nDB_FLAVOR=postgresql\nINITIAL_ADMIN_ACCOUNT=admin\nINITIAL_ADMIN_DOMAIN=novox.be\nINITIAL_ADMIN_MODE=ifmissing\nSMTP_PORT=25\nSMTPS_PORT=465\nSUBMISSION_PORT=587\nPOP3_PORT=110\nPOP3S_PORT=995\nIMAP_PORT=143\nIMAPS_PORT=993\nHTTP_PORT=7080\nHTTPS_PORT=7443\nAUTOMX_PORT=4243\nAMX_SMTP_ADDRESS=mail.novox.be\nAMX_SMTP_PORT=587\nAMX_IMAP_ADDRESS=mail.novox.be\nAMX_IMAP_PORT=143\nAMX_MAIL_DOMAINS=novox.be\nDMARC_RUA=admin\nDMARC_RUF=admin\nLETSENCRYPT_SHORTCHAIN=True\nTZ=Etc/UTC\nLOG_LEVEL=INFO\nWELCOME=false\nREAL_IP_HEADER=X-Real-IP\nREAL_IP_FROM=142.132.152.141\nCOMPRESSION=\nCOMPRESS_LEVEL=\nCOMPRESSION_LEVEL=\nBIND_ADDRESS4=127.0.0.1\nBIND_ADDRESS6=::1\nMAILU_VERSION=1.9\nDOCKER_ORG=mailu\nDOCKER_PREFIX=\nWELCOME_SUBJECT=Welcome to your new email account\nWELCOME_BODY=Welcome to your new email account, if you can read this, then it is configured properly!\n"
+      "content": "ADMIN_ADDRESS=mailu-admin\nANTISPAM_ADDRESS=mailu-antispam\nANTIVIRUS_ADDRESS=mailu-antivirus\nIMAP_ADDRESS=mailu-imap\nSMTP_ADDRESS=mailu-smtp\nFRONT_ADDRESS=mailu-front\nWEBMAIL_ADDRESS=mailu-webmail\nWEBDAV_ADDRESS=mailu-webdav\nREDIS_ADDRESS=mailu-redis\nPORTS=25,80,443,465,993,995,4190,110,143,587\nDOMAIN=${setting:domain}\nHOSTNAMES=${bound:route:name-web}\nPOSTMASTER=admin\nSITENAME=${setting:sitename}\nWEBSITE=${setting:website}\nTLS_FLAVOR=letsencrypt\nSUBNET=192.168.203.0/24\nCOMPOSE_PROJECT_NAME=mailu\nANTIVIRUS=clamav\nWEBMAIL=roundcube\nWEBDAV=radicale\nFETCHMAIL_ENABLED=True\nFETCHMAIL_DELAY=600\nADMIN=true\nWEB_ADMIN=/admin\nWEB_WEBMAIL=/webmail\nWEBROOT_REDIRECT=/webmail\nAPI=true\nWEB_API=/api\nAUTH_RATELIMIT_IP=6000/hour\nAUTH_RATELIMIT_USER=1000/day\nCREDENTIAL_ROUNDS=12\nPASSWORD_SCHEME=PBKDF2\nDISABLE_STATISTICS=True\nMESSAGE_SIZE_LIMIT=50000000\nMESSAGE_RATELIMIT=200/day\nRECIPIENT_DELIMITER=+\nPOSTFIX_MYNETWORKS=127.0.0.0/8 [::1]/128\nRELAYNETS=\nRELAYHOST=\nREJECT_UNLISTED_RECIPIENT=\nDB_FLAVOR=postgresql\nINITIAL_ADMIN_ACCOUNT=admin\nINITIAL_ADMIN_DOMAIN=${setting:domain}\nINITIAL_ADMIN_MODE=ifmissing\nSMTP_PORT=25\nSMTPS_PORT=465\nSUBMISSION_PORT=587\nPOP3_PORT=110\nPOP3S_PORT=995\nIMAP_PORT=143\nIMAPS_PORT=993\nHTTP_PORT=7080\nHTTPS_PORT=7443\nAUTOMX_PORT=4243\nAMX_SMTP_ADDRESS=${bound:route:name-web}\nAMX_SMTP_PORT=587\nAMX_IMAP_ADDRESS=${bound:route:name-web}\nAMX_IMAP_PORT=143\nAMX_MAIL_DOMAINS=${setting:domain}\nDMARC_RUA=admin\nDMARC_RUF=admin\nLETSENCRYPT_SHORTCHAIN=True\nTZ=Etc/UTC\nLOG_LEVEL=INFO\nWELCOME=false\nREAL_IP_HEADER=X-Real-IP\nREAL_IP_FROM=${setting:proxy-address}\nCOMPRESSION=\nCOMPRESS_LEVEL=\nCOMPRESSION_LEVEL=\nBIND_ADDRESS4=127.0.0.1\nBIND_ADDRESS6=::1\nMAILU_VERSION=1.9\nDOCKER_ORG=mailu\nDOCKER_PREFIX=\nWELCOME_SUBJECT=Welcome to your new email account\nWELCOME_BODY=Welcome to your new email account, if you can read this, then it is configured properly!\n"
    },
    {
      "id": "secret-env",
@@ -305,10 +315,7 @@
        "${dir:data-data}:/data",
        "${dir:data-dkim}:/dkim"
      ],
-      "secrets-in-environment": "mailu-admin honours SECRET_KEY_FILE, DB_PW_FILE and API_TOKEN_FILE (configuration.py) but INITIAL_ADMIN_PW is env-only (start.py); the remaining containers' need for SECRET_KEY is unverified",
+      "secrets-in-environment": "mailu-admin honours SECRET_KEY_FILE, DB_PW_FILE and API_TOKEN_FILE (configuration.py) but INITIAL_ADMIN_PW is env-only (start.py); the remaining containers' need for SECRET_KEY is unverified"
      "dns": [
        "192.168.203.254"
      ]
    },
    {
      "id": "imap",
@@ -483,7 +490,6 @@
        "MESH_MAILU_API_KEY_FILE": "/run/secrets/api-token",
        "MESH_MAILU_IMAP_CONTAINER": "mailu-imap",
        "MESH_MAILU_CONFIG_FILE": "/run/config/config.json",
        "MESH_MAILU_DOMAIN": "novox.be",
        "MESH_RECEIVES": "${dir:grants}/mesh.json"
      },
      "restart-on": [
@@ -546,9 +552,7 @@
  ],
  "serves": {
    "smtp": {
-      "port": 587,
+      "port": 587
      "domain": "novox.be",
      "name": "mail.novox.be"
    }
  },
  "receives": {
@@ -13,17 +13,32 @@
 // it to both ends; mailu sets exactly that password every run — so a rotation takes — and seals
 // nothing: the consumer already has its copy through the mesh's own channel.
 import { readFileSync } from "node:fs";
 import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
 import { MailuClient } from "../client.js";
 const mailu = MailuClient.fromEnv();
-// The mail server's own domain. From the environment the manifest composes, because the client's
+// The mail server's own domain: the operator's value, from the settings the mesh merges into this
-// config file carries the admin API's coordinates, not the mail domain.
+// module's config file (`settings set mailu` with {"domain": …}; novox/hq ADR 0112, ADR 0155). A
 // definition names no mesh, so it is never a literal in the manifest — and it used to be, as
 // MESH_MAILU_DOMAIN, which is still read for a mesh that has not re-registered the manifest.
 function domain(): string {
  const file = process.env.MESH_MAILU_CONFIG_FILE;
  if (file) {
    try {
      const config = JSON.parse(readFileSync(file, "utf8")) as { domain?: unknown };
      if (typeof config.domain === "string" && config.domain.trim() !== "") return config.domain.trim();
    } catch {
      // Unreadable or not JSON: fall through to the environment, and the error below names both.
    }
  }
  const named = (process.env.MESH_MAILU_DOMAIN ?? "").trim();
  if (named === "") {
-    throw new Error("MESH_MAILU_DOMAIN is not set, so a consumer's address cannot be composed");
+    throw new Error(
      "no mail domain is set, so a consumer's address cannot be composed — `settings set mailu <file>` " +
        'with {"domain": "<the mail domain>"}',
    );
  }
  return named;
 }
@@ -6,6 +6,7 @@
  ],
  "listens": [
    {
      "name": "api",
      "port": 59125,
      "protocol": "tcp",
      "from": "mesh",
@@ -0,0 +1,125 @@
 {
  "module": "matrix",
  "version": "1",
  "capabilities": [
    "container-runtime"
  ],
  "listens": [
    {
      "name": "client",
      "port": 6167,
      "protocol": "tcp",
      "from": "mesh",
      "why": "Conduit's client-server and federation APIs over plain HTTP. Both arrive through the route on 443: Conduit answers /.well-known/matrix/server with <its name>:443, so other homeservers federate through the proxy and nothing needs the traditional 8448"
    },
    {
      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
      "why": "Element Web, the static browser client, served by the image's nginx; reached through its route"
    }
  ],
  "requires": [
    "route"
  ],
  "contributes": {
    "route": {
      "homeserver": {
        "label": "matrix",
        "endpoint": "client"
      },
      "element": {
        "label": "element",
        "endpoint": "web"
      }
    }
  },
  "binds": {
    "route": "${dir:state}/route.json"
  },
  "resources": [
    {
      "id": "state",
      "type": "directory",
      "mode": "0700",
      "place": "."
    },
    {
      "id": "db",
      "type": "directory",
      "mode": "0700"
    },
    {
      "id": "conduit-conf",
      "type": "file",
      "path": "${dir:state}/conduit.toml",
      "mode": "0644",
      "content": "# Written by the mesh (modules/matrix). Conduit reads this file (CONDUIT_CONFIG); nothing comes\n# from the environment. server_name is the homeserver's permanent identity: every user id, room id\n# and signature in the database carries it, so it is the name this module is served under\n# (${bound:route:name-homeserver}) and never changes once a database exists.\n[global]\nserver_name = \"${bound:route:name-homeserver}\"\ndatabase_backend = \"rocksdb\"\ndatabase_path = \"/var/lib/matrix-conduit/\"\naddress = \"0.0.0.0\"\nport = 6167\nmax_request_size = 20000000\nallow_registration = false\nallow_federation = true\nallow_check_for_updates = true\ntrusted_servers = [\"matrix.org\"]\n",
      "names-on-purpose": {
        "matrix.org": "the federation's public key server, trusted by default; the world's, not this mesh's"
      }
    },
    {
      "id": "element-conf",
      "type": "file",
      "path": "${dir:state}/element.json",
      "mode": "0644",
      "merge": "json",
      "content": "{\n  \"default_server_name\": \"${bound:route:name-homeserver}\",\n  \"default_server_config\": {\n    \"m.homeserver\": {\n      \"base_url\": \"https://${bound:route:name-homeserver}\"\n    },\n    \"m.identity_server\": {\n      \"base_url\": \"https://vector.im\"\n    }\n  },\n  \"brand\": \"Element\",\n  \"integrations_ui_url\": \"https://scalar.vector.im/\",\n  \"integrations_rest_url\": \"https://scalar.vector.im/api\",\n  \"integrations_widgets_urls\": [\n    \"https://scalar.vector.im/_matrix/integrations/v1\",\n    \"https://scalar.vector.im/api\",\n    \"https://scalar-staging.vector.im/_matrix/integrations/v1\",\n    \"https://scalar-staging.vector.im/api\",\n    \"https://scalar-staging.riot.im/scalar/api\"\n  ],\n  \"bug_report_endpoint_url\": \"https://element.io/bugreports/submit\",\n  \"uisi_autorageshake_app\": \"element-auto-uisi\",\n  \"show_labs_settings\": true,\n  \"room_directory\": {\n    \"servers\": [\n      \"${bound:route:name-homeserver}\",\n      \"matrix.org\",\n      \"gitter.im\",\n      \"libera.chat\"\n    ]\n  },\n  \"enable_presence_by_hs_url\": {\n    \"https://matrix.org\": false,\n    \"https://matrix-client.matrix.org\": false\n  },\n  \"terms_and_conditions_links\": [\n    {\n      \"url\": \"https://element.io/privacy\",\n      \"text\": \"Privacy Policy\"\n    },\n    {\n      \"url\": \"https://element.io/cookie-policy\",\n      \"text\": \"Cookie Policy\"\n    }\n  ],\n  \"features\": {\n    \"feature_video_rooms\": true,\n    \"feature_rust_crypto\": true\n  },\n  \"element_call\": {\n    \"url\": \"https://call.element.dev\"\n  }\n}\n",
      "names-on-purpose": {
        "matrix.org": "the public room directory and the federation's largest homeserver; the world's",
        "matrix-client.matrix.org": "the same homeserver's client endpoint; the world's",
        "vector.im": "Element's public identity server; the world's",
        "scalar.vector.im": "Element's public integration manager; the world's",
        "scalar-staging.vector.im": "Element's staging integration manager, named by the upstream default config; the world's",
        "scalar-staging.riot.im": "the same, under its former name; the world's",
        "element.io": "Element's bug reports, privacy and cookie pages; the world's",
        "gitter.im": "a public room directory; the world's",
        "libera.chat": "a public room directory; the world's",
        "call.element.dev": "Element Call's public instance; the world's"
      }
    },
    {
      "id": "net",
      "type": "network",
      "name": "matrix"
    },
    {
      "id": "homeserver",
      "type": "container",
      "name": "matrix",
      "image": "matrixconduit/matrix-conduit@sha256:b0d24248e94f944ca49f90f10c429e3d65f4472bdde25661ecea9840134fb133",
      "network": "matrix",
      "env": {
        "CONDUIT_CONFIG": "/etc/conduit/conduit.toml"
      },
      "ports": [
        "6167"
      ],
      "volumes": [
        "${dir:db}:/var/lib/matrix-conduit",
        "${dir:state}/conduit.toml:/etc/conduit/conduit.toml:ro"
      ],
      "restart-on": [
        "conduit-conf"
      ]
    },
    {
      "id": "element",
      "type": "container",
      "name": "element-web",
      "image": "vectorim/element-web@sha256:a8f415462ab8d2600a592ba1b92bea51efe5a4d10eb738aab9bed769f7099613",
      "network": "matrix",
      "ports": [
        "80"
      ],
      "volumes": [
        "${dir:state}/element.json:/app/config.json:ro"
      ],
      "restart-on": [
        "element-conf"
      ]
    }
  ]
 }
@@ -22,7 +22,7 @@ COPY . .
 # The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
 # symlinks to a launcher that requires its library relatively — resolved away when the base image
 # was assembled.
-RUN node /app/node_modules/typescript/bin/tsc pg.d.ts store.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc pg.d.ts store.ts index.ts tools/index.ts prepare/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 # **A module may need something the base image does not carry.** The base holds what every module
@@ -48,3 +48,8 @@ COPY --from=build /deps/node_modules /app/modules/mesh-catalog/node_modules
 # to listen for what the builder announces. Serve binds the broker first, then imports these, so
 # `on()` has something to subscribe to.
 ENV MESH_TOOL_MODULES=/app/modules/mesh-catalog/dist/index.js,/app/modules/mesh-catalog/dist/tools/index.js
 # And what prepares this module's state, for the runtime's `prepare` mode (novox/hq ADR 0135). Named
 # here, beside the entrypoints above, because the module knows which of its files prepares its state
 # and nothing else could: the mesh asks one word and this says what answers it.
 ENV MESH_PREPARE=/app/modules/mesh-catalog/dist/prepare/index.js
@@ -14,10 +14,12 @@ import { Graph, type Made } from "./store.js";
 const graph = Graph.fromEnv();
-// Before subscribing, and idempotent. The runtime is restarted until its store is reachable, which
+// The schema is not brought up here. The mesh prepares this module's state before it starts this
-// is the same arrangement model-usage uses: a schema step that had to reach the provider over the
+// version, and does not start it if that failed (novox/hq ADR 0135) — see prepare/index.ts. Doing it
-// overlay would block the very apply that brings the overlay up.
+// at start made a schema that could not be reached a crash loop instead of a stop, with the graph
-await graph.migrate();
+// keeping a gap and nothing saying so. The reason it used to be here — that a step blocking the apply
 // would block the very apply that brings the overlay up — stopped being true when a step's failure
 // became this module's business and not the machine's (ADR 0136).
 /** What the builder says when it has built something. */
 interface Built {
@@ -47,7 +49,15 @@ interface Built {
  replay?: boolean;
 }
-await on("mesh-build-machine.built", async (event) => {
+/**
 * What a build means for the graph, wherever it came from.
 *
 * Two emitters say the same thing and neither is a mistake: the build machine says it as it happens,
 * and the control plane says what it already held when this module asks what it missed
 * (novox/hq ADR 0134). A replay is marked as one in its body, so nothing acts on a module that moved
 * months ago — see `replay` above.
 */
 const placeTheBuild = async (event: { body: unknown }): Promise<void> => {
  const body = event.body as Built;
  if (!body.module || !body.commit) {
    // Said rather than dropped: a build that announced itself without saying what it built is a
@@ -89,7 +99,11 @@ await on("mesh-build-machine.built", async (event) => {
      because: next.because,
    });
  }
-});
+};
 // As it happens, and what the mesh already held when this module asked what it missed.
 await on("mesh-build-machine.built", placeTheBuild);
 await on("mesh-controller.built-before", placeTheBuild);
 // **And ask for what was built before this catalogue existed** (novox/hq 04-ISSUES/050).
 //
@@ -29,13 +29,16 @@
    "broker": "/var/lib/mesh/mesh-catalog/broker"
  },
  "consumes": [
-    "mesh-build-machine.built"
+    "mesh-build-machine.built",
    "mesh-controller.built-before"
  ],
  "emits": [
    "registered",
    "upgraded",
-    "rebuild-needed"
+    "rebuild-needed",
    "catching-up"
  ],
  "prepares": true,
  "resources": [
    {
      "id": "mesh-state",
@@ -0,0 +1,17 @@
 // The catalogue's state, brought to the shape this version needs (novox/hq ADR 0135).
 //
 // **The mesh runs this before the version that needs it, and does not start that version if it
 // fails** — and the refusal reaches this module and nothing else on the machine
 // (novox/hq ADR 0136). That is the whole difference from where this used to happen: at start, inside
 // the runtime, a schema that could not be brought up was a crash loop, the graph kept a gap, and
 // nothing anywhere said so.
 //
 // Nothing here connects to the broker. Preparation runs before the version that would use it, so
 // there is nothing yet to talk to; the runtime's `prepare` mode imports this and awaits it, and this
 // process exiting non-zero is how the host knows not to start the runtime.
 import { Graph } from "../store.js";
 const graph = Graph.fromEnv();
 await graph.migrate();
 console.log("[mesh-catalog] the module graph's schema is what this version needs");
 await graph.close();
@@ -12,6 +12,7 @@
    "pg.d.ts",
    "store.ts",
    "index.ts",
-    "tools/index.ts"
+    "tools/index.ts",
    "prepare/index.ts"
  ]
 }
@@ -0,0 +1,13 @@
 # The console (novox/hq ADR 0152, design 34): the mesh's tools for whoever is on a machine, served
 # over MCP on that machine's loopback.
 #
 # **Nothing is compiled here.** The console is the tool runtime's own client — `mesh serve` — which
 # the runtime image already carries beside the runtime it runs modules with. This recipe changes the
 # program the image starts and nothing else, so the console is exactly the client a person can run by
 # hand, started by the mesh instead, on the credential the mesh sealed to the machine.
 #
 # One base, named rather than pinned: the mesh answers with the copy it holds (novox/hq issue 044).
 ARG RUNTIME_BASE
 FROM ${RUNTIME_BASE}
 ENTRYPOINT ["node", "dist/mesh.js"]
@@ -0,0 +1,38 @@
 # mesh-console
 The mesh's tools, on the machine a person sits at, served by a module the mesh assigned there
 (novox/hq [ADR 0152](https://git.novox.be/novox/hq), design 34).
 Assign it to a machine and an agent on that machine has the mesh's tools at
 `http://127.0.0.1:<port>/mcp` — MCP over HTTP, `initialize`, `tools/list`, `tools/call`. A person at
 a terminal reaches the same endpoint with `mesh tools --console http://127.0.0.1:<port>` and
 `mesh call <module>.<tool> --console …`, with no credential of their own: the console holds it.
 ## What it is
 The tool runtime's own client, `mesh serve`, started by the mesh on the credential it sealed to the
 machine for `<node>.mesh-console`. The manifest says three things nothing else in the catalogue says
 together:
 - `invokes: ["*"]` — it calls every tool on the mesh, and the bus grants exactly that publish side;
 - a listener `from: machine` — loopback only, and the filter opens nothing for it;
 - no `emits`, no `consumes`, no `tools` — nothing on the bus can address it.
 **Loopback is the authority boundary.** Whoever can connect is on the machine, and whoever is on the
 machine is the account that owns the mesh there (ADR 0034, ADR 0144). There is no token and no login,
 and `mesh serve` refuses to bind anything but a loopback address.
 ## What it lists
 What the running modules answer: every tool runtime serves a `tools` verb for its module, and the
 console asks the catalogue which modules the mesh holds and each module what it serves. A module that
 did not answer — not assigned, not up, or built before the runtime answered `tools` — is named in the
 list's `_meta.notAnswering` and can still be called by `<module>.<tool>`.
 The mesh's own verbs (`status`, `push`, `assign`) are the `mesh-controller` seat's tools under
 ADR 0132 and are not served on the bus yet; they appear here when they are.
 ## Port
 The manifest declares port 4270 and the mesh assigns the machine port as it does for any listener;
 the console binds `127.0.0.1:${port:4270}`. `node show <machine>` says which port a machine was given.
@@ -0,0 +1,64 @@
 {
  "module": "mesh-console",
  "version": "1",
  "slug": "console",
  "capabilities": [
    "container-runtime"
  ],
  "invokes": [
    "*"
  ],
  "own-secrets": {
    "broker": "/var/lib/mesh/mesh-console/broker"
  },
  "listens": [
    {
      "name": "mcp",
      "port": 4270,
      "protocol": "tcp",
      "from": "machine",
      "why": "the mesh's tools for whoever is on this machine, over MCP on loopback; the machine's login is the authority (novox/hq ADR 0152)"
    }
  ],
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "path": "/var/lib/mesh/mesh-console",
      "mode": "0700"
    },
    {
      "id": "server",
      "type": "container",
      "name": "mesh-console",
      "network": "host",
      "args": [
        "serve"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
        "MESH_CONSOLE_LISTEN": "127.0.0.1:${port:4270}"
      },
      "volumes": [
        "/var/lib/mesh/mesh-console/broker:/run/secrets/broker:ro"
      ],
      "artifact": "runtime"
    }
  ],
  "build": {
    "on": [
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
        "name": "runtime",
        "kind": "image",
        "from": "Dockerfile"
      }
    ]
  }
 }
@@ -14,11 +14,11 @@
    "route": {
      "api": {
        "label": "files-api",
-        "port": 9000
+        "endpoint": "s3"
      },
      "console": {
        "label": "files",
-        "port": 9001
+        "endpoint": "console"
      }
    }
  },
@@ -31,12 +31,14 @@
  ],
  "listens": [
    {
      "name": "s3",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the S3 endpoint"
    },
    {
      "name": "console",
      "port": 9001,
      "protocol": "tcp",
      "from": "mesh",
@@ -84,7 +86,7 @@
      "type": "file",
      "path": "/var/lib/minio/root.env",
      "mode": "0600",
-      "content": "MINIO_ROOT_USER=meshroot\n"
+      "content": "MINIO_ROOT_USER=meshroot\nMINIO_BROWSER_REDIRECT_URL=https://${bound:route:name-console}\n"
    },
    {
      "id": "data",
@@ -122,7 +124,6 @@
      ],
      "env": {
        "MINIO_ROOT_PASSWORD_FILE": "/run/secrets/root",
        "MINIO_BROWSER_REDIRECT_URL": "https://files.novox.be",
        "MINIO_REGION": "eu-west"
      }
    },
@@ -20,6 +20,7 @@
  ],
  "listens": [
    {
      "name": "database",
      "port": 27017,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/mosquitto
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc topics.ts client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
@@ -20,6 +20,8 @@ import { readFileSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { missingAcls, parseRoleAcls, staleAcls, wantedAcls } from "./topics.js";
 const run = promisify(execFile);
 export interface MqttConn {
@@ -141,14 +143,19 @@ export class MosquittoClient {
  }
  /**
-   * Create (or reset to a known state) a client scoped to one topic namespace, idempotently. The
+   * Create (or reset to a known state) a client granted exactly these topic filters, idempotently.
-   * client is confined to `<prefix>/#` by a same-named role: it may publish to, subscribe to and
+   * The grant is a same-named role carrying, for every filter, publish, receive and subscribe — and
-   * receive on exactly its own subtree and nothing else — the MQTT analog of redis's keyspace-scoped
+   * nothing else: an ACL the role carries that the filters no longer name is removed, so narrowing a
-   * ACL user. Called again for an existing client, it resets the password and re-asserts the ACLs.
+   * consumer's `topics` narrows what it may do. By default the filters are the consumer's own
   * subtree, `<as>/#` (see topics.ts). Called again for an existing client, it resets the password
   * and re-asserts the ACLs.
   *
   * Only the role named for this client is ever changed. A client or role the mesh did not make —
   * a device carried from the predecessor's password file, its `legacy-full-access` role — is never
   * read, changed or removed here.
   */
-  async createScopedClient(username: string, password: string, topicPrefix: string): Promise<void> {
+  async createScopedClient(username: string, password: string, filters: readonly string[]): Promise<void> {
    const role = username; // one role per client, named for it
    const pattern = `${topicPrefix}/#`;
    if (await this.clientExists(username)) {
      await this.ctl("setClientPassword", username, password);
@@ -161,17 +168,18 @@ export class MosquittoClient {
      await this.ctl("createClient", username, "-p", password);
    }
-    // A role carrying exactly this client's topic ACLs. createRole, addRoleACL and addClientRole are
+    // createRole and addRoleACL are one-shot: each rejects with an "already exists" when re-run
-    // all one-shot: each rejects with an "already exists" when re-run against a role/ACL/binding it
+    // against a role/ACL it created on a previous reconcile. That rejection is the intended terminal
-    // created on a previous reconcile. That rejection is the intended terminal state — the ACL is
+    // state, so it is swallowed.
    // deterministic (`<prefix>/#`, allow), so re-adding the identical entry is a no-op — so it is
    // swallowed. (Until the exit code was fixed this was invisible: the tool returned 0 and the
    // rejection was lost; now it surfaces, and each of these adds must tolerate its own idempotent
    // re-run explicitly.)
    await ignoreExisting(this.ctl("createRole", role));
-    for (const acl of ["publishClientSend", "publishClientReceive", "subscribePattern"]) {
+    const wanted = wantedAcls(filters);
-      // allow (1) this client to send to, receive on, and subscribe under its own subtree.
+    const current = parseRoleAcls(await this.ctl("getRole", role));
-      await ignoreExisting(this.ctl("addRoleACL", role, acl, pattern, "allow"));
+    for (const acl of missingAcls(current, wanted)) {
      await ignoreExisting(this.ctl("addRoleACL", role, acl.type, acl.topic, "allow"));
    }
    // What the consumer no longer asks for — added before it narrowed its topics — is taken away.
    for (const acl of staleAcls(current, wanted)) {
      await ignoreMissing(this.ctl("removeRoleACL", role, acl.type, acl.topic));
    }
    // Bind the role only when it is not already bound — addClientRole is the one call whose
    // idempotent re-run cannot be recognised by message (see clientHasRole).
@@ -181,25 +189,31 @@ export class MosquittoClient {
  }
  /**
-   * Whether a consumer's client accepts exactly this password and still carries its own role.
+   * Whether a consumer's client accepts exactly this password, still carries its own role, and that
-   * Read-only. The password is checked the way the consumer is checked, by an MQTT CONNECT as it,
+   * role grants exactly these filters. Read-only. The password is checked the way the consumer is
-   * and the broker's CONNACK code is the answer: 0 accepted, 4 bad credentials, 5 not authorised.
+   * checked, by an MQTT CONNECT as it, and the broker's CONNACK code is the answer: 0 accepted,
-   * Nothing rides on argv. An unreachable broker rejects (novox/hq issue 120).
+   * 4 bad credentials, 5 not authorised. Nothing rides on argv. An unreachable broker rejects
   * (novox/hq issue 120).
   */
-  async holdsClient(username: string, password: string): Promise<boolean> {
+  async holdsClient(username: string, password: string, filters: readonly string[]): Promise<boolean> {
    const code = await mqttConnack(this.conn.host, this.conn.port, username, password);
    if (code === 4 || code === 5) return false;
    if (code !== 0) throw new Error(`mosquitto refused ${username} with CONNACK ${code}`);
    // The role, asked directly: only "not found" means absent. Any other failure to ask rejects,
    // unlike clientHasRole, which reads every failure as "no role".
-    let out: string;
+    let client: string;
    let role: string;
    try {
-      out = await this.ctl("getClient", username);
+      client = await this.ctl("getClient", username);
      role = await this.ctl("getRole", username);
    } catch (err) {
      if (/not\s*found|does not exist|no such/i.test(String(err))) return false;
      throw err;
    }
-    return new RegExp(`(^|\\s)${escapeRegExp(username)}\\s+\\(priority`, "m").test(out);
+    if (!new RegExp(`(^|\\s)${escapeRegExp(username)}\\s+\\(priority`, "m").test(client)) return false;
    const current = parseRoleAcls(role);
    const wanted = wantedAcls(filters);
    return missingAcls(current, wanted).length === 0 && staleAcls(current, wanted).length === 0;
  }
  /** Remove a client and the per-client role created for it, idempotently. */
@@ -20,26 +20,31 @@
    "mosquitto.topic.deprovisioned"
  ],
  "serves": {
-    "mqtt-topic": {}
+    "mqtt-topic": {
      "scheme": "mqtt",
      "port": 1883
    }
  },
  "receives": {
-    "mqtt-topic": "/var/lib/mosquitto-module/grants/mesh.json"
+    "mqtt-topic": "${dir:grants}/mesh.json"
  },
  "grants": {
-    "mqtt-topic": "/var/lib/mosquitto-module/grants"
+    "mqtt-topic": "${dir:grants}"
  },
  "own-secrets": {
-    "admin": "/var/lib/mosquitto-module/admin.secret",
+    "admin": "/var/lib/mesh/mosquitto/admin",
    "broker": "/var/lib/mesh/mosquitto/broker"
  },
  "listens": [
    {
      "name": "mqtt",
      "port": 1883,
      "protocol": "tcp",
      "from": "mesh",
      "why": "modules on any machine that were granted a topic namespace"
    },
    {
      "name": "mqtt-websockets",
      "port": 8081,
      "protocol": "tcp",
      "from": "mesh",
@@ -56,26 +61,24 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/mosquitto-module",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
-      "id": "grants-dir",
+      "id": "grants",
      "type": "directory",
      "path": "/var/lib/mosquitto-module/grants",
      "mode": "0700"
    },
    {
      "id": "data",
      "type": "directory",
      "path": "/services/mosquitto/data",
      "mode": "0700",
      "owner": "1883:1883"
    },
    {
      "id": "server-conf",
      "type": "file",
-      "path": "/var/lib/mosquitto-module/mosquitto.conf",
+      "path": "${dir:state}/mosquitto.conf",
      "mode": "0600",
      "owner": "1883:1883",
      "content": "persistence true\npersistence_location /mosquitto/data\n\nlog_dest stdout\nlog_type warning\nlog_type error\nlog_type notice\n\n# Every client authenticates; identities and their per-topic ACLs are managed\n# at runtime by the dynamic security plugin, whose store the plugin itself owns.\nallow_anonymous false\nplugin /usr/lib/mosquitto_dynamic_security.so\nplugin_opt_config_file /mosquitto/data/dynamic-security.json\n\n# MQTT listener\nlistener 1883\n\n# MQTT-over-WebSockets listener\nlistener 8081\nprotocol websockets\n"
@@ -91,8 +94,8 @@
      "name": "mosquitto-bootstrap",
      "run-once": true,
      "volumes": [
-        "/services/mosquitto/data:/mosquitto/data",
+        "${dir:data}:/mosquitto/data",
-        "/var/lib/mosquitto-module/admin.secret:/run/secrets/admin:ro"
+        "/var/lib/mesh/mosquitto/admin:/run/secrets/admin:ro"
      ],
      "env": {
        "MESH_PROVISION_MQTT": "mosquitto:1883",
@@ -110,15 +113,15 @@
      "id": "server",
      "type": "container",
      "name": "mosquitto",
-      "image": "eclipse-mosquitto@sha256:6f8d8a947c506f8a2290ec65cd4bd2bc7cb4d43fb5f6271f861cb013e2ef9797",
+      "image": "eclipse-mosquitto@sha256:38c0da4f2ef84284d47b3b3eeea1cb3bdeabe81ee10caf0cd5c5ff61ee3ea408",
      "network": "mosquitto",
      "ports": [
        "1883",
        "8081"
      ],
      "volumes": [
-        "/services/mosquitto/data:/mosquitto/data",
+        "${dir:data}:/mosquitto/data",
-        "/var/lib/mosquitto-module/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"
+        "${dir:state}/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"
      ]
    },
    {
@@ -128,12 +131,12 @@
      "network": "mosquitto",
      "volumes": [
        "/var/lib/mesh/mosquitto/broker:/run/secrets/broker:ro",
-        "/var/lib/mosquitto-module/grants:/var/lib/mosquitto-module/grants:ro",
+        "${dir:grants}:${dir:grants}:ro",
-        "/var/lib/mosquitto-module/admin.secret:/run/secrets/admin:ro"
+        "/var/lib/mesh/mosquitto/admin:/run/secrets/admin:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RECEIVES": "/var/lib/mosquitto-module/grants/mesh.json",
+        "MESH_RECEIVES": "${dir:grants}/mesh.json",
        "MESH_PROVISION_MQTT": "mosquitto:1883",
        "MESH_PROVISION_ADMIN_USER": "mesh-admin",
        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/admin"
@@ -1,9 +1,14 @@
 {
  "name": "@novox/module-mosquitto",
  "version": "0.1.0",
-  "description": "mosquitto — provides the mesh mqtt-topic interface. Its admin client, provisioner, tools and events live here (novox/hq ADR 0039).",
+  "description": "mosquitto \u2014 provides the mesh mqtt-topic interface. Its admin client, provisioner, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc topics.ts client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/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.1"
  },
@@ -5,7 +5,14 @@
 //
 // The `mqtt-topic` interface: a consumer connects as `as` with the password the mesh minted, and
 // publishes and subscribes under `<as>/#`, isolated from every other consumer by a Dynamic Security
-// role scoped to exactly that subtree.
+// role scoped to exactly that subtree — unless it contributed `topics`, the MQTT topic filters its
 // work needs (a home-automation hub needs the devices' topics); then the role grants exactly those
 // (topics.ts). A list that is not valid topic filters is refused, and the consumer is not created
 // or changed until it is fixed.
 //
 // What a consumer is told (its binding): `at` — the broker's machine — and `port`, the machine port
 // of the MQTT listener (the manifest's `serves`); `as` is its login, and its copy of the password is
 // the pair credential the mesh delivers to it.
 //
 // **The login and password are the mesh's, not the provisioner's (ADR 0048).** The mesh derives the
 // login and hands it to both ends so they agree, and mints the password and delivers a copy to each.
@@ -15,6 +22,7 @@
 import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
 import { emit } from "@novox/mesh-sdk/events";
 import { MosquittoClient } from "../client.js";
 import { topicFilters } from "../topics.js";
 const mosquitto = MosquittoClient.fromEnv();
@@ -29,13 +37,20 @@ async function announce(type: string, body: Record<string, string>): Promise<voi
 runProvisioner("mqtt-topic", {
  async create(p: Provision): Promise<void> {
-    // The topic subtree is scoped to the consumer's own login, so one cannot read another's topics.
+    // By default the consumer's own subtree, so one cannot read another's topics; what it
-    const topicPrefix = p.as;
+    // contributed as `topics` otherwise.
-    await mosquitto.createScopedClient(p.as, p.password, topicPrefix);
+    const granted = topicFilters(p.values, p.as);
    if ("problem" in granted) {
      // Thrown, so the harness logs it and retries: the consumer stays as it was (or absent) until
      // its contribution is valid, rather than being given a grant it did not ask for.
      throw new Error(`${p.as}: ${granted.problem}`);
    }
    await mosquitto.createScopedClient(p.as, p.password, granted.filters);
    await announce("topic.provisioned", {
      consumer: p.consumer ?? "",
      username: p.as,
-      topicPrefix,
+      topicPrefix: granted.own ? p.as : "",
      topics: granted.filters.join(" "),
    });
  },
@@ -46,6 +61,9 @@ runProvisioner("mqtt-topic", {
  // Asked every minute by the harness: whether the backend still holds this consumer exactly as
  // the mesh gave it, so a login lost behind the provisioner's back is made again (novox/hq issue 120).
  async holds(p: Provision): Promise<boolean> {
-    return mosquitto.holdsClient(p.as, p.password);
+    const granted = topicFilters(p.values, p.as);
    // An invalid list was never applied; create refuses it again, loudly, on every pass.
    if ("problem" in granted) return false;
    return mosquitto.holdsClient(p.as, p.password, granted.filters);
  },
 });
@@ -0,0 +1,72 @@
 // What a consumer of mqtt-topic is granted (topics.ts): its own subtree unless it contributed
 // `topics`; a contributed list is granted exactly, refused whole when it is not topic filters; and
 // the role is brought to exactly the wanted ACLs — missing ones added, stale ones removed — read from
 // `mosquitto_ctrl dynsec getRole` as eclipse-mosquitto 2.1.2 prints it.
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { filterProblem, missingAcls, parseRoleAcls, staleAcls, topicFilters, wantedAcls } from "../topics.ts";
 test("a consumer that contributed nothing gets its own subtree", () => {
  assert.deepEqual(topicFilters({}, "mesh_ace_hass"), { ok: true, filters: ["mesh_ace_hass/#"], own: true });
  assert.deepEqual(topicFilters(undefined, "x"), { ok: true, filters: ["x/#"], own: true });
  // Settings merge into every contribution: keys that are not `topics` change nothing.
  assert.deepEqual(topicFilters({ endpoints: { web: {} } }, "x"), { ok: true, filters: ["x/#"], own: true });
 });
 test("a contributed list is granted exactly, duplicates once", () => {
  assert.deepEqual(topicFilters({ topics: ["#"] }, "x"), { ok: true, filters: ["#"], own: false });
  assert.deepEqual(topicFilters({ topics: ["stat/+/POWER", "tele/#", "tele/#", "/octoprint/x"] }, "x"), {
    ok: true,
    filters: ["stat/+/POWER", "tele/#", "/octoprint/x"],
    own: false,
  });
 });
 test("a list that is not topic filters is refused whole", () => {
  for (const topics of [[], "#", [""], ["a/#/b"], ["a#"], ["a/b+"], [42], ["a\u0000b"], {}]) {
    const out = topicFilters({ topics } as Record<string, unknown>, "x");
    assert.equal(out.ok, false, JSON.stringify(topics));
  }
  assert.equal(filterProblem("+/+/#"), undefined);
  assert.equal(filterProblem("#"), undefined);
 });
 const GET_ROLE = `Warning: You are running mosquitto_ctrl without encryption.
 This means all of the configuration changes you are making are visible on the network, including passwords.
 Rolename: u1
 ACLs:     publishClientSend    : allow : # (priority: 0)
          subscribePattern     : allow : u1/# (priority: 0)
          publishClientReceive : deny : secret topic/with space (priority: -1)
 `;
 test("getRole's ACL lines are read, the warning and headings are not", () => {
  assert.deepEqual(parseRoleAcls(GET_ROLE), [
    { type: "publishClientSend", allow: true, topic: "#" },
    { type: "subscribePattern", allow: true, topic: "u1/#" },
    { type: "publishClientReceive", allow: false, topic: "secret topic/with space" },
  ]);
  assert.deepEqual(parseRoleAcls("Rolename: empty\nACLs:\n"), []);
 });
 test("the role is brought to exactly the wanted ACLs", () => {
  const current = parseRoleAcls(GET_ROLE);
  const wanted = wantedAcls(["u1/#"]);
  assert.deepEqual(wanted, [
    { type: "publishClientSend", allow: true, topic: "u1/#" },
    { type: "publishClientReceive", allow: true, topic: "u1/#" },
    { type: "subscribePattern", allow: true, topic: "u1/#" },
  ]);
  assert.deepEqual(missingAcls(current, wanted), [
    { type: "publishClientSend", allow: true, topic: "u1/#" },
    { type: "publishClientReceive", allow: true, topic: "u1/#" },
  ]);
  assert.deepEqual(staleAcls(current, wanted), [
    { type: "publishClientSend", allow: true, topic: "#" },
    { type: "publishClientReceive", allow: false, topic: "secret topic/with space" },
  ]);
  assert.deepEqual(staleAcls(wanted, wanted), []);
  assert.deepEqual(missingAcls(wanted, wanted), []);
 });
@@ -0,0 +1,107 @@
 // Which topics a consumer of `mqtt-topic` may use — the one choice a consumer makes about its grant.
 //
 // **By default, its own subtree and nothing else.** A consumer connects as the login the mesh derived
 // (`as`) and may publish, receive and subscribe under `<as>/#` — isolated from every other consumer,
 // which is the point of a per-consumer client (novox/hq ADR 0039/0048).
 //
 // **A consumer whose work IS the shared topic space says so.** Home Assistant discovers devices
 // under `homeassistant/#` and `tasmota/discovery/#` and follows whatever state topics they announce;
 // Node-RED's flows subscribe to the topics devices publish on (`stat/<device>/POWER`, …). Confined
 // to `<as>/#` neither could do its job. So a consumer contributes `topics` to its `mqtt-topic`
 // requirement — a list of MQTT topic filters — and the provisioner grants exactly those, both ways.
 // Because assignment settings merge into every contribution, an operator narrows (or widens) the
 // list per machine with the same key, without editing a manifest.
 //
 // Pure, so it is tested without a broker (test/topics.test.ts).
 /** The dynsec ACL types a granted filter carries: send to it, receive from it, subscribe to it. */
 export const GRANTED_ACL_TYPES = ["publishClientSend", "publishClientReceive", "subscribePattern"] as const;
 /** One ACL on a role, as `mosquitto_ctrl dynsec getRole` reports it. */
 export interface Acl {
  type: string;
  allow: boolean;
  topic: string;
 }
 export type Filters = { ok: true; filters: string[]; own: boolean } | { ok: false; problem: string };
 /**
 * The topic filters a consumer is granted: what it contributed as `topics`, or its own subtree when
 * it contributed nothing. Refused — never silently narrowed or widened — when the list is not a
 * list of valid MQTT topic filters: a grant that quietly differs from what was asked is a consumer
 * that fails somewhere far from the cause.
 */
 export function topicFilters(values: Readonly<Record<string, unknown>> | undefined, as: string): Filters {
  const given = values?.topics;
  if (given === undefined || given === null) {
    return { ok: true, filters: [`${as}/#`], own: true };
  }
  if (!Array.isArray(given) || given.length === 0) {
    return { ok: false, problem: `topics must be a non-empty list of MQTT topic filters, not ${JSON.stringify(given)}` };
  }
  const out: string[] = [];
  for (const f of given) {
    if (typeof f !== "string") {
      return { ok: false, problem: `topics holds ${JSON.stringify(f)}, which is not a topic filter` };
    }
    const problem = filterProblem(f);
    if (problem) return { ok: false, problem: `topic filter ${JSON.stringify(f)}: ${problem}` };
    if (!out.includes(f)) out.push(f);
  }
  return { ok: true, filters: out, own: out.length === 1 && out[0] === `${as}/#` };
 }
 /** Why a string is not a valid MQTT topic filter (MQTT 3.1.1 §4.7), or undefined when it is one. */
 export function filterProblem(filter: string): string | undefined {
  if (filter.length === 0) return "it is empty";
  if (Buffer.byteLength(filter, "utf8") > 65535) return "it is longer than MQTT allows";
  if (filter.includes("\u0000")) return "it contains a NUL character";
  const levels = filter.split("/");
  for (let i = 0; i < levels.length; i++) {
    const level = levels[i];
    if (level.includes("#") && (level !== "#" || i !== levels.length - 1)) {
      return "'#' must be a whole level, and the last one";
    }
    if (level.includes("+") && level !== "+") return "'+' must be a whole level";
  }
  return undefined;
 }
 /** The ACLs a role must carry to grant these filters: every granted type, allowed, on every filter. */
 export function wantedAcls(filters: readonly string[]): Acl[] {
  const out: Acl[] = [];
  for (const topic of filters) {
    for (const type of GRANTED_ACL_TYPES) out.push({ type, allow: true, topic });
  }
  return out;
 }
 /**
 * The ACLs `mosquitto_ctrl dynsec getRole` lists, one per line under its "ACLs:" heading:
 *   `ACLs:     publishClientSend    : allow : # (priority: 0)`
 *   `          subscribePattern     : allow : u1/# (priority: 0)`
 */
 export function parseRoleAcls(output: string): Acl[] {
  const out: Acl[] = [];
  const line = /^(?:ACLs:)?\s*([A-Za-z]+)\s*:\s*(allow|deny)\s*:\s*(.*?)\s+\(priority:\s*-?\d+\)\s*$/;
  for (const raw of output.split(/\r?\n/)) {
    const m = raw.match(line);
    if (m) out.push({ type: m[1], allow: m[2] === "allow", topic: m[3] });
  }
  return out;
 }
 const key = (a: Acl): string => `${a.type}\u0000${a.allow ? "allow" : "deny"}\u0000${a.topic}`;
 /** ACLs a role carries that it should not: in `current` and not in `wanted`. */
 export function staleAcls(current: readonly Acl[], wanted: readonly Acl[]): Acl[] {
  const want = new Set(wanted.map(key));
  return current.filter((a) => !want.has(key(a)));
 }
 /** ACLs a role should carry and does not. */
 export function missingAcls(current: readonly Acl[], wanted: readonly Acl[]): Acl[] {
  const have = new Set(current.map(key));
  return wanted.filter((a) => !have.has(key(a)));
 }
@@ -8,5 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "index.ts", "provisioner/index.ts", "tools/index.ts", "bootstrap/index.ts"]
+  "include": ["topics.ts", "client.ts", "index.ts", "provisioner/index.ts", "tools/index.ts", "bootstrap/index.ts"]
 }
@@ -20,23 +20,24 @@
  ],
  "listens": [
    {
-      "port": 4848,
+      "name": "database",
      "port": 1433,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "modules on any machine that were granted a database. 4848, not 1433: the machine this replaces has served it there since it was installed, and every consumer was handed that number"
+      "why": "modules on any machine that were granted a database, and the people who were given its address; the machine port is the assignment's to pin"
    }
  ],
  "serves": {
    "mssql-database": {}
  },
  "receives": {
-    "mssql-database": "/var/lib/mssql/grants/mesh.json"
+    "mssql-database": "${dir:grants}/mesh.json"
  },
  "grants": {
-    "mssql-database": "/var/lib/mssql/grants"
+    "mssql-database": "${dir:grants}"
  },
  "own-secrets": {
-    "sa": "/var/lib/mssql/sa.secret",
+    "sa": "${dir:state}/sa.secret",
    "broker": "/var/lib/mesh/mssql/broker"
  },
  "resources": [
@@ -49,19 +50,18 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/mssql",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
      "id": "grants",
      "type": "directory",
      "path": "/var/lib/mssql/grants",
      "mode": "0700"
    },
    {
      "id": "sa-env",
      "type": "file",
-      "path": "/var/lib/mssql/sa.env",
+      "path": "${dir:state}/sa.env",
      "mode": "0600",
      "content": "ACCEPT_EULA=Y\nMSSQL_SA_PASSWORD=${secret:sa}\n"
    },
@@ -83,7 +83,7 @@
      "image": "mcr.microsoft.com/mssql/server@sha256:4402d880dd4c34bfa7d8705e56a86cd6c88da80a1f6bbbe741f999e76264a090",
      "network": "mssql",
      "env-file": [
-        "/var/lib/mssql/sa.env"
+        "${dir:state}/sa.env"
      ],
      "ports": [
        "1433"
@@ -100,8 +100,8 @@
      "network": "mssql",
      "volumes": [
        "/var/lib/mesh/mssql/broker:/run/secrets/broker:ro",
-        "/var/lib/mssql/grants:/var/lib/mssql/grants:ro",
+        "${dir:grants}:/var/lib/mssql/grants:ro",
-        "/var/lib/mssql/sa.secret:/run/secrets/sa:ro"
+        "${dir:state}/sa.secret:/run/secrets/sa:ro"
      ],
      "env": {
        "MESH_PROVISION_MSSQL": "mssql://sa@mssql:1433/master",
@@ -0,0 +1,20 @@
 # n8n with what its workflows reach for beyond the upstream image.
 #
 # The base is named, not pinned here (novox/hq issue 044): module.json's `build.on` declares N8N_BASE
 # as the upstream image by digest, and the mesh hands the build its own copy (ADR 0097).
 ARG N8N_BASE
 FROM ${N8N_BASE}
 USER root
 # - `media` (GID 2000), with `node` in it: the shared media library is group-writable by the
 #   operator's media group, and a workflow files downloads into it. A container resource cannot add
 #   a supplementary group, so the image's own /etc/group carries it. 2000 is the operator's media
 #   group today; novox/hq 153 proposes reading it from the accessed data (${access:<id>:gid}).
 # - uuid, pinned to the version the workflows were written against: Code nodes require() it
 #   (NODE_FUNCTION_ALLOW_EXTERNAL=*), and a Code node can only require what is installed.
 RUN apk add --no-cache shadow \
 && groupadd -g 2000 media \
 && usermod -aG media node \
 && npm install -g uuid@14.0.1
 USER node
@@ -14,47 +14,64 @@
    },
    "route": {
      "label": "n8n",
-      "port": 5682
+      "endpoint": "web"
    }
  },
  "binds": {
-    "postgres-database": "/var/lib/n8n/database.json",
+    "postgres-database": "${dir:state}/database.json",
-    "route": "/var/lib/n8n/route.json"
+    "route": "${dir:state}/route.json"
  },
  "secrets": {
-    "postgres-database": "/var/lib/n8n/database.secret"
+    "postgres-database": "${dir:state}/database.secret"
  },
  "own-secrets": {
    "basic-auth": "/var/lib/n8n/basic-auth.secret"
  },
  "accesses": [
    {
      "path": "/services/media",
      "mode": "read-write"
    }
  ],
  "listens": [
    {
-      "port": 5682,
+      "name": "web",
      "port": 5678,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the n8n editor and webhook endpoints over http; the public name n8n.novox.be is a route grant, and route-proxy reaches it on this published port"
+      "why": "the n8n editor, its REST API and the webhook endpoints workflows are triggered through; a public name is the route's"
    }
  ],
  "resources": [
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/n8n",
+      "mode": "0700",
-      "mode": "0700"
+      "place": "."
    },
    {
      "id": "data",
      "type": "directory",
      "path": "/services/n8n/n8n-data",
      "mode": "0700",
      "owner": "1000:1000"
    },
    {
      "id": "cache",
      "type": "directory",
      "mode": "0700",
      "owner": "999:999"
    },
    {
      "id": "database-secret",
      "type": "file",
      "path": "${dir:state}/n8n-database.secret",
      "mode": "0400",
      "owner": "1000:1000",
      "content": "${secret:postgres-database}"
    },
    {
      "id": "server-env",
      "type": "file",
-      "path": "/var/lib/n8n/server.env",
+      "path": "${dir:state}/server.env",
      "mode": "0600",
-      "content": "N8N_HOST=n8n.novox.be\nN8N_PORT=5678\nN8N_PROTOCOL=https\nWEBHOOK_URL=https://n8n.novox.be/\nN8N_BASIC_AUTH_ACTIVE=true\nN8N_BASIC_AUTH_USER=admin\nN8N_BASIC_AUTH_PASSWORD=${secret:basic-auth}\nNODE_FUNCTION_ALLOW_BUILTIN=*\nNODE_FUNCTION_ALLOW_EXTERNAL=*\nDB_TYPE=postgresdb\nDB_POSTGRESDB_HOST=${bound:postgres-database:at}\nDB_POSTGRESDB_PORT=${bound:postgres-database:port}\nDB_POSTGRESDB_DATABASE=${bound:postgres-database:as}\nDB_POSTGRESDB_USER=${bound:postgres-database:as}\nDB_POSTGRESDB_PASSWORD=${secret:postgres-database}\n"
+      "content": "N8N_HOST=${bound:route:name}\nN8N_PORT=5678\nN8N_PROTOCOL=https\nWEBHOOK_URL=https://${bound:route:name}/\nNODE_FUNCTION_ALLOW_BUILTIN=*\nNODE_FUNCTION_ALLOW_EXTERNAL=*\nDB_TYPE=postgresdb\nDB_POSTGRESDB_HOST=${bound:postgres-database:at}\nDB_POSTGRESDB_PORT=${bound:postgres-database:port}\nDB_POSTGRESDB_DATABASE=${bound:postgres-database:as}\nDB_POSTGRESDB_USER=${bound:postgres-database:as}\nDB_POSTGRESDB_PASSWORD_FILE=/run/secrets/database\n"
    },
    {
      "id": "net",
@@ -65,18 +82,61 @@
      "id": "server",
      "type": "container",
      "name": "n8n",
-      "image": "n8nio/n8n@sha256:4846eb2f4b874ab04cde7fc1e249d2ddaec66e9aea64439beb2972cfea88e3c0",
+      "artifact": "server",
      "network": "n8n",
      "env-file": [
-        "/var/lib/n8n/server.env"
+        "${dir:state}/server.env"
      ],
      "ports": [
        "5678"
      ],
      "volumes": [
-        "/services/n8n/n8n-data:/home/node/.n8n"
+        "${dir:data}:/home/node/.n8n",
        "${dir:state}/n8n-database.secret:/run/secrets/database:ro",
        "/services/media:/media-library"
      ]
    },
    {
      "id": "cache-server",
      "type": "container",
      "name": "n8n-redis",
      "image": "redis@sha256:8a1efc5f479551822b47424ccae982026b633f28818eab0387348120a61e10e2",
      "network": "n8n",
      "args": [
        "redis-server",
        "--appendonly",
        "yes"
      ],
-      "secrets-in-environment": "n8n's loader honours <VAR>_FILE for every setting; convertible, awaiting a bed that proves it (N8N_BASIC_AUTH_* was removed in n8n 1.0 and is likely dead)"
+      "volumes": [
        "${dir:cache}:/data"
      ]
    },
    {
      "id": "browser",
      "type": "container",
      "name": "n8n-selenium",
      "image": "selenium/standalone-chrome@sha256:9ae1c78e9b2ca9fe4b22e57873b5ee34aeb8e814e3122293eef4c3abe4c5f448",
      "network": "n8n",
      "env": {
        "SE_ENABLE_TRACING": "false",
        "SE_NODE_MAX_SESSIONS": "5",
        "SE_NODE_OVERRIDE_MAX_SESSIONS": "true"
      }
    }
-  ]
+  ],
  "build": {
    "on": [
      {
        "arg": "N8N_BASE",
        "image": "n8nio/n8n@sha256:4846eb2f4b874ab04cde7fc1e249d2ddaec66e9aea64439beb2972cfea88e3c0"
      }
    ],
    "artifacts": [
      {
        "name": "server",
        "kind": "image",
        "from": "Dockerfile"
      }
    ]
  }
 }
@@ -9,8 +9,11 @@
 #
 # Unlike every other module's Dockerfile, this builds no TypeScript and uses no mesh base image:
 # the module's code is the server, which upstream already built. There is no BUILD_BASE here on
-# purpose — nothing is compiled.
+# purpose — nothing is compiled. The upstream image is declared in the manifest under build.on and
-FROM nats@sha256:b83efabe3e7def1e0a4a31ec6e078999bb17c80363f881df35edc70fcb6bb927
+# arrives as NATS_BASE, like every other base the mesh copies into its own store before a build
 # (novox/hq ADR 0097); the digest above is the index one for the reason given.
 ARG NATS_BASE
 FROM ${NATS_BASE}
 COPY entrypoint.sh /usr/local/bin/mesh-nats-entrypoint
 RUN chmod 0755 /usr/local/bin/mesh-nats-entrypoint
@@ -21,6 +21,7 @@
  "consumes": [],
  "listens": [
    {
      "name": "bus",
      "port": 4222,
      "protocol": "tcp",
      "from": "mesh",
@@ -47,7 +48,7 @@
      "id": "server-conf",
      "type": "file",
      "path": "/var/lib/nats-module/conf/nats.conf",
-      "content": "# The nats module's own server settings. Declared by the module, because a port, a TLS path\n# and a store directory are properties of the container this module raises: they live in its\n# image and its mounts and change when it does.\n#\n# The mesh writes accounts.conf beside this one and nothing else. A controller that wrote the\n# whole file would have to be kept in step with a Dockerfile it never sees.\n\nport: 4222\nhttp: 127.0.0.1:8222\n\ntls {\n  cert_file: \"/tls/tls.crt\"\n  key_file: \"/tls/tls.key\"\n  ca_file: \"/tls/ca.crt\"\n}\n\n# **No `verify`, deliberately, and it was `verify: true` until a probe ran this image.** That\n# setting makes the server demand a *client* certificate, and nothing in the mesh presents one: a\n# host pins this server's exact certificate and authenticates with the password the mesh minted\n# (novox/hq ADR 0004, design 25 \u00a74), and so does a module's runtime. With it on, every connection\n# in the mesh is refused at the TLS handshake, before any password is looked at \u2014 and the error is\n# \"client didn't provide a certificate\", which reads as a client fault.\n#\n# TLS is still required: a tls block is what makes it required, and verify only decides whether\n# client certificates are checked. What is given up is a second factor the mesh has no machinery\n# to issue or rotate \u2014 a certificate per module per node \u2014 and what is kept is stronger than a\n# name check in both directions: an exact pin outward, a per-user password inward.\n\njetstream {\n  store_dir: \"/data\"\n}\n\n# Every user of the mesh, composed by the controller and rewritten whenever a module is\n# assigned, a node enrols or a person's access changes.\n#\n# **Relative, and in this same directory, because it has to be.** An absolute include path is\n# resolved relative to the including file's directory, not from the root: nats-server given\n# `include /etc/nats/accounts.conf` from /etc/nats-server/nats.conf looks for\n# /etc/nats-server/etc/nats/accounts.conf and refuses to start. Verified against the server.\ninclude accounts.conf\n",
+      "content": "# The nats module's own server settings. Declared by the module, because a port, a TLS path\n# and a store directory are properties of the container this module raises: they live in its\n# image and its mounts and change when it does.\n#\n# The mesh writes accounts.conf beside this one and nothing else. A controller that wrote the\n# whole file would have to be kept in step with a Dockerfile it never sees.\n\nport: 4222\nhttp: 127.0.0.1:8222\n\n# The mesh's own broker certificate \u2014 the one every machine already pins by fingerprint and the\n# controller already trusts (MESH_BROKER_CERTIFICATE). Serving the new bus with it means no\n# machine's pin changes when it moves, and no second certificate exists to be wrong about.\ntls {\n  cert_file: \"/tls/tls.crt\"\n  key_file: \"/tls/tls.key\"\n}\n\n# **No `verify`, deliberately, and it was `verify: true` until a probe ran this image.** That\n# setting makes the server demand a *client* certificate, and nothing in the mesh presents one: a\n# host pins this server's exact certificate and authenticates with the password the mesh minted\n# (novox/hq ADR 0004, design 25 \u00a74), and so does a module's runtime. With it on, every connection\n# in the mesh is refused at the TLS handshake, before any password is looked at \u2014 and the error is\n# \"client didn't provide a certificate\", which reads as a client fault.\n#\n# TLS is still required: a tls block is what makes it required, and verify only decides whether\n# client certificates are checked. What is given up is a second factor the mesh has no machinery\n# to issue or rotate \u2014 a certificate per module per node \u2014 and what is kept is stronger than a\n# name check in both directions: an exact pin outward, a per-user password inward.\n\njetstream {\n  store_dir: \"/data\"\n}\n\n# Every user of the mesh, composed by the controller and rewritten whenever a module is\n# assigned, a node enrols or a person's access changes.\n#\n# **Relative, and in this same directory, because it has to be.** An absolute include path is\n# resolved relative to the including file's directory, not from the root: nats-server given\n# `include /etc/nats/accounts.conf` from /etc/nats-server/nats.conf looks for\n# /etc/nats-server/etc/nats/accounts.conf and refuses to start. Verified against the server.\ninclude accounts.conf\n",
      "mode": "0644"
    },
    {
@@ -61,18 +62,24 @@
      "volumes": [
        "/var/lib/mesh-broker-nats:/data",
        "/var/lib/nats-module/conf:/etc/nats:ro",
-        "/var/lib/mesh-broker-nats-tls:/tls:ro"
+        "/var/lib/mesh-broker-tls:/tls:ro"
      ],
      "artifact": "server"
    }
  ],
  "accesses": [
    {
-      "path": "/var/lib/mesh-broker-nats-tls",
+      "path": "/var/lib/mesh-broker-tls",
      "mode": "read"
    }
  ],
  "build": {
    "on": [
      {
        "arg": "NATS_BASE",
        "image": "nats@sha256:b83efabe3e7def1e0a4a31ec6e078999bb17c80363f881df35edc70fcb6bb927"
      }
    ],
    "artifacts": [
      {
        "name": "server",
@@ -13,7 +13,7 @@
    },
    "route": {
      "label": "drive",
-      "port": 80
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -38,6 +38,7 @@
  ],
  "listens": [
    {
      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/nodered
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts mqtt/probe.ts mqtt/connection.ts mqtt/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/nodered/dist /app/modules/nodered/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/nodered/dist/tools/index.js
 # NOT dist/mqtt/index.js: that is a step the host runs to completion, named by the `mqtt`
 # container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
 # serving sidecar too, and exit it.
@@ -3,7 +3,8 @@
 //
 // Node-RED exposes a runtime admin API under its base URL: GET/POST /flows for the whole flow
 // configuration, GET /nodes for installed node modules. A default install has no auth; when
-// adminAuth is on, a bearer token (minted at /auth/token) is required.
+// adminAuth is on, a bearer token is required — the module's settings accept the mesh-minted
 // api-token, which the runtime config file carries as `token`.
 import { readFileSync } from "node:fs";
@@ -81,6 +82,35 @@ export class NodeRedClient {
    return modules.map((m) => ({ name: m.name, version: m.version, types: m.types ?? [] }));
  }
  /** The whole flow configuration with its revision (API v2), for a deploy that must not clobber
   *  a change made meanwhile. */
  async flowsWithRev(): Promise<{ rev: string; flows: any[] }> {
    const body = await this.req("/flows", { headers: this.headers({ "Node-RED-API-Version": "v2" }) });
    return { rev: String(body?.rev ?? ""), flows: Array.isArray(body?.flows) ? body.flows : [] };
  }
  /** A node's stored credentials as Node-RED shows them: plain fields, and `has_<field>` for secret ones. */
  async credentials(type: string, id: string): Promise<{ user?: string; has_password?: boolean }> {
    return (await this.req(`/credentials/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, { headers: this.headers() })) ?? {};
  }
  /**
   * Deploy the flow configuration read at `rev`. Node-RED answers 409 when the flows changed since,
   * rather than overwriting what someone deployed in between. A node carrying `credentials` has them
   * stored (encrypted) and counts as changed, so a "nodes" deploy restarts it and nothing else.
   */
  async deployFlowsAt(rev: string, config: any[], type = "nodes"): Promise<void> {
    await this.req("/flows", {
      method: "POST",
      headers: this.headers({
        "Content-Type": "application/json",
        "Node-RED-API-Version": "v2",
        "Node-RED-Deployment-Type": type,
      }),
      body: JSON.stringify({ rev, flows: config }),
    });
  }
  /**
   * Replace the whole flow configuration and deploy. Returns the new revision. `type` maps to
   * Node-RED's deployment types — "full" (default), "nodes", or "flows".
@@ -88,8 +118,13 @@ export class NodeRedClient {
  async deployFlows(config: any[], type = "full"): Promise<{ rev?: string; nodeCount: number }> {
    const body = await this.req("/flows", {
      method: "POST",
-      headers: this.headers({ "Content-Type": "application/json", "Node-RED-Deployment-Type": type }),
+      // v2 answers { rev }; v1 answers 204 with no body, which req() cannot parse.
-      body: JSON.stringify(config),
+      headers: this.headers({
        "Content-Type": "application/json",
        "Node-RED-API-Version": "v2",
        "Node-RED-Deployment-Type": type,
      }),
      body: JSON.stringify({ flows: config }),
    });
    return { rev: body?.rev, nodeCount: config.length };
  }
@@ -5,6 +5,8 @@
    "flows.deployed"
  ],
  "own-secrets": {
    "admin": "/var/lib/mesh/nodered/admin",
    "api-token": "/var/lib/mesh/nodered/api-token",
    "broker": "/var/lib/mesh/nodered/broker"
  },
  "capabilities": [
@@ -12,6 +14,7 @@
  ],
  "listens": [
    {
      "name": "web",
      "port": 1880,
      "protocol": "tcp",
      "from": "mesh",
@@ -25,26 +28,63 @@
      "path": "/var/lib/mesh/nodered",
      "mode": "0700"
    },
    {
      "id": "state",
      "type": "directory",
      "mode": "0700",
      "place": "."
    },
    {
      "id": "data",
      "type": "directory",
      "path": "/services/nodered/data",
      "mode": "0700",
      "owner": "1000:1000"
    },
    {
      "id": "written",
      "type": "directory",
      "mode": "0700"
    },
    {
      "id": "settings-code",
      "type": "file",
      "path": "${dir:state}/settings.js",
      "mode": "0600",
      "owner": "1000:1000",
      "content": "// Node-RED's settings, written by the mesh from the nodered module. What an assignment may change\n// is settings.json beside this file (merged key by key); the credentials are the mesh's secrets and\n// reach Node-RED only through this file. The flows' own credentials stay encrypted in the user\n// directory under the key Node-RED keeps there (.config.runtime.json), which is data, not this.\nconst fs = require(\"fs\");\nconst path = require(\"path\");\nconst crypto = require(\"crypto\");\n\nconst ADMIN_PASSWORD = \"${secret:admin}\";\nconst API_TOKEN = \"${secret:api-token}\";\nconst ADMIN = { username: \"admin\", permissions: \"*\" };\n\nconst settings = JSON.parse(fs.readFileSync(path.join(__dirname, \"settings.json\"), \"utf8\"));\n// The mesh's keys, not Node-RED's: endpoints lands in every merged file; timeZone is the\n// assignment's way to set the zone flows schedule and format in; mqtt names the broker nodes the\n// module's MQTT step keeps pointed at the mesh's broker; topics is what nodered asks the broker for.\nif (settings.timeZone) process.env.TZ = settings.timeZone;\ndelete settings.timeZone;\ndelete settings.endpoints;\ndelete settings.mqtt;\ndelete settings.topics;\n\nfunction same(a, b) {\n  const x = crypto.createHash(\"sha256\").update(String(a)).digest();\n  const y = crypto.createHash(\"sha256\").update(String(b)).digest();\n  return crypto.timingSafeEqual(x, y);\n}\n\n// The admin secret is a password, or, accepted from an existing install, the bcrypt hash its\n// settings held, so the password people already use keeps working.\nfunction passwordMatches(given) {\n  if (/^\\$2[aby]\\$\\d\\d\\$/.test(ADMIN_PASSWORD)) return require(\"bcryptjs\").compare(String(given), ADMIN_PASSWORD);\n  return Promise.resolve(same(given, ADMIN_PASSWORD));\n}\n\nmodule.exports = Object.assign(settings, {\n  uiPort: 1880,\n  adminAuth: {\n    type: \"credentials\",\n    users: (username) => Promise.resolve(username === ADMIN.username ? ADMIN : null),\n    authenticate: (username, password) =>\n      username === ADMIN.username\n        ? passwordMatches(password).then((ok) => (ok ? ADMIN : null))\n        : Promise.resolve(null),\n    // The module's own tools call the admin API with this bearer token.\n    tokens: (token) => Promise.resolve(same(token, API_TOKEN) ? { username: \"mesh\", permissions: \"*\" } : null),\n  },\n});\n"
    },
    {
      "id": "settings",
      "type": "file",
      "path": "${dir:state}/settings.json",
      "mode": "0600",
      "owner": "1000:1000",
      "merge": "json",
      "content": "{\n  \"flowFile\": \"flows.json\",\n  \"flowFilePretty\": true,\n  \"diagnostics\": { \"enabled\": true, \"ui\": true },\n  \"runtimeState\": { \"enabled\": false, \"ui\": false },\n  \"logging\": { \"console\": { \"level\": \"info\", \"metrics\": false, \"audit\": false } },\n  \"exportGlobalContextKeys\": false,\n  \"externalModules\": {},\n  \"editorTheme\": { \"projects\": { \"enabled\": false } },\n  \"functionExternalModules\": true,\n  \"debugMaxLength\": 1000,\n  \"mqttReconnectTime\": 15000,\n  \"serialReconnectTime\": 15000\n}\n"
    },
    {
      "id": "server",
      "type": "container",
      "name": "nodered",
-      "image": "nodered/node-red@sha256:02a2b92a41b73d2bc388238b86e4fcaab7fb5466373adb24e1df6aa5845265ff",
+      "image": "nodered/node-red@sha256:a649dd711d55490151a2c39a8e48ad0c44325488fbc0e66315f2d2e19e5e1ace",
      "env": {
        "TZ": "Etc/UTC"
      },
      "ports": [
        "1880"
      ],
      "args": [
        "--settings",
        "/data/settings.js"
      ],
      "volumes": [
-        "/services/nodered/data:/data"
+        "${dir:data}:/data",
        "${dir:state}/settings.js:/data/settings.js:ro",
        "${dir:state}/settings.json:/data/settings.json:ro"
      ],
      "restart-on": [
        "settings-code",
        "settings"
      ]
    },
    {
@@ -52,8 +92,7 @@
      "type": "file",
      "path": "/var/lib/mesh/nodered/config.json",
      "mode": "0600",
-      "content": "{}\n",
+      "content": "{\n  \"token\": \"${secret:api-token}\"\n}\n"
      "merge": "json"
    },
    {
      "id": "runtime",
@@ -66,26 +105,66 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NODERED_URL": "http://127.0.0.1:1880",
+        "MESH_NODERED_URL": "http://127.0.0.1:${port:1880}",
        "MESH_NODERED_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
    },
    {
      "id": "mqtt",
      "type": "container",
      "name": "mesh-nodered-mqtt",
      "network": "host",
      "run-once": true,
      "volumes": [
        "/var/lib/mesh/nodered/config.json:/run/config/config.json:ro",
        "${dir:written}:/var/lib/nodered-provisions",
        "${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
        "${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
        "${dir:state}/settings.json:/run/provisions/settings.json:ro"
      ],
      "env": {
        "MESH_NODERED_URL": "http://127.0.0.1:${port:1880}",
        "MESH_NODERED_CONFIG_FILE": "/run/config/config.json",
        "MESH_PROVISIONS_DIR": "/run/provisions",
        "MESH_WRITTEN_DIR": "/var/lib/nodered-provisions"
      },
      "args": [
        "run",
        "/app/modules/nodered/dist/mqtt/index.js"
      ],
      "restart-on": [
        "bound-mqtt-topic",
        "secret-mqtt-topic",
        "settings"
      ],
      "artifact": "runtime"
    }
  ],
  "requires": [
    "mqtt-topic",
    "route"
  ],
  "contributes": {
    "mqtt-topic": {
      "topics": [
        "#"
      ]
    },
    "route": {
      "label": "nodered",
-      "port": 1880
+      "endpoint": "web"
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/nodered/route.json"
+    "route": "${dir:state}/route.json",
    "mqtt-topic": "${dir:state}/mqtt-topic.json"
  },
  "secrets": {
    "mqtt-topic": "${dir:state}/mqtt-topic.secret"
  },
  "build": {
    "on": [
@@ -0,0 +1,232 @@
 // Node-RED's MQTT broker config node, pointed at the broker the mesh bound — `mqtt-topic`.
 //
 // **Why a step.** Node-RED keeps a broker as a config node in its flows (`flows.json`) and the login
 // and password in its encrypted credentials file, both of them Node-RED's to write. So this reads the
 // binding and the pair credential and makes the broker node say the same thing through Node-RED's
 // admin API — `GET /flows`, then `POST /flows` with the changed node and its `credentials`, deployed
 // as "nodes" so only what changed restarts — with the module's own `api-token`.
 //
 // **Which broker nodes are the mesh's.** Never guessed: a flow may talk to a broker that has nothing
 // to do with this mesh. The step owns the node it creates itself (id `mesh-mqtt-topic`, "mesh:
 // mqtt-topic") and the ones an assignment names in settings (`mqtt.brokers`: node ids — how ace's
 // existing broker node, which every one of its MQTT flows uses, is handed over). With none named and
 // none made yet, it makes one, so a fresh Node-RED has a broker the flows can pick.
 //
 // **Only the connection, and only when it differs.** Host, port, TLS off (the broker serves plain
 // MQTT), login, password. Every other field of the node — client id, keepalive, birth/close/will
 // messages — is left as it is. Node-RED never hands a stored password back, so the step keeps a
 // digest of what it last wrote: equal host/port/login and an equal digest is "already as the mesh
 // says".
 //
 // **Nothing loses its connection without someone seeing it.** The broker is asked first whether it
 // takes the delivered login; if not, nothing is written and the step fails saying why.
 //
 // Pure logic over two seams (Node-RED, the broker), tested against fakes (test/mqtt.test.ts).
 import { createHash } from "node:crypto";
 import type { Probe } from "./probe.js";
 export const PROVISION = "mqtt-topic";
 /** The id and name of the broker node the step makes when none is named. */
 export const MESH_BROKER_ID = "mesh-mqtt-topic";
 export const MESH_BROKER_NAME = "mesh: mqtt-topic";
 /** What the mesh wrote at `binds.mqtt-topic`. */
 export interface Binding {
  provision?: string;
  from?: string;
  at?: string;
  as?: string;
  serves?: Record<string, unknown>;
 }
 export type Outcome =
  | { what: string; result: "unchanged"; note?: string }
  | { what: string; result: "written"; fields: string[]; note?: string }
  | { what: string; result: "refused"; problem: string };
 /** A flow node; a broker config node carries `broker`, `port`, `usetls`. */
 export interface FlowNode {
  id: string;
  type: string;
  [key: string]: unknown;
 }
 /** Node-RED's admin API, as the step uses it. */
 export interface NodeRed {
  /** The whole flow configuration and its revision (API v2). */
  flows(): Promise<{ rev: string; flows: FlowNode[] }>;
  /** A node's stored credentials as Node-RED shows them: the user, and only whether a password is set. */
  credentials(type: string, id: string): Promise<{ user?: string; has_password?: boolean }>;
  /** Deploy the configuration against the revision it was read at; "nodes" restarts only what changed. */
  deploy(rev: string, flows: FlowNode[]): Promise<void>;
 }
 export interface Marks {
  get(name: string): Promise<string | undefined>;
  set(name: string, digest: string): Promise<void>;
 }
 export interface Deps {
  nodered: NodeRed;
  probe: Probe;
  marks: Marks;
 }
 export interface Wanted {
  host: string;
  port: number;
  user: string;
  password: string;
 }
 export function digest(...parts: (string | number)[]): string {
  return createHash("sha256").update(parts.map(String).join("\u0000")).digest("hex");
 }
 function isLoopback(host: string): boolean {
  const h = host.toLowerCase();
  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
 }
 /**
 * The broker and login the mesh says Node-RED uses. A loopback `at` — what the mesh hands a machine
 * that is not on the private network — is refused: from Node-RED's own container it is Node-RED.
 */
 export function wanted(binding: Binding | undefined, credential: string | undefined): { ok: true; want: Wanted } | { ok: false; problem: string } {
  if (!binding) return { ok: false, problem: `no binding for ${PROVISION} was delivered — the mesh writes it before this step runs` };
  const host = typeof binding.at === "string" ? binding.at.trim() : "";
  if (!host) return { ok: false, problem: `the ${PROVISION} binding names no host (at)` };
  if (isLoopback(host)) {
    return {
      ok: false,
      problem:
        `the ${PROVISION} binding says the broker is at ${host}, which from Node-RED's own container is Node-RED ` +
        `itself; put the machine on the private network so the broker has an address Node-RED can dial`,
    };
  }
  const port = Number(binding.serves?.port);
  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
    return { ok: false, problem: `the ${PROVISION} binding serves no usable port (${String(binding.serves?.port)})` };
  }
  const scheme = binding.serves?.scheme;
  if (scheme !== undefined && scheme !== "mqtt") return { ok: false, problem: `the ${PROVISION} binding serves scheme ${String(scheme)}; this step writes plain MQTT` };
  const user = typeof binding.as === "string" ? binding.as.trim() : "";
  if (!user) return { ok: false, problem: `the ${PROVISION} binding names no login (as)` };
  const password = (credential ?? "").replace(/\n$/, "");
  if (!password) return { ok: false, problem: `the ${PROVISION} credential is empty or was not delivered` };
  return { ok: true, want: { host, port, user, password } };
 }
 /** The broker node ids an assignment named in settings (`mqtt.brokers`), or none. */
 export function namedBrokers(settings: unknown): string[] {
  const brokers = (settings as { mqtt?: { brokers?: unknown } } | undefined)?.mqtt?.brokers;
  return Array.isArray(brokers) ? brokers.filter((b): b is string => typeof b === "string" && b.length > 0) : [];
 }
 /** A new broker node, Node-RED 5's defaults, pointed at the broker. */
 export function newBrokerNode(want: Wanted): FlowNode {
  return {
    id: MESH_BROKER_ID, type: "mqtt-broker", name: MESH_BROKER_NAME,
    broker: want.host, port: String(want.port), clientid: "", autoConnect: true, usetls: false,
    protocolVersion: "4", keepalive: "60", cleansession: true, autoUnsubscribe: true,
    birthTopic: "", birthQos: "0", birthRetain: "false", birthPayload: "", birthMsg: {},
    closeTopic: "", closeQos: "0", closeRetain: "false", closePayload: "", closeMsg: {},
    willTopic: "", willQos: "0", willRetain: "false", willPayload: "", willMsg: {},
    userProps: "", sessionExpiry: "",
  };
 }
 const markFor = (id: string, w: Wanted): string => digest("nodered-mqtt", id, w.host, w.port, w.user, w.password);
 function scrub(err: unknown, secret: string): string {
  let text = err instanceof Error ? err.message : String(err);
  for (const form of new Set([secret, encodeURIComponent(secret)])) text = text.split(form).join("***");
  return text;
 }
 /**
 * Bring the mesh's broker nodes in line with the binding: one outcome per node. Never throws. A node
 * the settings name that is not in the flows is refused (the others are still put right).
 */
 export async function reconcileBrokers(deps: Deps, binding: Binding | undefined, credential: string | undefined, named: readonly string[]): Promise<Outcome[]> {
  const w = wanted(binding, credential);
  if ("problem" in w) return [{ what: "mqtt", result: "refused", problem: w.problem }];
  const want = w.want;
  let note: string | undefined;
  try {
    const probe = await deps.probe(want.host, want.port, want.user, want.password, "#");
    if (probe.connack === 4 || probe.connack === 5) {
      return [{
        what: "mqtt",
        result: "refused",
        problem:
          `the broker at ${want.host}:${want.port} does not (yet) take the login ${want.user} with the delivered password ` +
          `(CONNACK ${probe.connack}); mosquitto's provisioner creates it from the grant — nothing was written`,
      }];
    }
    if (probe.connack !== 0) return [{ what: "mqtt", result: "refused", problem: `the broker at ${want.host}:${want.port} answered CONNACK ${probe.connack}; nothing was written` }];
    if (probe.suback === 0x80) note = `warning: ${want.user} may not subscribe to every topic; flows subscribing outside its grant will get nothing`;
  } catch (err) {
    return [{ what: "mqtt", result: "refused", problem: `the broker at ${want.host}:${want.port} could not be asked: ${scrub(err, want.password)}; nothing was written` }];
  }
  const outcomes: Outcome[] = [];
  for (let attempt = 0; attempt < 2; attempt++) {
    outcomes.length = 0;
    try {
      const { rev, flows } = await deps.nodered.flows();
      const targets = named.length > 0 ? [...named] : [MESH_BROKER_ID];
      const changed: { id: string; fields: string[] }[] = [];
      for (const id of targets) {
        let node = flows.find((n) => n.id === id);
        if (node && node.type !== "mqtt-broker") {
          outcomes.push({ what: `broker ${id}`, result: "refused", problem: `node ${id} is a ${node.type}, not an mqtt-broker` });
          continue;
        }
        if (!node) {
          if (id !== MESH_BROKER_ID) {
            outcomes.push({ what: `broker ${id}`, result: "refused", problem: `the settings name broker node ${id}, and Node-RED's flows have no such node` });
            continue;
          }
          node = newBrokerNode(want);
          flows.push(node);
          node.credentials = { user: want.user, password: want.password };
          changed.push({ id, fields: ["node"] });
          continue;
        }
        const fields: string[] = [];
        if (String(node.broker ?? "") !== want.host) fields.push("broker");
        if (Number(node.port ?? 0) !== want.port) fields.push("port");
        if (node.usetls === true) fields.push("usetls");
        const creds = await deps.nodered.credentials("mqtt-broker", id);
        if ((creds.user ?? "") !== want.user) fields.push("user");
        if (!creds.has_password || (await deps.marks.get(`broker-${id}`)) !== markFor(id, want)) fields.push("password");
        if (fields.length === 0) {
          outcomes.push(note ? { what: `broker ${id}`, result: "unchanged", note } : { what: `broker ${id}`, result: "unchanged" });
          continue;
        }
        node.broker = want.host;
        node.port = String(want.port);
        node.usetls = false;
        node.credentials = { user: want.user, password: want.password };
        changed.push({ id, fields });
      }
      if (changed.length > 0) {
        await deps.nodered.deploy(rev, flows);
        for (const c of changed) {
          await deps.marks.set(`broker-${c.id}`, markFor(c.id, want));
          outcomes.push({ what: `broker ${c.id}`, result: "written", fields: c.fields, ...(note ? { note } : {}) });
        }
      }
      return outcomes;
    } catch (err) {
      // A deploy against a revision someone else changed meanwhile (409) is read again once.
      if (attempt === 0 && /\b409\b/.test(String(err))) continue;
      return [...outcomes, { what: "mqtt", result: "refused", problem: scrub(err, want.password) }];
    }
  }
  return outcomes;
 }
@@ -0,0 +1,102 @@
 // nodered's MQTT step — run once by the host after Node-RED starts, and again whenever the
 // `mqtt-topic` binding, its pair credential or the settings change (the container's `restart-on`,
 // novox/hq ADR 0099). It points the mesh's broker config nodes at the broker the mesh bound, through
 // Node-RED's admin API (connection.ts). It connects to no mesh broker.
 //
 // Exits non-zero when anything could not be put right, so the node reports the step failed and the
 // host runs it again on the next apply. Declared last in the manifest, so its failing gates nothing
 // else of nodered's (novox/hq ADR 0136). Never prints a password.
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { NodeRedClient } from "../client.js";
 import { namedBrokers, reconcileBrokers, type Binding, type Marks } from "./connection.js";
 import { probeBroker } from "./probe.js";
 const dir = process.env.MESH_PROVISIONS_DIR ?? "/run/provisions";
 const writtenDir = process.env.MESH_WRITTEN_DIR ?? "/var/lib/nodered-provisions";
 const waitSeconds = Number(process.env.MESH_NODERED_WAIT_SECONDS ?? "180");
 const readIfThere = (path: string): Promise<string | undefined> => readFile(path, "utf8").catch(() => undefined);
 const parse = <T>(raw: string | undefined): T | undefined => {
  if (raw === undefined) return undefined;
  try {
    return JSON.parse(raw) as T;
  } catch {
    return undefined;
  }
 };
 const marks: Marks = {
  async get(name) {
    return (await readIfThere(join(writtenDir, `${name}.digest`)))?.trim() || undefined;
  },
  async set(name, value) {
    await mkdir(writtenDir, { recursive: true, mode: 0o700 });
    const path = join(writtenDir, `${name}.digest`);
    await writeFile(`${path}.tmp`, `${value}\n`, { mode: 0o600 });
    await rename(`${path}.tmp`, path);
  },
 };
 let client: NodeRedClient;
 try {
  client = NodeRedClient.fromEnv();
 } catch (err) {
  console.error(`[nodered-mqtt] ${err instanceof Error ? err.message : String(err)}`);
  process.exit(1);
 }
 /** Node-RED answers the admin API once its flows are loaded and the token is good. */
 async function ready(): Promise<boolean> {
  const until = Date.now() + waitSeconds * 1000;
  for (;;) {
    try {
      await client.flowsWithRev();
      return true;
    } catch (err) {
      if (/\b(401|403)\b/.test(String(err))) {
        console.error("[nodered-mqtt] Node-RED refuses the api-token — settings.js and this step disagree");
        return false;
      }
    }
    if (Date.now() >= until) return false;
    await new Promise((r) => setTimeout(r, 2000));
  }
 }
 if (!(await ready())) {
  console.error(`[nodered-mqtt] Node-RED's admin API did not answer at ${client.baseUrl} within ${waitSeconds}s`);
  process.exit(1);
 }
 const binding = parse<Binding>(await readIfThere(join(dir, "mqtt-topic.json")));
 const secret = await readIfThere(join(dir, "mqtt-topic.secret"));
 const settings = parse<unknown>(await readIfThere(join(dir, "settings.json")));
 const outcomes = await reconcileBrokers(
  {
    nodered: {
      flows: () => client.flowsWithRev(),
      credentials: (type, id) => client.credentials(type, id),
      deploy: (rev, flows) => client.deployFlowsAt(rev, flows, "nodes"),
    },
    probe: probeBroker,
    marks,
  },
  binding,
  secret,
  namedBrokers(settings),
 );
 let failed = 0;
 for (const o of outcomes) {
  if (o.result === "unchanged") console.log(`[nodered-mqtt] ${o.what}: already as the mesh says${o.note ? ` — ${o.note}` : ""}`);
  else if (o.result === "written") console.log(`[nodered-mqtt] ${o.what}: wrote ${o.fields.join(", ")}${o.note ? ` — ${o.note}` : ""}`);
  else {
    failed++;
    console.error(`[nodered-mqtt] ${o.what}: ${o.problem}`);
  }
 }
 process.exitCode = failed > 0 ? 1 : 0;
@@ -0,0 +1,117 @@
 // Ask the broker, before Node-RED is told anything, whether it takes the login and password the
 // mesh delivered — and whether that login may subscribe to every topic, as flows expect.
 //
 // One MQTT 3.1.1 session: CONNECT (clean, a throwaway client id, so no flow's session is taken
 // over), read the CONNACK, optionally SUBSCRIBE once and read the SUBACK, DISCONNECT. No dependency:
 // the handful of bytes MQTT needs for this are written here.
 import { randomBytes } from "node:crypto";
 import { connect } from "node:net";
 export interface ProbeResult {
  /** 0 accepted; 4 bad username or password; 5 not authorised. */
  connack: number;
  /** The SUBACK return code for the filter asked about: 0–2 granted, 0x80 refused. */
  suback?: number;
 }
 export type Probe = (host: string, port: number, username: string, password: string, subscribe?: string) => Promise<ProbeResult>;
 function str(v: string): Buffer {
  const b = Buffer.from(v, "utf8");
  const len = Buffer.alloc(2);
  len.writeUInt16BE(b.length);
  return Buffer.concat([len, b]);
 }
 function packet(type: number, body: Buffer): Buffer {
  let remaining = body.length;
  const lenBytes: number[] = [];
  do {
    let byte = remaining % 128;
    remaining = Math.floor(remaining / 128);
    if (remaining > 0) byte |= 0x80;
    lenBytes.push(byte);
  } while (remaining > 0);
  return Buffer.concat([Buffer.from([type, ...lenBytes]), body]);
 }
 /** The first complete packet in `buf`: its type byte, its body, and how many bytes it took. */
 export function firstPacket(buf: Buffer): { type: number; body: Buffer; used: number } | undefined {
  if (buf.length < 2) return undefined;
  let length = 0;
  let multiplier = 1;
  let i = 1;
  for (;;) {
    if (i >= buf.length) return undefined;
    const byte = buf[i++];
    length += (byte & 0x7f) * multiplier;
    if ((byte & 0x80) === 0) break;
    multiplier *= 128;
    if (i > 4) throw new Error("malformed MQTT remaining length");
  }
  if (buf.length < i + length) return undefined;
  return { type: buf[0], body: buf.subarray(i, i + length), used: i + length };
 }
 export const probeBroker: Probe = (host, port, username, password, subscribe) => {
  const connectBody = Buffer.concat([
    str("MQTT"),
    Buffer.from([4, 0xc2, 0, 10]), // level 4 (3.1.1); username + password + clean session; keepalive 10s
    str(`mesh-probe-${randomBytes(6).toString("hex")}`),
    str(username),
    str(password),
  ]);
  return new Promise((resolve, reject) => {
    const socket = connect({ host, port });
    let buf = Buffer.alloc(0);
    const result: ProbeResult = { connack: -1 };
    const timer = setTimeout(() => {
      socket.destroy();
      reject(new Error(`no answer from the broker at ${host}:${port} within 10s`));
    }, 10_000);
    const finish = (): void => {
      clearTimeout(timer);
      if (result.connack === 0) socket.end(Buffer.from([0xe0, 0]));
      else socket.destroy();
      resolve(result);
    };
    socket.on("connect", () => socket.write(packet(0x10, connectBody)));
    socket.on("data", (chunk) => {
      buf = Buffer.concat([buf, chunk]);
      for (;;) {
        let p;
        try {
          p = firstPacket(buf);
        } catch (err) {
          clearTimeout(timer);
          socket.destroy();
          reject(err);
          return;
        }
        if (!p) return;
        buf = buf.subarray(p.used);
        const kind = p.type >> 4;
        if (kind === 2) {
          result.connack = p.body[1] ?? -1;
          if (result.connack !== 0 || !subscribe) return finish();
          // SUBSCRIBE, packet id 1, one filter at QoS 0.
          socket.write(packet(0x82, Buffer.concat([Buffer.from([0, 1]), str(subscribe), Buffer.from([0])])));
        } else if (kind === 9) {
          result.suback = p.body[2];
          return finish();
        }
      }
    });
    socket.on("error", (err) => {
      clearTimeout(timer);
      reject(err);
    });
    socket.on("close", () => {
      if (result.connack === -1) {
        clearTimeout(timer);
        reject(new Error(`the broker at ${host}:${port} closed the connection without answering`));
      }
    });
  });
 };
@@ -1,9 +1,14 @@
 {
  "name": "@novox/module-nodered",
  "version": "0.1.0",
-  "description": "nodered — flow-based automation. Its client and tools live here (novox/hq ADR 0039).",
+  "description": "nodered \u2014 flow-based automation. Its client and tools live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc client.ts tools/index.ts mqtt/probe.ts mqtt/connection.ts mqtt/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
    "typecheck": "tsc -p tsconfig.json",
    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
  },
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
@@ -0,0 +1,124 @@
 // What holds nodered's MQTT step (mqtt/connection.ts): the broker nodes the mesh owns — the one it
 // makes, or the ones settings name — are made to use the broker and login the mesh bound, only after
 // the broker takes that login; every other field of a node is kept; nothing is deployed when nothing
 // differs; a node that is not named is never touched; a loopback broker address is refused.
 //
 // Node-RED and the broker are fakes answering as the real ones do (admin API v2 of nodered/node-red
 // 5.0.7, the build ace runs).
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { MESH_BROKER_ID, namedBrokers, reconcileBrokers, type Binding, type FlowNode, type Marks, type NodeRed } from "../mqtt/connection.ts";
 import type { Probe } from "../mqtt/probe.ts";
 const MINTED = "mesh-minted-password";
 const binding = (at = "ace.internal"): Binding => ({ provision: "mqtt-topic", from: "ace", at, as: "mesh_ace_nodered", serves: { scheme: "mqtt", port: 1883 } });
 /** ace's flows, reduced: its one broker node (dead, zurag.be:1884) and a node that uses it. */
 function aceFlows(): FlowNode[] {
  return [
    { id: "2b0aece9c5f3b307", type: "mqtt-broker", name: "MQTT Broker", broker: "zurag.be", port: "1884", clientid: "", usetls: false, protocolVersion: "4", keepalive: "60" },
    { id: "fe0cae96f1e3ae4d", type: "mqtt in", topic: "stat/sonoff_office_light_switch/RESULT", broker: "2b0aece9c5f3b307", z: "t" },
    { id: "other-broker", type: "mqtt-broker", name: "someone else's", broker: "test.mosquitto.org", port: "1883" },
  ];
 }
 function fakeNodeRed(flows: FlowNode[], creds: Record<string, { user?: string; password?: string }> = {}) {
  let rev = "r1";
  const deploys: FlowNode[][] = [];
  const nodered: NodeRed = {
    async flows() {
      return { rev, flows: structuredClone(flows) };
    },
    async credentials(_type, id) {
      const c = creds[id] ?? {};
      return { user: c.user, has_password: Boolean(c.password) };
    },
    async deploy(at, next) {
      if (at !== rev) throw new Error("Node-RED /flows: 409 version_mismatch");
      for (const n of next) {
        if (n.credentials) creds[n.id] = { ...(creds[n.id] ?? {}), ...(n.credentials as object) };
      }
      flows.splice(0, flows.length, ...next.map(({ credentials: _c, ...n }) => n as FlowNode));
      deploys.push(next);
      rev = `r${deploys.length + 1}`;
    },
  };
  return { nodered, deploys, flows, creds };
 }
 const marks = (): Marks & { store: Map<string, string> } => {
  const store = new Map<string, string>();
  return { store, get: async (k) => store.get(k), set: async (k, v) => void store.set(k, v) };
 };
 const takes: Probe = async (_h, _p, user, pass) => ({ connack: user === "mesh_ace_nodered" && pass === MINTED ? 0 : 5, suback: 0 });
 test("ace: the named broker node is moved to the bound broker and login; the other broker is not touched", async () => {
  const f = fakeNodeRed(aceFlows(), { "2b0aece9c5f3b307": { user: "luffy", password: "old" }, "other-broker": { user: "x", password: "y" } });
  const m = marks();
  const out = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: m }, binding(), `${MINTED}\n`, ["2b0aece9c5f3b307"]);
  assert.deepEqual(out, [{ what: "broker 2b0aece9c5f3b307", result: "written", fields: ["broker", "port", "user", "password"] }]);
  const node = f.flows.find((n) => n.id === "2b0aece9c5f3b307");
  assert.deepEqual(node, { ...aceFlows()[0], broker: "ace.internal", port: "1883", usetls: false });
  assert.deepEqual(f.creds["2b0aece9c5f3b307"], { user: "mesh_ace_nodered", password: MINTED });
  assert.deepEqual(f.flows.find((n) => n.id === "other-broker"), aceFlows()[2]);
  assert.deepEqual(f.creds["other-broker"], { user: "x", password: "y" });
  // Only the changed node carried credentials in the deploy.
  assert.deepEqual(f.deploys[0].filter((n) => n.credentials).map((n) => n.id), ["2b0aece9c5f3b307"]);
  // Again: nothing differs, nothing is deployed.
  const again = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: m }, binding(), MINTED, ["2b0aece9c5f3b307"]);
  assert.deepEqual(again, [{ what: "broker 2b0aece9c5f3b307", result: "unchanged" }]);
  assert.equal(f.deploys.length, 1);
 });
 test("fresh: with nothing named, the step makes its own broker node", async () => {
  const f = fakeNodeRed([]);
  const out = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: marks() }, binding(), MINTED, []);
  assert.deepEqual(out, [{ what: `broker ${MESH_BROKER_ID}`, result: "written", fields: ["node"] }]);
  assert.equal(f.flows[0].type, "mqtt-broker");
  assert.equal(f.flows[0].broker, "ace.internal");
  assert.deepEqual(f.creds[MESH_BROKER_ID], { user: "mesh_ace_nodered", password: MINTED });
 });
 test("a login the broker does not take is never written", async () => {
  const f = fakeNodeRed(aceFlows());
  const out = await reconcileBrokers({ nodered: f.nodered, probe: async () => ({ connack: 5 }), marks: marks() }, binding(), MINTED, ["2b0aece9c5f3b307"]);
  assert.equal(out[0].result, "refused");
  assert.equal(f.deploys.length, 0);
 });
 test("a named node that is not there, or a loopback broker, is refused", async () => {
  const f = fakeNodeRed(aceFlows());
  const out = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: marks() }, binding(), MINTED, ["gone"]);
  assert.match((out[0] as { problem: string }).problem, /no such node/);
  const lo = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: marks() }, binding("127.0.0.1"), MINTED, []);
  assert.match((lo[0] as { problem: string }).problem, /Node-RED itself/);
  assert.equal(f.deploys.length, 0);
 });
 test("a deploy that raced another is read again once", async () => {
  const f = fakeNodeRed(aceFlows());
  let first = true;
  const racing: NodeRed = {
    ...f.nodered,
    async flows() {
      const got = await f.nodered.flows();
      if (first) {
        first = false;
        return { ...got, rev: "stale" };
      }
      return got;
    },
  };
  const out = await reconcileBrokers({ nodered: racing, probe: takes, marks: marks() }, binding(), MINTED, ["2b0aece9c5f3b307"]);
  assert.equal(out[0].result, "written");
  assert.equal(f.deploys.length, 1);
 });
 test("settings name broker nodes under mqtt.brokers", () => {
  assert.deepEqual(namedBrokers({ mqtt: { brokers: ["a", "", 3, "b"] } }), ["a", "b"]);
  assert.deepEqual(namedBrokers({ endpoints: {} }), []);
  assert.deepEqual(namedBrokers(undefined), []);
 });
@@ -8,5 +8,11 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "tools/index.ts"]
+  "include": [
    "client.ts",
    "tools/index.ts",
    "mqtt/probe.ts",
    "mqtt/connection.ts",
    "mqtt/index.ts"
  ]
 }
@@ -1,50 +0,0 @@
 {
  "module": "novox.be",
  "version": "1",
  "capabilities": [
    "container-runtime"
  ],
  "requires": [
    "route"
  ],
  "contributes": {
    "route": {
      "label": "@",
      "port": 4000
    }
  },
  "binds": {
    "route": "/var/lib/novox.be/route.json"
  },
  "listens": [
    {
      "port": 4000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the public website over http; the public name novox.be is a route grant, and route-proxy reaches it on this published port"
    }
  ],
  "resources": [
    {
      "id": "state",
      "type": "directory",
      "path": "/var/lib/novox.be",
      "mode": "0700"
    },
    {
      "id": "net",
      "type": "network",
      "name": "novox-be"
    },
    {
      "id": "server",
      "type": "container",
      "name": "novox-be",
      "image": "registry-api.novox.be/novox/www@sha256:aa7ed20a293e1d7444c5c5d59b6d8bdb382bad159559a22e006810e379cae69c",
      "network": "novox-be",
      "ports": [
        "8080"
      ]
    }
  ]
 }
@@ -15,6 +15,7 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 6789,
      "protocol": "tcp",
      "from": "mesh",
@@ -12,6 +12,7 @@
  ],
  "listens": [
    {
      "name": "api",
      "port": 11434,
      "protocol": "tcp",
      "from": "machine",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
      "name": "web",
      "port": 3579,
      "protocol": "tcp",
      "from": "mesh",
@@ -89,7 +90,7 @@
  "contributes": {
    "route": {
      "label": "ombi",
-      "port": 3579
+      "endpoint": "web"
    }
  },
  "binds": {
--- a/Show More
+++ b/Show More