Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jschoubben
|
50464217c6 |
@@ -9,13 +9,13 @@
|
||||
"model-access"
|
||||
],
|
||||
"binds": {
|
||||
"model-access": "${dir:state}/model.json"
|
||||
"model-access": "/var/lib/anthropic-consumer/model.json"
|
||||
},
|
||||
"secrets": {
|
||||
"model-access": "${dir:state}/access-token"
|
||||
"model-access": "/var/lib/anthropic-consumer/access-token"
|
||||
},
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/anthropic-consumer/broker"
|
||||
},
|
||||
"emits": [
|
||||
"usage.session"
|
||||
@@ -24,14 +24,14 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/anthropic-consumer",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/anthropic-consumer",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "claude-home",
|
||||
@@ -42,6 +42,7 @@
|
||||
{
|
||||
"id": "out",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/anthropic-consumer/out",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
@@ -55,7 +56,7 @@
|
||||
"/app/modules/anthropic-consumer/dist/apply/index.js"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:state}:/run/state"
|
||||
"/var/lib/anthropic-consumer:/run/state"
|
||||
],
|
||||
"env": {
|
||||
"MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/access-token",
|
||||
@@ -76,8 +77,8 @@
|
||||
"/app/modules/anthropic-consumer/dist/usage/index.js"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}:/run/state"
|
||||
"/var/lib/mesh/anthropic-consumer/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/anthropic-consumer:/run/state"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -9,13 +9,13 @@
|
||||
"model-access"
|
||||
],
|
||||
"binds": {
|
||||
"model-access": "${dir:mesh-state}/model.json"
|
||||
"model-access": "/var/lib/mesh/anthropic-manager/model.json"
|
||||
},
|
||||
"secrets": {
|
||||
"model-access": "${dir:mesh-state}/refresh-token"
|
||||
"model-access": "/var/lib/mesh/anthropic-manager/refresh-token"
|
||||
},
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/anthropic-manager/broker"
|
||||
},
|
||||
"emits": [
|
||||
"usage.read"
|
||||
@@ -24,13 +24,13 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/anthropic-manager",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "out",
|
||||
"type": "directory",
|
||||
"path": "${dir:mesh-state}/out",
|
||||
"path": "/var/lib/mesh/anthropic-manager/out",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
@@ -45,8 +45,8 @@
|
||||
"/app/modules/anthropic-manager/dist/refresh/index.js"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}:/run/state"
|
||||
"/var/lib/mesh/anthropic-manager/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/anthropic-manager:/run/state"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
"**"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:state}/broker"
|
||||
"broker": "/var/lib/audit-logger/broker"
|
||||
},
|
||||
"build": {
|
||||
"on": [
|
||||
@@ -33,12 +33,13 @@
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/audit-logger",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "trail",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/audit-logger/trail",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
@@ -47,8 +48,8 @@
|
||||
"name": "mesh-audit-logger",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:trail}:/trail"
|
||||
"/var/lib/audit-logger/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/audit-logger/trail:/trail"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
},
|
||||
"own-secrets": {
|
||||
"admin": "${dir:state}/admin.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/baserow/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -41,8 +41,8 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/baserow",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -88,7 +88,7 @@
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/baserow/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{\n \"password\": \"${secret:admin}\",\n \"host\": \"${bound:route:name}\"\n}\n",
|
||||
"merge": "json"
|
||||
@@ -99,8 +99,8 @@
|
||||
"name": "mesh-baserow",
|
||||
"network": "baserow",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
"/var/lib/mesh/baserow/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/baserow/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# bazarr'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 in
|
||||
# the base images, published like any other artifact — which 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 (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/bazarr
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/bazarr/dist /app/modules/bazarr/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/bazarr/dist/index.js,/app/modules/bazarr/dist/tools/index.js
|
||||
@@ -0,0 +1,173 @@
|
||||
// The Bazarr API client — bazarr's own code, living in the module (novox/hq ADR 0039). Bazarr
|
||||
// manages subtitles for a Sonarr/Radarr library: it tracks which episodes and movies are still
|
||||
// missing subtitles, searches providers for them, and records what it downloaded. This client
|
||||
// talks its /api surface (keyed by an X-API-KEY header); bazarr's tools and events import it.
|
||||
|
||||
import { readFileSync } from "node:fs";
|
||||
|
||||
export interface WantedSubtitle {
|
||||
kind: "episode" | "movie";
|
||||
title: string; // series + episode, or movie title
|
||||
path?: string;
|
||||
seriesId?: number; // sonarr series id (episodes)
|
||||
episodeId?: number; // sonarr episode id (episodes)
|
||||
radarrId?: number; // radarr movie id (movies)
|
||||
missing: string[]; // language names still missing
|
||||
}
|
||||
|
||||
export interface ProviderSubtitle {
|
||||
provider: string;
|
||||
language: string;
|
||||
hearingImpaired: boolean;
|
||||
forced: boolean;
|
||||
score?: number;
|
||||
release?: string;
|
||||
subtitle: string; // the opaque token Bazarr uses to download this exact result
|
||||
}
|
||||
|
||||
export interface HistoryEntry {
|
||||
kind: "episode" | "movie";
|
||||
id: string; // stable dedup key across polls
|
||||
title: string;
|
||||
language?: string;
|
||||
provider?: string;
|
||||
path?: string;
|
||||
timestamp?: string;
|
||||
description?: string;
|
||||
}
|
||||
|
||||
/** 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 {};
|
||||
try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
|
||||
catch { return {}; }
|
||||
}
|
||||
|
||||
/** Read a secret the mesh mounted at a file path (an own-secret delivered by `secret accept`);
|
||||
* absent or unreadable yields undefined so callers fall back rather than crash. */
|
||||
function readSecret(file?: string): string | undefined {
|
||||
if (!file) return undefined;
|
||||
try { return readFileSync(file, "utf8").trim(); }
|
||||
catch { return undefined; }
|
||||
}
|
||||
|
||||
export class BazarrClient {
|
||||
readonly baseUrl: string;
|
||||
|
||||
constructor(
|
||||
url: string,
|
||||
private readonly apiKey: string,
|
||||
) {
|
||||
this.baseUrl = url.replace(/\/$/, "");
|
||||
}
|
||||
|
||||
/** Build from the module's resolved environment. Bazarr's API is keyed; without URL and key
|
||||
* there is nothing to talk to, so this throws rather than run half-configured. */
|
||||
static fromEnv(env: NodeJS.ProcessEnv = process.env): BazarrClient {
|
||||
const cfg = meshConfig(env.MESH_BAZARR_CONFIG_FILE);
|
||||
const url = cfg.url ?? env.MESH_BAZARR_URL;
|
||||
const apiKey = cfg.apiKey ?? readSecret(env.MESH_BAZARR_API_KEY_FILE) ?? env.MESH_BAZARR_API_KEY;
|
||||
if (!url) throw new Error("no Bazarr URL — set MESH_BAZARR_URL");
|
||||
if (!apiKey) throw new Error("no Bazarr API key — set MESH_BAZARR_API_KEY");
|
||||
return new BazarrClient(url, apiKey);
|
||||
}
|
||||
|
||||
private async request(method: string, path: string, params: Record<string, string> = {}): Promise<any> {
|
||||
const url = new URL(`${this.baseUrl}/api${path}`);
|
||||
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
|
||||
const res = await fetch(url.toString(), { method, headers: { "X-API-KEY": this.apiKey, Accept: "application/json" } });
|
||||
if (!res.ok) throw new Error(`Bazarr API ${method} ${path}: ${res.status} ${await res.text()}`);
|
||||
// Downloads/patches return an empty body; only GETs carry JSON.
|
||||
const text = await res.text();
|
||||
return text ? JSON.parse(text) : {};
|
||||
}
|
||||
|
||||
private get(path: string, params?: Record<string, string>): Promise<any> {
|
||||
return this.request("GET", path, params);
|
||||
}
|
||||
|
||||
private languageNames(missing: any[]): string[] {
|
||||
return (missing ?? []).map((m: any) => m?.name ?? m?.code2 ?? m?.code3).filter(Boolean);
|
||||
}
|
||||
|
||||
/** Episodes and movies still missing subtitles — Bazarr's core "what's left to do" list. */
|
||||
async getWanted(limit = 50): Promise<WantedSubtitle[]> {
|
||||
const [eps, movies] = await Promise.all([
|
||||
this.get("/episodes/wanted", { start: "0", length: String(limit) }),
|
||||
this.get("/movies/wanted", { start: "0", length: String(limit) }),
|
||||
]);
|
||||
const episodes: WantedSubtitle[] = (eps?.data ?? []).map((e: any) => ({
|
||||
kind: "episode" as const,
|
||||
title: `${e.seriesTitle ?? e.series ?? "Unknown"} — ${e.episodeTitle ?? e.episode_title ?? ""}`.trim(),
|
||||
path: e.path,
|
||||
seriesId: e.sonarrSeriesId,
|
||||
episodeId: e.sonarrEpisodeId,
|
||||
missing: this.languageNames(e.missing_subtitles),
|
||||
}));
|
||||
const films: WantedSubtitle[] = (movies?.data ?? []).map((m: any) => ({
|
||||
kind: "movie" as const,
|
||||
title: m.title ?? "Unknown",
|
||||
path: m.path,
|
||||
radarrId: m.radarrId,
|
||||
missing: this.languageNames(m.missing_subtitles),
|
||||
}));
|
||||
return [...episodes, ...films];
|
||||
}
|
||||
|
||||
/** Ask providers what subtitles are available for one wanted episode — a manual search. */
|
||||
async searchEpisode(episodeId: number): Promise<ProviderSubtitle[]> {
|
||||
const raw = await this.get("/providers/episodes", { episodeid: String(episodeId) });
|
||||
return this.mapProviderResults(raw);
|
||||
}
|
||||
|
||||
/** Ask providers what subtitles are available for one movie — a manual search. */
|
||||
async searchMovie(radarrId: number): Promise<ProviderSubtitle[]> {
|
||||
const raw = await this.get("/providers/movies", { radarrid: String(radarrId) });
|
||||
return this.mapProviderResults(raw);
|
||||
}
|
||||
|
||||
private mapProviderResults(raw: any): ProviderSubtitle[] {
|
||||
const list = Array.isArray(raw) ? raw : (raw?.data ?? []);
|
||||
return list.map((r: any) => ({
|
||||
provider: r.provider,
|
||||
language: r.language?.name ?? r.language ?? "unknown",
|
||||
hearingImpaired: Boolean(r.hearing_impaired ?? r.hi),
|
||||
forced: Boolean(r.forced),
|
||||
score: r.score,
|
||||
release: r.release_info?.[0] ?? r.release_info,
|
||||
subtitle: r.subtitle,
|
||||
}));
|
||||
}
|
||||
|
||||
/** Recent subtitle-download history, episodes and movies together, newest first. Each entry
|
||||
* carries a stable id so the events poller can tell a fresh download from one already seen. */
|
||||
async getHistory(limit = 40): Promise<HistoryEntry[]> {
|
||||
const [eps, movies] = await Promise.all([
|
||||
this.get("/episodes/history", { start: "0", length: String(limit) }),
|
||||
this.get("/movies/history", { start: "0", length: String(limit) }),
|
||||
]);
|
||||
const key = (kind: string, r: any): string =>
|
||||
`${kind}:${r.timestamp ?? r.parsed_timestamp ?? ""}:${r.subtitles_path ?? r.path ?? ""}:${r.language?.code3 ?? r.language ?? ""}`;
|
||||
const episodes: HistoryEntry[] = (eps?.data ?? []).map((r: any) => ({
|
||||
kind: "episode" as const,
|
||||
id: key("episode", r),
|
||||
title: `${r.seriesTitle ?? "Unknown"} — ${r.episodeTitle ?? ""}`.trim(),
|
||||
language: r.language?.name ?? r.language,
|
||||
provider: r.provider,
|
||||
path: r.subtitles_path,
|
||||
timestamp: r.timestamp,
|
||||
description: r.description,
|
||||
}));
|
||||
const films: HistoryEntry[] = (movies?.data ?? []).map((r: any) => ({
|
||||
kind: "movie" as const,
|
||||
id: key("movie", r),
|
||||
title: r.title ?? "Unknown",
|
||||
language: r.language?.name ?? r.language,
|
||||
provider: r.provider,
|
||||
path: r.subtitles_path,
|
||||
timestamp: r.timestamp,
|
||||
description: r.description,
|
||||
}));
|
||||
return [...episodes, ...films];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
// bazarr's events. The tool runtime imports this once the broker is bound. Bazarr's one genuinely
|
||||
// observable thing is a subtitle arriving: it works away in the background, searching providers for
|
||||
// the missing-subtitle list, and when it succeeds a subtitle appears in its history. That is worth
|
||||
// announcing to the mesh.
|
||||
//
|
||||
// Emits (novox/hq ADR 0041/0042):
|
||||
// module.bazarr.subtitle.downloaded — a subtitle was fetched for an episode or movie
|
||||
//
|
||||
// Bazarr has nothing on the mesh it usefully reacts to (a download completing is Sonarr/Radarr's
|
||||
// business, and they trigger Bazarr directly), so it consumes nothing — a pure emitter.
|
||||
//
|
||||
// The event is observation-based: poll history and diff. Primed silently on the first look, or a
|
||||
// restart would re-announce the whole recent history as freshly downloaded.
|
||||
|
||||
import { emit } from "@novox/mesh-sdk/events";
|
||||
import { BazarrClient } from "./client.js";
|
||||
|
||||
const bazarr = BazarrClient.fromEnv();
|
||||
|
||||
const seen = new Set<string>();
|
||||
let primed = false;
|
||||
async function pollHistory(): Promise<void> {
|
||||
const entries = await bazarr.getHistory(40);
|
||||
for (const entry of entries) {
|
||||
if (seen.has(entry.id)) continue;
|
||||
if (primed) {
|
||||
await emit("subtitle.downloaded", {
|
||||
kind: entry.kind,
|
||||
title: entry.title,
|
||||
language: entry.language,
|
||||
provider: entry.provider,
|
||||
path: entry.path,
|
||||
});
|
||||
}
|
||||
seen.add(entry.id);
|
||||
}
|
||||
primed = true;
|
||||
}
|
||||
|
||||
const tick = (fn: () => Promise<void>, everyMs: number): void => {
|
||||
const run = (): void => void fn().catch((err) => console.error(`[bazarr] ${err}`));
|
||||
setInterval(run, everyMs);
|
||||
run();
|
||||
};
|
||||
tick(pollHistory, 60_000);
|
||||
|
||||
console.log("[bazarr] watching subtitle-download history");
|
||||
@@ -0,0 +1,141 @@
|
||||
{
|
||||
"module": "bazarr",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"emits": [
|
||||
"subtitle.downloaded"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "/var/lib/mesh/bazarr/broker",
|
||||
"api-key": "/var/lib/mesh/bazarr/api-key"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
"name": "web",
|
||||
"port": 6767,
|
||||
"protocol": "tcp",
|
||||
"from": "mesh",
|
||||
"why": "managing subtitles"
|
||||
}
|
||||
],
|
||||
"accesses": [
|
||||
{
|
||||
"path": "/services/media/movies",
|
||||
"mode": "read-write"
|
||||
},
|
||||
{
|
||||
"path": "/services/media/series",
|
||||
"mode": "read-write"
|
||||
},
|
||||
{
|
||||
"path": "/services/media/anime",
|
||||
"mode": "read-write"
|
||||
},
|
||||
{
|
||||
"path": "/services/media/downloads",
|
||||
"mode": "read"
|
||||
}
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh/bazarr",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "directory",
|
||||
"path": "/services/bazarr/config",
|
||||
"mode": "0700",
|
||||
"owner": "1000:1000"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "bazarr",
|
||||
"image": "lscr.io/linuxserver/bazarr@sha256:3a820372f19fcb2981ea19fe4b5382934d67414afaba974bce831ddda0a64a02",
|
||||
"env": {
|
||||
"PUID": "1000",
|
||||
"PGID": "1000",
|
||||
"TZ": "Etc/UTC"
|
||||
},
|
||||
"ports": [
|
||||
"6767"
|
||||
],
|
||||
"volumes": [
|
||||
"/services/bazarr/config:/config",
|
||||
"/services/media/movies:/movies",
|
||||
"/services/media/series:/series",
|
||||
"/services/media/anime:/anime",
|
||||
"/services/media/downloads:/downloads"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "/var/lib/mesh/bazarr/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-bazarr",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"/var/lib/mesh/bazarr/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/bazarr/api-key:/run/secrets/api-key:ro",
|
||||
"/var/lib/mesh/bazarr/config.json:/run/config/config.json:ro",
|
||||
"/services/bazarr/config:/var/lib/bazarr/config:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_BAZARR_URL": "http://127.0.0.1:6767",
|
||||
"MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
|
||||
"MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
"route"
|
||||
],
|
||||
"contributes": {
|
||||
"route": {
|
||||
"label": "subs",
|
||||
"endpoint": "web"
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "/var/lib/mesh/bazarr/route.json"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "@novox/module-bazarr",
|
||||
"version": "0.1.0",
|
||||
"description": "bazarr — subtitle management. Its API client, tools and events live here (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"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
// bazarr's tools — its own code (novox/hq ADR 0039), importing bazarr's 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 { BazarrClient } from "../client.js";
|
||||
|
||||
export function getBazarrTools(bazarr: BazarrClient): ToolDefinition[] {
|
||||
return [
|
||||
{
|
||||
name: "bazarr_wanted",
|
||||
description: "Episodes and movies still missing subtitles, with the languages each still needs.",
|
||||
input: { limit: { type: "number", description: "max items per kind (default 50)" } },
|
||||
run: async (args) => {
|
||||
const wanted = await bazarr.getWanted(args.limit ? Number(args.limit) : 50);
|
||||
return { count: wanted.length, wanted };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "bazarr_search_subtitles",
|
||||
description: "Manually search subtitle providers for one wanted item — pass an episodeId or a radarrId.",
|
||||
input: {
|
||||
episodeId: { type: "number", description: "a Sonarr episode id (from bazarr_wanted)" },
|
||||
radarrId: { type: "number", description: "a Radarr movie id (from bazarr_wanted)" },
|
||||
},
|
||||
run: async (args) => {
|
||||
if (args.episodeId !== undefined) {
|
||||
const results = await bazarr.searchEpisode(Number(args.episodeId));
|
||||
return { kind: "episode", episodeId: Number(args.episodeId), count: results.length, results };
|
||||
}
|
||||
if (args.radarrId !== undefined) {
|
||||
const results = await bazarr.searchMovie(Number(args.radarrId));
|
||||
return { kind: "movie", radarrId: Number(args.radarrId), count: results.length, results };
|
||||
}
|
||||
throw new Error("pass either episodeId or radarrId");
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "bazarr_history",
|
||||
description: "Recent subtitle-download history — what was downloaded, for which title, from which provider.",
|
||||
input: { limit: { type: "number", description: "max entries per kind (default 40)" } },
|
||||
run: async (args) => {
|
||||
const history = await bazarr.getHistory(args.limit ? Number(args.limit) : 40);
|
||||
return { count: history.length, history };
|
||||
},
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
// Exposed only when Bazarr is configured; otherwise bazarr contributes no tools rather than
|
||||
// failing the whole runtime.
|
||||
registerModuleTools("bazarr", (env) => {
|
||||
try {
|
||||
return getBazarrTools(BazarrClient.fromEnv(env));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["client.ts", "index.ts", "tools/index.ts"]
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
# bookshelf'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 in
|
||||
# the base images, published like any other artifact — which 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 (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/bookshelf
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/bookshelf/dist /app/modules/bookshelf/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/bookshelf/dist/index.js,/app/modules/bookshelf/dist/tools/index.js
|
||||
@@ -0,0 +1,136 @@
|
||||
// The Bookshelf API client — bookshelf's own code, living in the module (novox/hq ADR 0039).
|
||||
// Ported from the shared hal `arr` client, but self-contained: in nox each Servarr app owns its own
|
||||
// copy, so a change to Bookshelf's API rebuilds only bookshelf and nothing else. Both this module's
|
||||
// tools and its events entrypoint import it, and nothing outside bookshelf does.
|
||||
//
|
||||
// Bookshelf is a Readarr fork (ghcr.io/pennydreadful/bookshelf). It speaks the Servarr v1 API; its
|
||||
// content is "book". Unlike Sonarr/Radarr it exposes no calendar endpoint, so there is no calendar
|
||||
// tool here — matching hal, which excluded bookshelf from its calendar-capable apps.
|
||||
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
// Bookshelf speaks the v1 API; its content is "book".
|
||||
const API_VERSION = "v1";
|
||||
const CONTENT_ENDPOINT = "book";
|
||||
const APP_NAME = "Bookshelf";
|
||||
|
||||
export interface BookshelfQueueItem {
|
||||
/** The queue record id — stable while the item is in the queue, so events can diff on it. */
|
||||
id: number;
|
||||
title: string;
|
||||
status: string;
|
||||
size: string;
|
||||
sizeleft: string;
|
||||
timeleft?: string;
|
||||
}
|
||||
|
||||
export interface BookshelfContentItem {
|
||||
title: string;
|
||||
author?: string;
|
||||
year?: number;
|
||||
status?: string;
|
||||
monitored: boolean;
|
||||
}
|
||||
|
||||
export class BookshelfClient {
|
||||
readonly baseUrl: string;
|
||||
|
||||
constructor(
|
||||
url: string,
|
||||
private readonly apiKey: string,
|
||||
) {
|
||||
this.baseUrl = url.replace(/\/$/, "");
|
||||
}
|
||||
|
||||
/**
|
||||
* Build from the module's resolved environment. The URL defaults to the server on this node (the
|
||||
* runtime shares its network), and the API key is read from MESH_BOOKSHELF_API_KEY or, failing
|
||||
* that, discovered from the server's own config.xml under MESH_BOOKSHELF_CONFIG_DIR — the same
|
||||
* file Bookshelf writes it to, so a running server needs nothing configured by hand. Throws when
|
||||
* no key can be found, so the tools/events simply do not load (the harness treats the throw as
|
||||
* "exposes nothing").
|
||||
*/
|
||||
static fromEnv(env: NodeJS.ProcessEnv = process.env): BookshelfClient {
|
||||
const url = env.MESH_BOOKSHELF_URL ?? `http://127.0.0.1:${env.MESH_BOOKSHELF_PORT ?? "8787"}`;
|
||||
const configDir = env.MESH_BOOKSHELF_CONFIG_DIR ?? "/config";
|
||||
const apiKey = env.MESH_BOOKSHELF_API_KEY ?? BookshelfClient.detectApiKey(configDir);
|
||||
if (!apiKey) {
|
||||
throw new Error("Bookshelf not configured — set MESH_BOOKSHELF_API_KEY or make the config dir readable");
|
||||
}
|
||||
return new BookshelfClient(url, apiKey);
|
||||
}
|
||||
|
||||
/** Discover the API key from the server's config.xml, falling back to null. Every Servarr app
|
||||
* writes <ApiKey> into config.xml at the root of its config directory. */
|
||||
static detectApiKey(configDir: string): string | null {
|
||||
const config = join(configDir, "config.xml");
|
||||
if (existsSync(config)) {
|
||||
const match = readFileSync(config, "utf8").match(/<ApiKey>([^<]+)<\/ApiKey>/);
|
||||
if (match) return match[1];
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
private async get(endpoint: string, params?: Record<string, string>): Promise<unknown> {
|
||||
const url = new URL(`${this.baseUrl}/api/${API_VERSION}/${endpoint}`);
|
||||
if (params) {
|
||||
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
|
||||
}
|
||||
const res = await fetch(url.toString(), { headers: { "X-Api-Key": this.apiKey } });
|
||||
if (!res.ok) throw new Error(`${APP_NAME} API /${endpoint}: ${res.status} ${await res.text()}`);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
async getStatus(): Promise<{ appName: string; version: string }> {
|
||||
const data = (await this.get("system/status")) as { appName?: string; version?: string };
|
||||
return { appName: data.appName || APP_NAME, version: data.version ?? "unknown" };
|
||||
}
|
||||
|
||||
async getContent(limit?: number): Promise<BookshelfContentItem[]> {
|
||||
const data = await this.get(CONTENT_ENDPOINT);
|
||||
const items: any[] = Array.isArray(data) ? data : ((data as any)?.records ?? []);
|
||||
const mapped = items.map((item) => ({
|
||||
title: item.title ?? "Unknown",
|
||||
author: item.author?.authorName ?? item.authorName,
|
||||
year: item.releaseDate ? new Date(item.releaseDate).getFullYear() : item.year,
|
||||
status: item.status,
|
||||
monitored: item.monitored ?? true,
|
||||
}));
|
||||
return limit ? mapped.slice(0, limit) : mapped;
|
||||
}
|
||||
|
||||
/** Library search is a filter over existing content, not an indexer lookup — same as hal's. */
|
||||
async searchContent(term: string): Promise<BookshelfContentItem[]> {
|
||||
const all = await this.getContent();
|
||||
const lower = term.toLowerCase();
|
||||
return all.filter(
|
||||
(item) =>
|
||||
item.title.toLowerCase().includes(lower) ||
|
||||
(item.author?.toLowerCase().includes(lower) ?? false),
|
||||
);
|
||||
}
|
||||
|
||||
async getQueue(): Promise<{ totalRecords: number; items: BookshelfQueueItem[] }> {
|
||||
const data = (await this.get("queue", { pageSize: "50" })) as { totalRecords?: number; records?: any[] };
|
||||
const records = data.records ?? [];
|
||||
return {
|
||||
totalRecords: data.totalRecords ?? records.length,
|
||||
items: records.map((r) => ({
|
||||
id: r.id,
|
||||
title: r.title ?? r.book?.title ?? r.author?.authorName ?? "Unknown",
|
||||
status: r.status ?? "unknown",
|
||||
size: formatBytes(r.size ?? 0),
|
||||
sizeleft: formatBytes(r.sizeleft ?? 0),
|
||||
timeleft: r.timeleft,
|
||||
})),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
function formatBytes(bytes: number): string {
|
||||
if (bytes === 0) return "0 B";
|
||||
const units = ["B", "KB", "MB", "GB", "TB"];
|
||||
const i = Math.floor(Math.log(bytes) / Math.log(1024));
|
||||
return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
// bookshelf's events. The tool runtime imports this once the broker is bound. It watches the
|
||||
// download queue and turns its comings and goings into mesh events — the same mechanism radarr uses,
|
||||
// applied to a Servarr book manager.
|
||||
//
|
||||
// Emits (novox/hq ADR 0041/0042):
|
||||
// module.bookshelf.book.grabbed — a release entered the queue (Bookshelf grabbed it)
|
||||
// module.bookshelf.download.completed — a release left the queue, imported. This routing key is
|
||||
// what the plex module consumes (module.*.download.completed)
|
||||
// to rescan, so a new audiobook becomes a visible item.
|
||||
// Consumes: none.
|
||||
//
|
||||
// NOTE: the hal bookshelf module emitted no events (its hooks only did install-time provisioning).
|
||||
// This queue watcher is new in nox, modelled exactly on radarr's — bookshelf is a Servarr app with
|
||||
// the same queue semantics, so the diff-and-emit pattern carries over unchanged.
|
||||
//
|
||||
// The queue is polled and diffed, primed silently on the first look (like plex's index.ts) so a
|
||||
// restart mid-download does not re-announce everything already in flight as freshly grabbed.
|
||||
|
||||
import { emit } from "@novox/mesh-sdk/events";
|
||||
import { BookshelfClient, type BookshelfQueueItem } from "./client.js";
|
||||
|
||||
// Building the client throws when Bookshelf has no URL/key yet. Like the tools (see tools/index.ts),
|
||||
// the events entrypoint must not crash the runtime for that — it stays idle until configured.
|
||||
function buildClient(): BookshelfClient | null {
|
||||
try {
|
||||
return BookshelfClient.fromEnv();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
const bookshelf = buildClient();
|
||||
|
||||
// Bookshelf removes an item from the queue once it has been imported; a "warning"/"failed" status is
|
||||
// how a stuck or broken grab shows itself, so we do not call those a completion when they vanish.
|
||||
const FAILED_STATUSES = new Set(["failed", "warning"]);
|
||||
|
||||
const inQueue = new Map<number, BookshelfQueueItem>();
|
||||
let primed = false;
|
||||
|
||||
async function pollQueue(bookshelf: BookshelfClient): Promise<void> {
|
||||
const { items } = await bookshelf.getQueue();
|
||||
const now = new Map(items.map((i) => [i.id, i]));
|
||||
|
||||
if (primed) {
|
||||
// Entered the queue since last look — Bookshelf grabbed a release.
|
||||
for (const [id, item] of now) {
|
||||
if (!inQueue.has(id)) await emit("book.grabbed", { title: item.title, status: item.status });
|
||||
}
|
||||
// Left the queue — imported and done, unless it was last seen failing.
|
||||
for (const [id, item] of inQueue) {
|
||||
if (!now.has(id) && !FAILED_STATUSES.has(item.status)) {
|
||||
await emit("download.completed", { title: item.title });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
inQueue.clear();
|
||||
for (const [id, item] of now) inQueue.set(id, item);
|
||||
primed = true;
|
||||
}
|
||||
|
||||
const tick = (fn: () => Promise<void>, everyMs: number): void => {
|
||||
const run = (): void => void fn().catch((err) => console.error(`[bookshelf] ${err}`));
|
||||
setInterval(run, everyMs);
|
||||
run();
|
||||
};
|
||||
|
||||
if (bookshelf) {
|
||||
tick(() => pollQueue(bookshelf), 30_000);
|
||||
console.log("[bookshelf] watching the download queue, emitting grabs and completions");
|
||||
} else {
|
||||
console.log("[bookshelf] not configured — events idle until an API key is available");
|
||||
}
|
||||
@@ -0,0 +1,118 @@
|
||||
{
|
||||
"module": "bookshelf",
|
||||
"version": "1",
|
||||
"slug": "books",
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"emits": [
|
||||
"book.grabbed",
|
||||
"download.completed"
|
||||
],
|
||||
"consumes": [],
|
||||
"own-secrets": {
|
||||
"broker": "/var/lib/mesh/bookshelf/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
"name": "web",
|
||||
"port": 8787,
|
||||
"protocol": "tcp",
|
||||
"from": "mesh",
|
||||
"why": "managing the ebook/audiobook library"
|
||||
}
|
||||
],
|
||||
"accesses": [
|
||||
{
|
||||
"path": "/services/media/books",
|
||||
"mode": "read-write"
|
||||
},
|
||||
{
|
||||
"path": "/services/media/downloads",
|
||||
"mode": "read-write"
|
||||
}
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh/bookshelf",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "directory",
|
||||
"path": "/services/bookshelf/config",
|
||||
"mode": "0700",
|
||||
"owner": "1000:1000"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "bookshelf",
|
||||
"image": "ghcr.io/pennydreadful/bookshelf@sha256:388eecc94362580eae31ee0a454be6af516f8a311f8432a521c202fb475f4359",
|
||||
"env": {
|
||||
"PUID": "1000",
|
||||
"PGID": "1000",
|
||||
"TZ": "Etc/UTC"
|
||||
},
|
||||
"ports": [
|
||||
"8787"
|
||||
],
|
||||
"volumes": [
|
||||
"/services/bookshelf/config:/config",
|
||||
"/services/media/books:/books",
|
||||
"/services/media/downloads:/downloads"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-bookshelf",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"/var/lib/mesh/bookshelf/broker:/run/secrets/broker:ro",
|
||||
"/services/bookshelf/config:/var/lib/bookshelf/config:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
|
||||
"MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
"route"
|
||||
],
|
||||
"contributes": {
|
||||
"route": {
|
||||
"label": "books",
|
||||
"endpoint": "web"
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "/var/lib/mesh/bookshelf/route.json"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "@novox/module-bookshelf",
|
||||
"version": "0.1.0",
|
||||
"description": "bookshelf — ebook/audiobook management (Readarr fork). Its API client, tools and events live here (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"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
// bookshelf's tools — ported from the shared hal `arr` sdk (novox/hq ADR 0039), importing
|
||||
// bookshelf's own client. They return structured data (not the pre-formatted text hal returned); the
|
||||
// mesh serves them through the sdk's tool harness. Bookshelf has no calendar endpoint, so there is
|
||||
// no calendar tool — matching hal, which excluded it from its calendar-capable apps.
|
||||
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { BookshelfClient } from "../client.js";
|
||||
|
||||
export function getBookshelfTools(bookshelf: BookshelfClient): ToolDefinition[] {
|
||||
return [
|
||||
{
|
||||
name: "bookshelf_status",
|
||||
description: "Bookshelf status overview: version, book count, monitored count, queue size.",
|
||||
input: {},
|
||||
run: async () => {
|
||||
const [status, content, queue] = await Promise.all([
|
||||
bookshelf.getStatus(),
|
||||
bookshelf.getContent(),
|
||||
bookshelf.getQueue(),
|
||||
]);
|
||||
return {
|
||||
app: status.appName,
|
||||
version: status.version,
|
||||
books: content.length,
|
||||
monitored: content.filter((c) => c.monitored).length,
|
||||
queue: queue.totalRecords,
|
||||
};
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "bookshelf_library",
|
||||
description: "List books from the Bookshelf library.",
|
||||
input: { limit: { type: "number", description: "max items to return (default 50)" } },
|
||||
run: async (args) => {
|
||||
const items = await bookshelf.getContent(args.limit ? Number(args.limit) : 50);
|
||||
return { count: items.length, books: items };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "bookshelf_search",
|
||||
description:
|
||||
"Search the Bookshelf library for books by title or author (filters existing content, not indexers).",
|
||||
input: { query: { type: "string", description: "the search term" } },
|
||||
run: async (args) => {
|
||||
const query = String(args.query);
|
||||
return { query, results: await bookshelf.searchContent(query) };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "bookshelf_queue",
|
||||
description: "Show the Bookshelf download queue — what is downloading and how far along.",
|
||||
input: {},
|
||||
run: async () => {
|
||||
const queue = await bookshelf.getQueue();
|
||||
return { count: queue.totalRecords, items: queue.items };
|
||||
},
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
// The tools exist only when Bookshelf is configured; without a URL and key, bookshelf contributes
|
||||
// none rather than failing the whole runtime.
|
||||
registerModuleTools("bookshelf", (env) => {
|
||||
try {
|
||||
return getBookshelfTools(BookshelfClient.fromEnv(env));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["client.ts", "index.ts", "tools/index.ts"]
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
ARG GO_BASE
|
||||
ARG ALPINE_BASE
|
||||
# build-agent's image: the build machine itself, compiled into a container (novox/hq ADR 0190).
|
||||
#
|
||||
# **The source is not vendored here.** builder's actual code — cmd/mesh-builder, internal/builder,
|
||||
# internal/catalogue — lives in the mesh-controller repository, the same control plane it is one
|
||||
# half of. This module ships the packaging, not a second copy of the source, so the build context
|
||||
# is the mesh-controller repository root (declared under build.artifacts[].context), and this
|
||||
# Dockerfile compiles ./cmd/mesh-builder from it — the same shape route-proxy already uses for the
|
||||
# same reason.
|
||||
FROM ${GO_BASE} AS build
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /mesh-builder ./cmd/mesh-builder
|
||||
|
||||
# Unlike mesh-controller's own FROM scratch (ADR 0006: nothing to audit but one binary), the build
|
||||
# machine's whole job is shelling out to git and docker — it needs a real userland to do that in,
|
||||
# not a second copy of either tool vendored into this image. apk installs both from the base's own
|
||||
# packages, not fetched on its own at build time.
|
||||
FROM ${ALPINE_BASE}
|
||||
RUN apk add --no-cache docker-cli git
|
||||
COPY --from=build /mesh-builder /usr/local/bin/mesh-builder
|
||||
ENTRYPOINT ["/usr/local/bin/mesh-builder"]
|
||||
@@ -1,15 +0,0 @@
|
||||
# build-agent
|
||||
|
||||
The mesh's build machine as a role every machine can hold (novox/hq ADR 0190). It holds the node seat
|
||||
`node-build-agent`: every holder pulls one build at a time from the role's one work queue when it is
|
||||
idle, so a tier of many images is built by as many machines as hold the seat and are online, and a
|
||||
machine that is off builds nothing and blocks nothing. The controller asks the role, never a machine;
|
||||
the outcome names the machine that built it.
|
||||
|
||||
What a holding machine needs is what the builder always needed, said here once: a container runtime
|
||||
(the socket is mounted), the artifact store and the package registry as provisions, a workspace, and
|
||||
the bus credential. The code is `cmd/mesh-builder` in the mesh-controller repository, compiled from
|
||||
that repository's main (`build.artifacts[].context`); this module ships the packaging.
|
||||
|
||||
Assign it to every machine with a container runtime. It replaces `builder`, the one-holder form of the
|
||||
same thing; retire that once this is assigned where it was.
|
||||
@@ -1,88 +0,0 @@
|
||||
{
|
||||
"module": "build-agent",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
"name": "node-build-agent",
|
||||
"scope": "node"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
"artifact-store",
|
||||
"npm-package-registry"
|
||||
],
|
||||
"binds": {
|
||||
"npm-package-registry": "${dir:mesh-state}/package-registry.json"
|
||||
},
|
||||
"secrets": {
|
||||
"npm-package-registry": "${dir:mesh-state}/package-registry.secret"
|
||||
},
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "workspace",
|
||||
"type": "directory",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "agent-env",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/build-agent.env",
|
||||
"mode": "0600",
|
||||
"content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=${dir:workspace}\n"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "mesh-build-agent",
|
||||
"artifact": "server",
|
||||
"env-file": [
|
||||
"${dir:mesh-state}/build-agent.env"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}:/run/mesh:ro",
|
||||
"${dir:workspace}:${dir:workspace}",
|
||||
"/var/run/docker.sock:/var/run/docker.sock"
|
||||
],
|
||||
"restart-on": [
|
||||
"agent-env"
|
||||
],
|
||||
"network": "host"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "server",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile",
|
||||
"context": {
|
||||
"seat": "git",
|
||||
"repository": "novox/mesh-controller",
|
||||
"ref": "main"
|
||||
}
|
||||
}
|
||||
],
|
||||
"on": [
|
||||
{
|
||||
"arg": "GO_BASE",
|
||||
"image": "golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c"
|
||||
},
|
||||
{
|
||||
"arg": "ALPINE_BASE",
|
||||
"image": "alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
+11
-10
@@ -15,32 +15,33 @@
|
||||
"npm-package-registry"
|
||||
],
|
||||
"binds": {
|
||||
"npm-package-registry": "${dir:mesh-state}/package-registry.json"
|
||||
"npm-package-registry": "/var/lib/mesh/builder/package-registry.json"
|
||||
},
|
||||
"secrets": {
|
||||
"npm-package-registry": "${dir:mesh-state}/package-registry.secret"
|
||||
"npm-package-registry": "/var/lib/mesh/builder/package-registry.secret"
|
||||
},
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/builder/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/builder",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "workspace",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/builder/workspace",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "builder-env",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/builder.env",
|
||||
"path": "/var/lib/mesh/builder/builder.env",
|
||||
"mode": "0600",
|
||||
"content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=${dir:workspace}\n"
|
||||
"content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=/var/lib/builder/workspace\n"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
@@ -48,11 +49,11 @@
|
||||
"name": "mesh-builder",
|
||||
"artifact": "server",
|
||||
"env-file": [
|
||||
"${dir:mesh-state}/builder.env"
|
||||
"/var/lib/mesh/builder/builder.env"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}:/run/mesh:ro",
|
||||
"${dir:workspace}:${dir:workspace}",
|
||||
"/var/lib/mesh/builder:/run/mesh:ro",
|
||||
"/var/lib/builder/workspace:/var/lib/builder/workspace",
|
||||
"/var/run/docker.sock:/var/run/docker.sock"
|
||||
],
|
||||
"restart-on": [
|
||||
|
||||
@@ -12,14 +12,14 @@
|
||||
"public-dns": {}
|
||||
},
|
||||
"grants": {
|
||||
"public-dns": "${dir:grants}"
|
||||
"public-dns": "/var/lib/cloudflare-dns/grants"
|
||||
},
|
||||
"receives": {
|
||||
"public-dns": "${dir:grants}/mesh.json"
|
||||
"public-dns": "/var/lib/cloudflare-dns/grants/mesh.json"
|
||||
},
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"token": "/var/lib/cloudflare-dns/token",
|
||||
"broker": "/var/lib/mesh/cloudflare-dns/broker"
|
||||
},
|
||||
"emits": [
|
||||
"record.created",
|
||||
@@ -29,24 +29,25 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/cloudflare-dns",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/cloudflare-dns",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "grants",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/cloudflare-dns/grants",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/config.json",
|
||||
"path": "/var/lib/cloudflare-dns/config.json",
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
@@ -57,10 +58,10 @@
|
||||
"name": "mesh-cloudflare-dns",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:grants}:/grants",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
"/var/lib/cloudflare-dns/config.json:/run/config/config.json:ro",
|
||||
"/var/lib/cloudflare-dns/grants:/grants",
|
||||
"/var/lib/cloudflare-dns/token:/run/secrets/token:ro",
|
||||
"/var/lib/mesh/cloudflare-dns/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CLOUDFLARE_TOKEN_FILE": "/run/secrets/token",
|
||||
|
||||
@@ -3,26 +3,26 @@
|
||||
"version": "1",
|
||||
"slug": "confl",
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"token": "/var/lib/confluence/token",
|
||||
"broker": "/var/lib/mesh/confluence/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/confluence",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/confluence",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/config.json",
|
||||
"path": "/var/lib/confluence/config.json",
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
@@ -33,9 +33,9 @@
|
||||
"name": "mesh-runtime-confluence",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
"/var/lib/confluence/config.json:/run/config/config.json:ro",
|
||||
"/var/lib/confluence/token:/run/secrets/token:ro",
|
||||
"/var/lib/mesh/confluence/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CONFLUENCE_TOKEN_FILE": "/run/secrets/token",
|
||||
|
||||
@@ -15,11 +15,11 @@
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "${dir:state}/route.json"
|
||||
"route": "/var/lib/de-spiegel/route.json"
|
||||
},
|
||||
"own-secrets": {
|
||||
"smtp-user": "${dir:state}/smtp-user.secret",
|
||||
"smtp-pass": "${dir:state}/smtp-pass.secret"
|
||||
"smtp-user": "/var/lib/de-spiegel/smtp-user.secret",
|
||||
"smtp-pass": "/var/lib/de-spiegel/smtp-pass.secret"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -34,13 +34,13 @@
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/de-spiegel",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "server-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/server.env",
|
||||
"path": "/var/lib/de-spiegel/server.env",
|
||||
"mode": "0600",
|
||||
"content": "SMTP_AUTH_USER=${secret:smtp-user}\nSMTP_AUTH_PASS=${secret:smtp-pass}\n"
|
||||
},
|
||||
@@ -56,7 +56,7 @@
|
||||
"image": "registry-api.novox.be/novox/de-spiegel@sha256:e144b72ce9c145870470d765343549f2c60211728cd118b9ff0e4029f36342ba",
|
||||
"network": "de-spiegel",
|
||||
"env-file": [
|
||||
"${dir:state}/server.env"
|
||||
"/var/lib/de-spiegel/server.env"
|
||||
],
|
||||
"ports": [
|
||||
"35621"
|
||||
|
||||
@@ -3,8 +3,7 @@
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"package-manager",
|
||||
"service-manager",
|
||||
"uplink-dhcpcd"
|
||||
"service-manager"
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
"name": "mesh-artifact-store",
|
||||
"name": "the-artifact-store",
|
||||
"scope": "mesh"
|
||||
}
|
||||
],
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -1,23 +0,0 @@
|
||||
# fail2ban's runtime: the tool runtime, carrying the intrusion prevention's verbs and the client they
|
||||
# speak through.
|
||||
#
|
||||
# Built from this module's own directory and nothing else (novox/hq ADR 0069). Two bases, named in
|
||||
# module.json's `build.on`: the image this is compiled in and the image it runs in.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/fail2ban
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
# The daemon runs on the machine, declared by this module; what runs here is only its client, which
|
||||
# speaks to the daemon over the socket the machine shares into this container (novox/hq ADR 0179).
|
||||
# The package brings the client and the daemon together; the daemon is never started here.
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends fail2ban \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
COPY --from=build /app/modules/fail2ban/dist /app/modules/fail2ban/dist
|
||||
ENV MESH_TOOL_MODULES=/app/modules/fail2ban/dist/tools/index.js
|
||||
+35
-188
@@ -1,204 +1,51 @@
|
||||
// fail2ban's own code, in the module (novox/hq ADR 0039). The jails are composed by the mesh from
|
||||
// the modules a machine runs (to-be 31) and written as declared resources; the daemon is kept
|
||||
// running by one. This code exists only to read and steer the *live* state the daemon owns: who is
|
||||
// banned now and until when, and the ban or release an operator asks for — the node-intrusion-
|
||||
// prevention seat's four verbs (ADR 0179). The daemon's state is fail2ban's, not the mesh's: the
|
||||
// mesh composes the jails and never writes the ban list.
|
||||
//
|
||||
// Spoken through fail2ban-client over the daemon's socket, which the machine shares into this
|
||||
// runtime; so the client here is the one from the runtime's own package and the daemon is the
|
||||
// machine's, and the two meet at /var/run/fail2ban/fail2ban.sock.
|
||||
// fail2ban's own code, in the module (novox/hq ADR 0039). The jails and the daemon are declared
|
||||
// resources — the mesh writes /etc/fail2ban/jail.d/* and keeps fail2ban.service running (see
|
||||
// module.json). This code exists only to read and steer the *live* state the daemon owns at
|
||||
// runtime: which IPs are banned right now, and the manual ban/unban an operator reaches for. That
|
||||
// state (the running bans, /var/lib/fail2ban's sqlite) is fail2ban's, not the mesh's — the mesh
|
||||
// reconciles the config, never the ban list.
|
||||
|
||||
import { execFile } from "node:child_process";
|
||||
import { isIP } from "node:net";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
const execFileP = promisify(execFile);
|
||||
|
||||
/** A command runner, so the verbs can be tested without a daemon. */
|
||||
export type Runner = (cmd: string, args: string[]) => Promise<string>;
|
||||
|
||||
export const execRunner: Runner = async (cmd, args) => {
|
||||
try {
|
||||
const { stdout } = await execFileP(cmd, args, { maxBuffer: 16 * 1024 * 1024 });
|
||||
return stdout;
|
||||
} catch (err) {
|
||||
const e = err as { code?: string | number; stderr?: string; stdout?: string; message?: string };
|
||||
const said = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
|
||||
if (e.code === "ENOENT") throw new Error(`${cmd} is not in this runtime`);
|
||||
if (/Failed to access socket path|Is fail2ban running/i.test(said)) {
|
||||
throw new Error("fail2ban is not running on this machine, or its socket is not shared with this runtime");
|
||||
}
|
||||
// fail2ban-client's own last line is the one a person reads ("Sorry but the jail 'x' does not exist").
|
||||
const lines = said.split("\n").map((l) => l.trim()).filter(Boolean);
|
||||
throw new Error(lines.length ? lines[lines.length - 1] : (e.message ?? `${cmd} failed`));
|
||||
}
|
||||
};
|
||||
|
||||
/** One jail as the daemon reports it. */
|
||||
export interface JailStatus {
|
||||
jail: string;
|
||||
/** What the jail is reading: files or journal matches, as fail2ban names them. */
|
||||
watching: string[];
|
||||
/** Addresses with failures counted against them right now, and all failures since the jail started. */
|
||||
failing: { now: number; total: number };
|
||||
/** Addresses held right now, and all bans since the jail started. */
|
||||
banned: { now: number; total: number; addresses: string[] };
|
||||
}
|
||||
|
||||
/** One ban as the daemon holds it. */
|
||||
export interface Ban {
|
||||
ip: string;
|
||||
jail: string;
|
||||
/** When the ban was placed, in the machine's local time as fail2ban prints it. */
|
||||
since: string;
|
||||
/** When the ban ends; "never" for a permanent ban. */
|
||||
until: string;
|
||||
}
|
||||
|
||||
export interface JailSettings {
|
||||
jail: string;
|
||||
bantime: string;
|
||||
findtime: string;
|
||||
maxretry: number;
|
||||
ignoreip: string[];
|
||||
actions: string[];
|
||||
/** The log files the jail reads, when it reads files. */
|
||||
logpath: string[];
|
||||
/** The journal match the jail reads, when it reads the journal. */
|
||||
journalmatch: string;
|
||||
}
|
||||
const run = promisify(execFile);
|
||||
|
||||
export class Fail2banClient {
|
||||
private readonly run: Runner;
|
||||
|
||||
constructor(run: Runner = execRunner) {
|
||||
this.run = run;
|
||||
}
|
||||
|
||||
static fromEnv(_env: NodeJS.ProcessEnv = process.env): Fail2banClient {
|
||||
return new Fail2banClient();
|
||||
}
|
||||
|
||||
private client(...args: string[]): Promise<string> {
|
||||
return this.run("fail2ban-client", args);
|
||||
}
|
||||
|
||||
/** The jails the daemon runs, by name. */
|
||||
async jails(): Promise<string[]> {
|
||||
const out = await this.client("status");
|
||||
const m = out.match(/Jail list:\s*(.*)/);
|
||||
if (!m) return [];
|
||||
return m[1].split(",").map((j) => j.trim()).filter(Boolean);
|
||||
}
|
||||
|
||||
/** Every jail with what it watches and holds, or one jail's detail. */
|
||||
async status(jail?: string): Promise<{ jails: JailStatus[] }> {
|
||||
const names = jail ? [jail] : await this.jails();
|
||||
const jails: JailStatus[] = [];
|
||||
for (const name of names) {
|
||||
jails.push(parseJailStatus(name, await this.client("status", name)));
|
||||
}
|
||||
return { jails };
|
||||
}
|
||||
|
||||
/** Every address banned now, with the jail holding it and when the ban ends. */
|
||||
async banned(jail?: string): Promise<{ banned: Ban[] }> {
|
||||
const names = jail ? [jail] : await this.jails();
|
||||
const banned: Ban[] = [];
|
||||
for (const name of names) {
|
||||
banned.push(...parseBans(name, await this.client("get", name, "banip", "--with-time")));
|
||||
}
|
||||
banned.sort((a, b) => a.until.localeCompare(b.until) || a.ip.localeCompare(b.ip));
|
||||
return { banned };
|
||||
}
|
||||
|
||||
/** Ban one address in one jail now. The daemon's own answer is how many addresses it added. */
|
||||
async ban(ip: string, jail: string): Promise<{ banned: Ban | null; added: number }> {
|
||||
address(ip);
|
||||
name(jail);
|
||||
const out = await this.client("set", jail, "banip", ip);
|
||||
const added = Number.parseInt(out.trim(), 10) || 0;
|
||||
const held = (await this.banned(jail)).banned.find((b) => b.ip === ip) ?? null;
|
||||
return { banned: held, added };
|
||||
}
|
||||
|
||||
/** Let one address go, from one jail or from every jail. The daemon's answer is how many it released. */
|
||||
async unban(ip: string, jail?: string): Promise<{ released: number; ip: string; jail: string | "every jail" }> {
|
||||
address(ip);
|
||||
let out: string;
|
||||
/** Overview of every jail, or the detailed status of one — currently-banned IPs and totals. */
|
||||
async status(jail?: string): Promise<string> {
|
||||
if (jail) {
|
||||
name(jail);
|
||||
out = await this.client("set", jail, "unbanip", ip);
|
||||
} else {
|
||||
out = await this.client("unban", ip);
|
||||
const { stdout } = await run("sudo", ["fail2ban-client", "status", jail]);
|
||||
return stdout;
|
||||
}
|
||||
return { released: Number.parseInt(out.trim(), 10) || 0, ip, jail: jail ?? "every jail" };
|
||||
const { stdout: overview } = await run("sudo", ["fail2ban-client", "status"]);
|
||||
const match = overview.match(/Jail list:\s*(.+)/);
|
||||
if (!match) return overview;
|
||||
|
||||
const jails = match[1].split(",").map((j) => j.trim()).filter(Boolean);
|
||||
const parts: string[] = [overview.trimEnd(), ""];
|
||||
for (const j of jails) {
|
||||
const { stdout } = await run("sudo", ["fail2ban-client", "status", j]);
|
||||
parts.push(`=== ${j} ===`, stdout.trimEnd(), "");
|
||||
}
|
||||
return parts.join("\n");
|
||||
}
|
||||
|
||||
/** One jail's effective settings — the module's own tool, beside the seat's verbs. */
|
||||
async settings(jail: string): Promise<JailSettings> {
|
||||
name(jail);
|
||||
const get = (key: string) => this.client("get", jail, key);
|
||||
const [bantime, findtime, maxretry, ignoreip, actions, logpath, journalmatch] = await Promise.all([
|
||||
get("bantime"), get("findtime"), get("maxretry"), get("ignoreip"), get("actions"), get("logpath"),
|
||||
get("journalmatch"),
|
||||
]);
|
||||
return {
|
||||
jail,
|
||||
bantime: bantime.trim(),
|
||||
findtime: findtime.trim(),
|
||||
maxretry: Number.parseInt(maxretry.trim(), 10),
|
||||
ignoreip: listed(ignoreip),
|
||||
actions: actions.split("\n").slice(1).map((l) => l.trim()).filter(Boolean),
|
||||
logpath: /No file is currently monitored/.test(logpath) ? [] : listed(logpath),
|
||||
journalmatch: journalmatch.split("\n").slice(1).map((l) => l.trim()).filter(Boolean).join(" "),
|
||||
};
|
||||
/** Manually ban an IP in a jail. Mutates live state, not a mesh-managed file. */
|
||||
async ban(jail: string, ip: string): Promise<string> {
|
||||
const { stdout } = await run("sudo", ["fail2ban-client", "set", jail, "banip", ip]);
|
||||
return stdout;
|
||||
}
|
||||
|
||||
/** Unban an IP from one jail, or from every jail when no jail is given. */
|
||||
async unban(ip: string, jail?: string): Promise<string> {
|
||||
const args = jail
|
||||
? ["fail2ban-client", "set", jail, "unbanip", ip]
|
||||
: ["fail2ban-client", "unban", ip];
|
||||
const { stdout } = await run("sudo", args);
|
||||
return stdout;
|
||||
}
|
||||
}
|
||||
|
||||
/** fail2ban's tree listings: lines like "|- 127.0.0.0/8" and "`- ::1", after a heading. */
|
||||
function listed(out: string): string[] {
|
||||
return out
|
||||
.split("\n")
|
||||
.map((l) => l.replace(/^[\s|`-]+/, "").trim())
|
||||
.filter((l, i) => i > 0 && l.length > 0);
|
||||
}
|
||||
|
||||
export function parseJailStatus(jail: string, out: string): JailStatus {
|
||||
const field = (label: string) => {
|
||||
const m = out.match(new RegExp(label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + ":\\t?\\s*(.*)"));
|
||||
return m ? m[1].trim() : "";
|
||||
};
|
||||
const num = (label: string) => Number.parseInt(field(label), 10) || 0;
|
||||
const watching = [field("File list"), field("Journal matches")].filter(Boolean);
|
||||
return {
|
||||
jail,
|
||||
watching,
|
||||
failing: { now: num("Currently failed"), total: num("Total failed") },
|
||||
banned: {
|
||||
now: num("Currently banned"),
|
||||
total: num("Total banned"),
|
||||
addresses: field("Banned IP list").split(/\s+/).filter(Boolean),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** `get <jail> banip --with-time` prints one ban per line: "IP \tsince + seconds = until". */
|
||||
export function parseBans(jail: string, out: string): Ban[] {
|
||||
const bans: Ban[] = [];
|
||||
for (const line of out.split("\n")) {
|
||||
const m = line.match(/^(\S+)\s+(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \+ (-?\d+) = (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}|\S+)/);
|
||||
if (!m) continue;
|
||||
bans.push({ ip: m[1], jail, since: m[2], until: Number(m[3]) < 0 ? "never" : m[4] });
|
||||
}
|
||||
return bans;
|
||||
}
|
||||
|
||||
function address(ip: string): void {
|
||||
if (!isIP(ip)) throw new Error(`${JSON.stringify(ip)} is not an address`);
|
||||
}
|
||||
|
||||
function name(jail: string): void {
|
||||
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(jail)) throw new Error(`${JSON.stringify(jail)} is not a jail's name`);
|
||||
}
|
||||
|
||||
@@ -7,25 +7,9 @@
|
||||
"claims": [
|
||||
{
|
||||
"name": "node-intrusion-prevention",
|
||||
"scope": "node",
|
||||
"serves": [
|
||||
"status",
|
||||
"banned",
|
||||
"ban",
|
||||
"unban"
|
||||
]
|
||||
"scope": "node"
|
||||
}
|
||||
],
|
||||
"tools": [
|
||||
"fail2ban_settings"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"jailing": {
|
||||
"into": "/etc/fail2ban/jail.d/mesh.conf",
|
||||
"filter-into": "/etc/fail2ban/filter.d"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "package",
|
||||
@@ -44,37 +28,19 @@
|
||||
"path": "/etc/fail2ban/action.d",
|
||||
"mode": "0755"
|
||||
},
|
||||
{
|
||||
"id": "filter-d",
|
||||
"type": "directory",
|
||||
"path": "/etc/fail2ban/filter.d",
|
||||
"mode": "0755"
|
||||
},
|
||||
{
|
||||
"id": "run-dir",
|
||||
"type": "directory",
|
||||
"path": "/var/run/fail2ban",
|
||||
"mode": "0755"
|
||||
},
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "jail-local",
|
||||
"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.\n# **A ban list never holds a neighbour.** The mesh's own range is named rather than written\n# (novox/hq ADR 0112), and every private range beside it: a source on one is somebody's own\n# network, not the internet. On a machine behind a router that reflects local traffic, every\n# client in the house arrives as the gateway's address — so one mistyped local request banned\n# 192.168.1.1 on the home server and would have cut the whole house off from it (ADR 0186).\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range} 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 fc00::/7 fe80::/10\n\n# Three failures in a day ban for a day (novox/hq ADR 0179). The attackers this mesh sees pace\n# themselves at one try every ten minutes, under any ten-minute window; a day's window counts\n# them, and a day's ban costs a person who mistyped three times once, from one address, while\n# the mesh's own range is never banned at all.\nbantime = 1d\nfindtime = 1d\nmaxretry = 3\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"
|
||||
"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",
|
||||
"type": "file",
|
||||
"path": "/etc/fail2ban/jail.d/sshd.conf",
|
||||
"mode": "0644",
|
||||
"content": "[sshd]\nenabled = true\nport = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 3\nfindtime = 1d\nbantime = 1d\n"
|
||||
"content": "[sshd]\nenabled = true\nport = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 5\n"
|
||||
},
|
||||
{
|
||||
"id": "log",
|
||||
@@ -89,7 +55,7 @@
|
||||
"type": "file",
|
||||
"path": "/etc/fail2ban/jail.d/recidive.conf",
|
||||
"mode": "0644",
|
||||
"content": "[recidive]\nenabled = true\nlogpath = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\n# Banned twice in two weeks, by any jail, is banned for four (novox/hq ADR 0179).\nbantime = 4w\nfindtime = 2w\nmaxretry = 2\n"
|
||||
"content": "[recidive]\nenabled = true\nlogpath = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\nbantime = 1w\nfindtime = 1d\n"
|
||||
},
|
||||
{
|
||||
"id": "action-dualchain",
|
||||
@@ -115,44 +81,8 @@
|
||||
"jail-local",
|
||||
"jail-sshd",
|
||||
"jail-recidive",
|
||||
"action-dualchain",
|
||||
"composed-jails"
|
||||
"action-dualchain"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-fail2ban",
|
||||
"artifact": "runtime",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"/var/run/fail2ban:/var/run/fail2ban"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker"
|
||||
}
|
||||
}
|
||||
],
|
||||
"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,18 +1,14 @@
|
||||
{
|
||||
"name": "@novox/module-fail2ban",
|
||||
"version": "0.1.0",
|
||||
"description": "fail2ban \u2014 intrusion prevention: the mesh composes the jails and keeps the daemon running; this module holds the node-intrusion-prevention seat and serves its verbs status, banned, ban and unban (novox/hq to-be 31, ADR 0179).",
|
||||
"description": "fail2ban — intrusion prevention: the mesh declares the jails and keeps the daemon running; its ban/unban/status tools live here.",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.1"
|
||||
"@novox/mesh-sdk": "^0.1.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
"typescript": "^5.6.0"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
|
||||
"test": "node --test --experimental-strip-types 'test/*.test.ts'"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,106 +0,0 @@
|
||||
// The intrusion prevention's verbs over a fake daemon, with the shapes fail2ban-client 1.1.0 printed
|
||||
// on the control node on 2026-10-02 (novox/hq ADR 0179).
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { Fail2banClient, parseBans, parseJailStatus, type Runner } from "../client.ts";
|
||||
|
||||
const STATUS = "Status\n|- Number of jail:\t2\n`- Jail list:\trecidive, sshd\n";
|
||||
const RECIDIVE =
|
||||
"Status for the jail: recidive\n|- Filter\n| |- Currently failed:\t36\n| |- Total failed:\t149\n" +
|
||||
"| `- File list:\t/var/log/fail2ban.log\n`- Actions\n |- Currently banned:\t9\n |- Total banned:\t13\n" +
|
||||
" `- Banned IP list:\t195.178.110.30 45.148.10.240 92.118.39.71\n";
|
||||
const SSHD =
|
||||
"Status for the jail: sshd\n|- Filter\n| |- Currently failed:\t5\n| |- Total failed:\t11776\n" +
|
||||
"| `- Journal matches:\t_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n`- Actions\n |- Currently banned:\t0\n" +
|
||||
" |- Total banned:\t150\n `- Banned IP list:\t\n";
|
||||
const WITH_TIME =
|
||||
"195.178.110.30 \t2026-09-26 23:18:47 + 604800 = 2026-10-03 23:18:47\n" +
|
||||
"92.118.39.71 \t2026-09-28 10:33:49 + 604800 = 2026-10-05 10:33:49\n";
|
||||
|
||||
function fake(answers: Record<string, string>, calls: string[][] = []): Runner {
|
||||
return async (cmd, args) => {
|
||||
calls.push([cmd, ...args]);
|
||||
const key = args.join(" ");
|
||||
if (key in answers) return answers[key];
|
||||
throw new Error(`unexpected ${cmd} ${key}`);
|
||||
};
|
||||
}
|
||||
|
||||
test("a jail's status is read into numbers, what it watches and who it holds", () => {
|
||||
const s = parseJailStatus("recidive", RECIDIVE);
|
||||
assert.deepEqual(s, {
|
||||
jail: "recidive",
|
||||
watching: ["/var/log/fail2ban.log"],
|
||||
failing: { now: 36, total: 149 },
|
||||
banned: { now: 9, total: 13, addresses: ["195.178.110.30", "45.148.10.240", "92.118.39.71"] },
|
||||
});
|
||||
const j = parseJailStatus("sshd", SSHD);
|
||||
assert.deepEqual(j.watching, ["_SYSTEMD_UNIT=sshd.service + _COMM=sshd"]);
|
||||
assert.deepEqual(j.banned, { now: 0, total: 150, addresses: [] });
|
||||
});
|
||||
|
||||
test("status covers every jail the daemon lists, or the one named", async () => {
|
||||
const calls: string[][] = [];
|
||||
const f = new Fail2banClient(fake({ status: STATUS, "status recidive": RECIDIVE, "status sshd": SSHD }, calls));
|
||||
const all = await f.status();
|
||||
assert.deepEqual(all.jails.map((j) => j.jail), ["recidive", "sshd"]);
|
||||
const one = await f.status("sshd");
|
||||
assert.equal(one.jails.length, 1);
|
||||
assert.deepEqual(calls[calls.length - 1], ["fail2ban-client", "status", "sshd"]);
|
||||
});
|
||||
|
||||
test("bans are read with when they were placed and when they end, a permanent one as never", () => {
|
||||
const bans = parseBans("recidive", WITH_TIME + "203.0.113.9 \t2026-10-01 00:00:00 + -1 = never\n");
|
||||
assert.equal(bans.length, 3);
|
||||
assert.deepEqual(bans[0], { ip: "195.178.110.30", jail: "recidive", since: "2026-09-26 23:18:47", until: "2026-10-03 23:18:47" });
|
||||
assert.equal(bans[2].until, "never");
|
||||
assert.deepEqual(parseBans("sshd", "\n"), []);
|
||||
});
|
||||
|
||||
test("banned gathers every jail's bans, soonest to end first", async () => {
|
||||
const f = new Fail2banClient(fake({
|
||||
status: STATUS,
|
||||
"get recidive banip --with-time": WITH_TIME,
|
||||
"get sshd banip --with-time": "198.51.100.7 \t2026-10-02 15:06:58 + 600 = 2026-10-02 15:16:58\n",
|
||||
}));
|
||||
const { banned } = await f.banned();
|
||||
assert.deepEqual(banned.map((b) => `${b.ip}@${b.jail}`), ["198.51.100.7@sshd", "195.178.110.30@recidive", "92.118.39.71@recidive"]);
|
||||
});
|
||||
|
||||
test("ban asks the daemon by jail and answers with the ban as held; a non-address is refused before anything runs", async () => {
|
||||
const calls: string[][] = [];
|
||||
const f = new Fail2banClient(fake({
|
||||
"set recidive banip 198.51.100.7": "1\n",
|
||||
"get recidive banip --with-time": WITH_TIME + "198.51.100.7 \t2026-10-02 17:00:00 + 604800 = 2026-10-09 17:00:00\n",
|
||||
}, calls));
|
||||
const r = await f.ban("198.51.100.7", "recidive");
|
||||
assert.equal(r.added, 1);
|
||||
assert.equal(r.banned?.until, "2026-10-09 17:00:00");
|
||||
assert.deepEqual(calls[0], ["fail2ban-client", "set", "recidive", "banip", "198.51.100.7"]);
|
||||
await assert.rejects(() => f.ban("not-an-ip", "recidive"), /is not an address/);
|
||||
await assert.rejects(() => f.ban("198.51.100.7", "a jail; rm"), /is not a jail's name/);
|
||||
assert.equal(calls.length, 2);
|
||||
});
|
||||
|
||||
test("unban releases from one jail or from every jail", async () => {
|
||||
const calls: string[][] = [];
|
||||
const f = new Fail2banClient(fake({ "set sshd unbanip 198.51.100.7": "1\n", "unban 198.51.100.7": "2\n" }, calls));
|
||||
assert.deepEqual(await f.unban("198.51.100.7", "sshd"), { released: 1, ip: "198.51.100.7", jail: "sshd" });
|
||||
assert.deepEqual(await f.unban("198.51.100.7"), { released: 2, ip: "198.51.100.7", jail: "every jail" });
|
||||
assert.deepEqual(calls[1], ["fail2ban-client", "unban", "198.51.100.7"]);
|
||||
});
|
||||
|
||||
test("a jail's settings are read from the daemon's listings", async () => {
|
||||
const f = new Fail2banClient(fake({
|
||||
"get sshd bantime": "86400\n", "get sshd findtime": "86400\n", "get sshd maxretry": "3\n",
|
||||
"get sshd ignoreip": "These IP addresses/networks are ignored:\n|- 127.0.0.0/8\n|- 10.10.0.0/24\n`- ::1\n",
|
||||
"get sshd actions": "The jail sshd has the following actions:\niptables-allports-dualchain\n",
|
||||
"get sshd logpath": "No file is currently monitored\n",
|
||||
"get sshd journalmatch": "Current match filter:\n_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n",
|
||||
}));
|
||||
assert.deepEqual(await f.settings("sshd"), {
|
||||
jail: "sshd", bantime: "86400", findtime: "86400", maxretry: 3,
|
||||
ignoreip: ["127.0.0.0/8", "10.10.0.0/24", "::1"], actions: ["iptables-allports-dualchain"],
|
||||
logpath: [], journalmatch: "_SYSTEMD_UNIT=sshd.service + _COMM=sshd",
|
||||
});
|
||||
});
|
||||
@@ -1,62 +1,55 @@
|
||||
// The intrusion prevention's tools: the node-intrusion-prevention seat's four verbs — who is banned,
|
||||
// the jails' state, ban one, let one go — and the module's own reading of a jail's settings
|
||||
// (novox/hq to-be 31, ADR 0179). The jails themselves are composed by the mesh from the modules a
|
||||
// machine runs and written as declared resources; these touch only what the running daemon holds.
|
||||
// fail2ban's tools — reading and steering the live ban state. The jails themselves are declared
|
||||
// resources (module.json); these three touch what the running daemon holds: what is banned now,
|
||||
// and the manual ban/unban an operator reaches for. The daemon's state is fail2ban's own, so this
|
||||
// is the only way to see or change it — the mesh reconciles the config, not the bans.
|
||||
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { Fail2banClient } from "../client.js";
|
||||
|
||||
export function getSeatVerbs(fail2ban: Fail2banClient): ToolDefinition[] {
|
||||
return [
|
||||
{
|
||||
name: "status",
|
||||
description:
|
||||
"Every jail on this machine with what it watches, how many addresses it is counting failures against and holding now, and the totals since it started; one jail's detail when named.",
|
||||
input: { jail: { type: "string", description: "one jail (optional)" } },
|
||||
run: async (args) => fail2ban.status(args.jail ? String(args.jail) : undefined),
|
||||
},
|
||||
{
|
||||
name: "banned",
|
||||
description: "Every address banned on this machine right now, with the jail that holds it, when it was banned and when the ban ends.",
|
||||
input: { jail: { type: "string", description: "one jail (optional)" } },
|
||||
run: async (args) => fail2ban.banned(args.jail ? String(args.jail) : undefined),
|
||||
},
|
||||
{
|
||||
name: "ban",
|
||||
description:
|
||||
"Ban one address in one jail now, for the jail's ban time — an operator's act on the live ban list, which the mesh never writes itself.",
|
||||
input: {
|
||||
ip: { type: "string", description: "the address" },
|
||||
jail: { type: "string", description: "the jail to hold it (recidive for the long ban)" },
|
||||
},
|
||||
run: async (args) => fail2ban.ban(String(args.ip ?? ""), String(args.jail ?? "")),
|
||||
},
|
||||
{
|
||||
name: "unban",
|
||||
description: "Let one address go, from one jail or from every jail when none is named.",
|
||||
input: {
|
||||
ip: { type: "string", description: "the address" },
|
||||
jail: { type: "string", description: "one jail (optional)" },
|
||||
},
|
||||
run: async (args) => fail2ban.unban(String(args.ip ?? ""), args.jail ? String(args.jail) : undefined),
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
|
||||
return [
|
||||
{
|
||||
name: "fail2ban_settings",
|
||||
name: "fail2ban_status",
|
||||
description:
|
||||
"One jail's effective settings on this machine: ban time, window, tries, the addresses it never bans, its actions and what it reads.",
|
||||
input: { jail: { type: "string", description: "the jail" } },
|
||||
run: async (args) => fail2ban.settings(String(args.jail ?? "")),
|
||||
"fail2ban status on this node — the jails and their live bans. Omit `jail` for every jail, or name one for its detail.",
|
||||
input: {
|
||||
type: "object",
|
||||
properties: {
|
||||
jail: {
|
||||
type: "string",
|
||||
description: "A specific jail (e.g. sshd, recidive); omit for the overview of all jails.",
|
||||
},
|
||||
},
|
||||
},
|
||||
run: async (args) => ({ status: await fail2ban.status(args.jail as string | undefined) }),
|
||||
},
|
||||
{
|
||||
name: "fail2ban_ban",
|
||||
description: "Manually ban an IP address in a jail — a live change to the running daemon, not a mesh-managed file.",
|
||||
input: {
|
||||
type: "object",
|
||||
properties: {
|
||||
jail: { type: "string", description: "Jail name (e.g. sshd, recidive)." },
|
||||
ip: { type: "string", description: "IP address to ban." },
|
||||
},
|
||||
required: ["jail", "ip"],
|
||||
},
|
||||
run: async (args) => ({ result: await fail2ban.ban(args.jail as string, args.ip as string) }),
|
||||
},
|
||||
{
|
||||
name: "fail2ban_unban",
|
||||
description: "Unban an IP address from one jail, or from every jail when `jail` is omitted.",
|
||||
input: {
|
||||
type: "object",
|
||||
properties: {
|
||||
ip: { type: "string", description: "IP address to unban." },
|
||||
jail: { type: "string", description: "A specific jail; omit to unban from all jails." },
|
||||
},
|
||||
required: ["ip"],
|
||||
},
|
||||
run: async (args) => ({ result: await fail2ban.unban(args.ip as string, args.jail as string | undefined) }),
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
const fail2ban = Fail2banClient.fromEnv();
|
||||
// The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
|
||||
// module holds it (ADR 0159, 0160). The module's own under its own.
|
||||
registerModuleTools("node-intrusion-prevention", () => getSeatVerbs(fail2ban));
|
||||
registerModuleTools("fail2ban", () => getFail2banTools(fail2ban));
|
||||
registerModuleTools("fail2ban", () => getFail2banTools(Fail2banClient.fromEnv()));
|
||||
|
||||
@@ -45,14 +45,6 @@ export interface GiteaPull {
|
||||
html_url: string;
|
||||
}
|
||||
|
||||
export interface GiteaComment {
|
||||
id: number;
|
||||
user?: string;
|
||||
body: string;
|
||||
created_at?: string;
|
||||
html_url: string;
|
||||
}
|
||||
|
||||
export interface GiteaLabel {
|
||||
id: number;
|
||||
name: string;
|
||||
@@ -103,13 +95,6 @@ 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;
|
||||
@@ -265,64 +250,6 @@ export class GiteaClient {
|
||||
);
|
||||
}
|
||||
|
||||
/** Close or reopen a pull request without merging it. A pull request is an issue to the forge's
|
||||
* state machine, and the pulls endpoint takes the same `state`. */
|
||||
async setPullState(owner: string, repo: string, index: number, state: "open" | "closed"): Promise<GiteaPull> {
|
||||
return GiteaClient.mapPull(
|
||||
await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`, { method: "PATCH", body: JSON.stringify({ state }) }),
|
||||
);
|
||||
}
|
||||
|
||||
/** Change a pull request's title or body; a field left undefined is left alone. */
|
||||
async updatePullRequest(owner: string, repo: string, index: number, data: { title?: string; body?: string }): Promise<GiteaPull> {
|
||||
return GiteaClient.mapPull(
|
||||
await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`, { method: "PATCH", body: JSON.stringify(data) }),
|
||||
);
|
||||
}
|
||||
|
||||
/** The unified diff of a pull request, as text. */
|
||||
async pullDiff(owner: string, repo: string, index: number): Promise<string> {
|
||||
return this.requestText(`/repos/${owner}/${repo}/pulls/${index}.diff`);
|
||||
}
|
||||
|
||||
/** Every comment on an issue or pull request, oldest first. */
|
||||
async listComments(owner: string, repo: string, index: number): Promise<GiteaComment[]> {
|
||||
const raw = await this.request<any[]>(`/repos/${owner}/${repo}/issues/${index}/comments`);
|
||||
return (raw ?? []).map((c) => ({
|
||||
id: Number(c?.id ?? 0),
|
||||
user: c?.user?.login,
|
||||
body: String(c?.body ?? ""),
|
||||
created_at: c?.created_at,
|
||||
html_url: String(c?.html_url ?? ""),
|
||||
}));
|
||||
}
|
||||
|
||||
/** One file's contents at a ref (default the repository's default branch), decoded. */
|
||||
async getFile(owner: string, repo: string, path: string, ref?: string): Promise<{ path: string; ref?: string; sha: string; size: number; content: string }> {
|
||||
const qs = ref ? `?ref=${encodeURIComponent(ref)}` : "";
|
||||
const f = await this.request<any>(`/repos/${owner}/${repo}/contents/${path.split("/").map(encodeURIComponent).join("/")}${qs}`);
|
||||
if (!f || f.type !== "file") throw new Error(`Gitea API: ${path} is not a file`);
|
||||
const content = f.encoding === "base64" ? Buffer.from(String(f.content ?? ""), "base64").toString("utf8") : String(f.content ?? "");
|
||||
return { path, ref, sha: String(f.sha ?? ""), size: Number(f.size ?? content.length), content };
|
||||
}
|
||||
|
||||
async listBranches(owner: string, repo: string): Promise<{ name: string; commit: string; protected: boolean }[]> {
|
||||
const raw = await this.request<any[]>(`/repos/${owner}/${repo}/branches?limit=100`);
|
||||
return (raw ?? []).map((b) => ({ name: String(b?.name ?? ""), commit: String(b?.commit?.id ?? ""), protected: Boolean(b?.protected) }));
|
||||
}
|
||||
|
||||
async deleteBranch(owner: string, repo: string, branch: string): Promise<void> {
|
||||
await this.request(`/repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}`, { method: "DELETE" });
|
||||
}
|
||||
|
||||
/** A request whose answer is text, not JSON — a diff. Same token handling as request(). */
|
||||
private async requestText(path: string): Promise<string> {
|
||||
const token = await this.tokens.current();
|
||||
const res = await this.send(path, { headers: { Accept: "text/plain" } }, token);
|
||||
if (!res.ok) throw new Error(`Gitea API ${path}: ${res.status} ${await res.text()}`);
|
||||
return res.text();
|
||||
}
|
||||
|
||||
async mergePullRequest(owner: string, repo: string, index: number, method = "merge", deleteBranch = false): Promise<void> {
|
||||
await this.request(`/repos/${owner}/${repo}/pulls/${index}/merge`, {
|
||||
method: "POST",
|
||||
|
||||
+10
-18
@@ -86,19 +86,19 @@
|
||||
}
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/gitea/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/gitea",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "runtime-state",
|
||||
"type": "directory",
|
||||
"path": "${dir:mesh-state}/state",
|
||||
"path": "/var/lib/mesh/gitea/state",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
@@ -145,8 +145,7 @@
|
||||
"volumes": [
|
||||
"${dir:data}:/data"
|
||||
],
|
||||
"secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it",
|
||||
"logging": "journald"
|
||||
"secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it"
|
||||
},
|
||||
{
|
||||
"id": "admin-bootstrap",
|
||||
@@ -176,7 +175,7 @@
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/gitea/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
@@ -187,11 +186,11 @@
|
||||
"name": "mesh-gitea",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"/var/lib/mesh/gitea/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/gitea/config.json:/run/config/config.json:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:state}/admin.secret:/run/secrets/admin:ro",
|
||||
"${dir:runtime-state}:/run/state"
|
||||
"/var/lib/mesh/gitea/state:/run/state"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
@@ -238,12 +237,5 @@
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
},
|
||||
"jails": [
|
||||
{
|
||||
"name": "gitea",
|
||||
"failregex": "^.*Failed authentication attempt for .* from <HOST>(?::\\d+)?\\s*$",
|
||||
"jail": "backend = systemd\njournalmatch = CONTAINER_NAME=gitea\nport = http,https,222\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -29,11 +29,7 @@ interface Forge {
|
||||
mints: number;
|
||||
lastScopes: string[] | null;
|
||||
tokens: Map<string, string>;
|
||||
scopesOf: Map<string, string[]>;
|
||||
admins: Map<string, string>;
|
||||
pullState: string;
|
||||
pullTitle: string;
|
||||
branchDeleted: boolean;
|
||||
close(): Promise<void>;
|
||||
}
|
||||
|
||||
@@ -44,9 +40,6 @@ function fakeForge(): Promise<Forge> {
|
||||
tokens: new Map<string, string>(), // name -> value
|
||||
scopesOf: new Map<string, string[]>(), // value -> scopes, so a route can enforce them like gitea does
|
||||
admins: new Map([[ADMIN, PASSWORD]]),
|
||||
pullState: "open",
|
||||
pullTitle: "The console shipped",
|
||||
branchDeleted: false,
|
||||
};
|
||||
// write:X implies read:X — gitea's own rule (models/auth/access_token_scope.go).
|
||||
const covers = (scopes: string[], required: string): boolean =>
|
||||
@@ -92,51 +85,6 @@ function fakeForge(): Promise<Forge> {
|
||||
}
|
||||
return json(res, 405, { message: "method not allowed" });
|
||||
}
|
||||
const tokenOf = (): string => {
|
||||
const h = req.headers.authorization ?? "";
|
||||
return h.startsWith("token ") ? h.slice(6) : "";
|
||||
};
|
||||
const pull = url.pathname.match(/^\/api\/v1\/repos\/novox\/hq\/pulls\/(\d+)(\.diff)?$/);
|
||||
if (pull) {
|
||||
if (![...forge.tokens.values()].includes(tokenOf())) return json(res, 401, { message: "token is required" });
|
||||
if (pull[2]) {
|
||||
res.writeHead(200, { "Content-Type": "text/plain" });
|
||||
return res.end("diff --git a/x b/x\n--- a/x\n+++ b/x\n@@ -1 +1 @@\n-old\n+new\n");
|
||||
}
|
||||
if (req.method === "PATCH") {
|
||||
const patch = await body(req);
|
||||
forge.pullState = patch?.state ?? forge.pullState;
|
||||
forge.pullTitle = patch?.title ?? forge.pullTitle;
|
||||
}
|
||||
return json(res, 200, { number: Number(pull[1]), title: forge.pullTitle, state: forge.pullState, merged: false,
|
||||
user: { login: "mesh-admin" }, head: { ref: "feat/x" }, base: { ref: "main" }, html_url: "http://fake/novox/hq/pulls/" + pull[1] });
|
||||
}
|
||||
if (url.pathname === "/api/v1/repos/novox/hq/issues/223/comments") {
|
||||
return json(res, 200, [{ id: 1, user: { login: "jochen" }, body: "landed elsewhere", created_at: "2026-10-01T00:00:00Z", html_url: "http://fake/c/1" }]);
|
||||
}
|
||||
if (url.pathname === "/api/v1/repos/novox/hq/contents/README.md") {
|
||||
return json(res, 200, { type: "file", encoding: "base64", sha: "abc", size: 5, content: Buffer.from("hello").toString("base64") });
|
||||
}
|
||||
if (url.pathname === "/api/v1/repos/novox/hq/branches") {
|
||||
return json(res, 200, [{ name: "main", protected: true, commit: { id: "aaaa" } }, { name: "feat/x", protected: false, commit: { id: "bbbb" } }]);
|
||||
}
|
||||
if (url.pathname === "/api/v1/repos/novox/hq/branches/feat%2Fx" || url.pathname === "/api/v1/repos/novox/hq/branches/feat/x") {
|
||||
if (req.method === "DELETE") { forge.branchDeleted = true; return json(res, 204, null); }
|
||||
}
|
||||
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) : "";
|
||||
@@ -153,21 +101,6 @@ 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) => {
|
||||
@@ -177,11 +110,7 @@ function fakeForge(): Promise<Forge> {
|
||||
url: `http://127.0.0.1:${port}`,
|
||||
get mints() { return forge.mints; },
|
||||
get lastScopes() { return forge.lastScopes; },
|
||||
get pullState() { return forge.pullState; },
|
||||
get pullTitle() { return forge.pullTitle; },
|
||||
get branchDeleted() { return forge.branchDeleted; },
|
||||
tokens: forge.tokens,
|
||||
scopesOf: forge.scopesOf,
|
||||
admins: forge.admins,
|
||||
close: () => new Promise((r) => server.close(() => r())),
|
||||
});
|
||||
@@ -223,14 +152,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 the tools' scopes only", async () => {
|
||||
test("first start: mints with the admin account, keeps the token at 0600, asks for two 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", "write:admin"]);
|
||||
assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user"]);
|
||||
assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]);
|
||||
const token = forge.tokens.get("mesh-tools")!;
|
||||
assert.equal(await readFile(file, "utf8"), token + "\n");
|
||||
@@ -268,34 +197,6 @@ 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();
|
||||
@@ -400,16 +301,6 @@ test("the tools register once there is a way to a token, and the first call mint
|
||||
"gitea_list_repos", "gitea_create_repo", "gitea_delete_repo",
|
||||
"gitea_list_issues", "gitea_get_issue", "gitea_create_issue", "gitea_close_issue", "gitea_add_comment",
|
||||
"gitea_list_pull_requests", "gitea_get_pull_request", "gitea_create_pull_request", "gitea_merge_pull_request",
|
||||
"gitea_close_pull_request",
|
||||
"gitea_reopen_pull_request",
|
||||
"gitea_update_pull_request",
|
||||
"gitea_pull_request_files",
|
||||
"gitea_pull_request_diff",
|
||||
"gitea_list_comments",
|
||||
"gitea_reopen_issue",
|
||||
"gitea_get_file",
|
||||
"gitea_list_branches",
|
||||
"gitea_delete_branch",
|
||||
"gitea_list_labels", "gitea_create_label",
|
||||
"gitea_api",
|
||||
],
|
||||
@@ -420,32 +311,3 @@ test("the tools register once there is a way to a token, and the first call mint
|
||||
assert.equal(result.repos.length, 1);
|
||||
assert.equal(forge.mints, before + 1);
|
||||
});
|
||||
|
||||
// The forge's tools reach every action a review needs without a checkout and without the API
|
||||
// escape hatch: close a pull request whose work landed elsewhere, read its diff, its comments, a
|
||||
// file, the branches, and delete the branch left behind. Against the fake forge, through the
|
||||
// compiled tools, the way the console calls them.
|
||||
test("a pull request can be closed, read and cleaned up through the tools", async () => {
|
||||
const { env } = await delivered(forge);
|
||||
const tools = collectTools(env).find((c) => c.module === "gitea")!.tools;
|
||||
const tool = (name: string) => tools.find((t) => t.name === name)!;
|
||||
for (const name of ["gitea_close_pull_request", "gitea_reopen_pull_request", "gitea_update_pull_request", "gitea_pull_request_files",
|
||||
"gitea_pull_request_diff", "gitea_list_comments", "gitea_reopen_issue", "gitea_get_file", "gitea_list_branches", "gitea_delete_branch"]) {
|
||||
assert.ok(tool(name), `${name} is not a tool`);
|
||||
}
|
||||
const closed = (await tool("gitea_close_pull_request").run({ owner: "novox", repo: "hq", number: 223 })) as { pull: { state: string } };
|
||||
assert.equal(closed.pull.state, "closed");
|
||||
assert.equal(forge.pullState, "closed");
|
||||
const renamed = (await tool("gitea_update_pull_request").run({ owner: "novox", repo: "hq", number: 223, title: "Superseded" })) as { pull: { title: string } };
|
||||
assert.equal(renamed.pull.title, "Superseded");
|
||||
const diff = (await tool("gitea_pull_request_diff").run({ owner: "novox", repo: "hq", number: 223 })) as { diff: string };
|
||||
assert.match(diff.diff, /^diff --git/);
|
||||
const comments = (await tool("gitea_list_comments").run({ owner: "novox", repo: "hq", number: 223 })) as { comments: { body: string }[] };
|
||||
assert.equal(comments.comments[0].body, "landed elsewhere");
|
||||
const file = (await tool("gitea_get_file").run({ owner: "novox", repo: "hq", path: "README.md" })) as { file: { content: string } };
|
||||
assert.equal(file.file.content, "hello");
|
||||
const branches = (await tool("gitea_list_branches").run({ owner: "novox", repo: "hq" })) as { branches: { name: string }[] };
|
||||
assert.deepEqual(branches.branches.map((b) => b.name), ["main", "feat/x"]);
|
||||
await tool("gitea_delete_branch").run({ owner: "novox", repo: "hq", branch: "feat/x" });
|
||||
assert.equal(forge.branchDeleted, true);
|
||||
});
|
||||
|
||||
+3
-14
@@ -34,21 +34,15 @@ 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.
|
||||
* 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.
|
||||
* Nothing under /admin, /orgs or write:user — the escape-hatch tool reaches only what these three cover.
|
||||
*/
|
||||
export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user", "write:admin"];
|
||||
export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user"];
|
||||
|
||||
/** 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`, or 403 for a scope it lacks. A fresh token, or a plain error when there is nothing to renew with. */
|
||||
/** The forge answered 401 to `rejected`. A fresh token, or a plain error when there is nothing to renew with. */
|
||||
renew(rejected: string): Promise<string>;
|
||||
}
|
||||
|
||||
@@ -176,11 +170,6 @@ 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) {
|
||||
|
||||
@@ -254,131 +254,6 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
|
||||
},
|
||||
},
|
||||
|
||||
{
|
||||
name: "gitea_close_pull_request",
|
||||
description: "Close a pull request without merging it — one whose work landed elsewhere, or was abandoned.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
number: { type: "number", description: "the PR number" },
|
||||
},
|
||||
run: async (args) => ({
|
||||
pull: await gitea.setPullState(String(args.owner), String(args.repo), Number(args.number), "closed"),
|
||||
}),
|
||||
},
|
||||
{
|
||||
name: "gitea_reopen_pull_request",
|
||||
description: "Reopen a closed, unmerged pull request.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
number: { type: "number", description: "the PR number" },
|
||||
},
|
||||
run: async (args) => ({
|
||||
pull: await gitea.setPullState(String(args.owner), String(args.repo), Number(args.number), "open"),
|
||||
}),
|
||||
},
|
||||
{
|
||||
name: "gitea_update_pull_request",
|
||||
description: "Change a pull request's title or body; a field not given is left as it is.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
number: { type: "number", description: "the PR number" },
|
||||
title: { type: "string", description: "the new title (optional)" },
|
||||
body: { type: "string", description: "the new body, markdown (optional)" },
|
||||
},
|
||||
run: async (args) => ({
|
||||
pull: await gitea.updatePullRequest(String(args.owner), String(args.repo), Number(args.number), {
|
||||
title: args.title === undefined ? undefined : String(args.title),
|
||||
body: args.body === undefined ? undefined : String(args.body),
|
||||
}),
|
||||
}),
|
||||
},
|
||||
{
|
||||
name: "gitea_pull_request_files",
|
||||
description: "The files a pull request changes, as paths from the repository's root (up to 100; says when there are more).",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
number: { type: "number", description: "the PR number" },
|
||||
},
|
||||
run: async (args) => gitea.listPullFiles(String(args.owner), String(args.repo), Number(args.number)),
|
||||
},
|
||||
{
|
||||
name: "gitea_pull_request_diff",
|
||||
description: "A pull request's unified diff, as text — for reviewing it without a checkout.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
number: { type: "number", description: "the PR number" },
|
||||
},
|
||||
run: async (args) => ({
|
||||
diff: await gitea.pullDiff(String(args.owner), String(args.repo), Number(args.number)),
|
||||
}),
|
||||
},
|
||||
{
|
||||
name: "gitea_list_comments",
|
||||
description: "Every comment on an issue or pull request, oldest first.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
number: { type: "number", description: "the issue or PR number" },
|
||||
},
|
||||
run: async (args) => ({
|
||||
comments: await gitea.listComments(String(args.owner), String(args.repo), Number(args.number)),
|
||||
}),
|
||||
},
|
||||
{
|
||||
name: "gitea_reopen_issue",
|
||||
description: "Reopen a closed issue.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
number: { type: "number", description: "the issue number" },
|
||||
},
|
||||
run: async (args) => ({
|
||||
issue: await gitea.setIssueState(String(args.owner), String(args.repo), Number(args.number), "open"),
|
||||
}),
|
||||
},
|
||||
|
||||
// ---- Contents and branches ----
|
||||
{
|
||||
name: "gitea_get_file",
|
||||
description: "One file's contents from a repository, decoded, at a branch, tag or commit (default the repository's default branch).",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
path: { type: "string", description: "the file's path from the repository's root" },
|
||||
ref: { type: "string", description: "branch, tag or commit (optional)" },
|
||||
},
|
||||
run: async (args) => ({
|
||||
file: await gitea.getFile(String(args.owner), String(args.repo), String(args.path), args.ref ? String(args.ref) : undefined),
|
||||
}),
|
||||
},
|
||||
{
|
||||
name: "gitea_list_branches",
|
||||
description: "Every branch of a repository with the commit it points at.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
},
|
||||
run: async (args) => ({ branches: await gitea.listBranches(String(args.owner), String(args.repo)) }),
|
||||
},
|
||||
{
|
||||
name: "gitea_delete_branch",
|
||||
description: "Delete a branch — a feature branch whose pull request was closed rather than merged. Refused by the forge for a protected branch.",
|
||||
input: {
|
||||
owner: { type: "string", description: "the repository owner" },
|
||||
repo: { type: "string", description: "the repository name" },
|
||||
branch: { type: "string", description: "the branch name" },
|
||||
},
|
||||
run: async (args) => {
|
||||
await gitea.deleteBranch(String(args.owner), String(args.repo), String(args.branch));
|
||||
return { deleted: true, branch: String(args.branch) };
|
||||
},
|
||||
},
|
||||
|
||||
// ---- Labels ----
|
||||
{
|
||||
name: "gitea_list_labels",
|
||||
|
||||
+10
-10
@@ -2,26 +2,26 @@
|
||||
"module": "gitlab",
|
||||
"version": "1",
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"token": "/var/lib/gitlab/token",
|
||||
"broker": "/var/lib/mesh/gitlab/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/gitlab",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/gitlab",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/config.json",
|
||||
"path": "/var/lib/gitlab/config.json",
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
@@ -32,9 +32,9 @@
|
||||
"name": "mesh-runtime-gitlab",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
"/var/lib/gitlab/config.json:/run/config/config.json:ro",
|
||||
"/var/lib/gitlab/token:/run/secrets/token:ro",
|
||||
"/var/lib/mesh/gitlab/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_GITLAB_TOKEN_FILE": "/run/secrets/token",
|
||||
|
||||
+22
-80
@@ -5,8 +5,8 @@
|
||||
"alert.firing"
|
||||
],
|
||||
"own-secrets": {
|
||||
"admin": "${dir:mesh-state}/admin",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"admin": "/var/lib/grafana-module/admin.secret",
|
||||
"broker": "/var/lib/mesh/grafana/broker"
|
||||
},
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
@@ -24,93 +24,51 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/grafana",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/grafana-module",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "data",
|
||||
"type": "directory",
|
||||
"path": "/services/grafana/data",
|
||||
"mode": "0700",
|
||||
"owner": "472:472"
|
||||
},
|
||||
{
|
||||
"id": "admin-secret",
|
||||
"id": "server-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/admin.secret",
|
||||
"mode": "0400",
|
||||
"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"
|
||||
"path": "/var/lib/grafana-module/server.env",
|
||||
"mode": "0600",
|
||||
"content": "GF_SECURITY_ADMIN_PASSWORD=${secret:admin}\n"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "grafana",
|
||||
"image": "grafana/grafana@sha256:ac461fb352abc50da10a51c7d02462e9c05488f11f53f14b3ad79a8145f638a0",
|
||||
"image": "grafana/grafana@sha256:f772d434e8fab0049deb2b1b30abd43342bcfca1537614aa8d36080232cf4283",
|
||||
"ports": [
|
||||
"3000"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:data}:/var/lib/grafana",
|
||||
"${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"
|
||||
"/services/grafana/data:/var/lib/grafana"
|
||||
],
|
||||
"env": {
|
||||
"GF_SECURITY_ADMIN_PASSWORD__FILE": "/run/secrets/admin"
|
||||
},
|
||||
"env-file": [
|
||||
"${dir:state}/oidc.env"
|
||||
"/var/lib/grafana-module/server.env"
|
||||
],
|
||||
"restart-on": [
|
||||
"oidc-env",
|
||||
"oidc-secret",
|
||||
"influxdb-datasource",
|
||||
"influxdb-secret"
|
||||
]
|
||||
"secrets-in-environment": "grafana honours GF_SECURITY_ADMIN_PASSWORD__FILE; convertible, awaiting a bed that exercises the admin password (assigned-grafana serves tools only)"
|
||||
},
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/grafana/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{\n \"user\": \"admin\",\n \"password\": \"${secret:admin}\"\n}\n",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
@@ -119,12 +77,12 @@
|
||||
"name": "mesh-grafana",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
"/var/lib/mesh/grafana/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/grafana/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
|
||||
"MESH_GRAFANA_URL": "http://127.0.0.1:3000",
|
||||
"MESH_GRAFANA_CONFIG_FILE": "/run/config/config.json"
|
||||
},
|
||||
"restart-on": [
|
||||
@@ -134,32 +92,16 @@
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
"route",
|
||||
"oidc-client",
|
||||
"influxdb-api"
|
||||
"route"
|
||||
],
|
||||
"contributes": {
|
||||
"route": {
|
||||
"label": "grafana",
|
||||
"endpoint": "web"
|
||||
},
|
||||
"oidc-client": {
|
||||
"label": "grafana",
|
||||
"endpoint": "web",
|
||||
"callback": "/login/generic_oauth"
|
||||
},
|
||||
"influxdb-api": {
|
||||
"access": "read"
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "${dir:state}/route.json",
|
||||
"oidc-client": "${dir:state}/oidc.json",
|
||||
"influxdb-api": "${dir:state}/influxdb.json"
|
||||
},
|
||||
"secrets": {
|
||||
"oidc-client": "${dir:mesh-state}/oidc-client",
|
||||
"influxdb-api": "${dir:mesh-state}/influxdb-api"
|
||||
"route": "/var/lib/mesh/grafana/route.json"
|
||||
},
|
||||
"build": {
|
||||
"on": [
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "${dir:state}/route.json"
|
||||
"route": "/var/lib/hello-web/route.json"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -30,13 +30,13 @@
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/hello-web",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "page",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/index.html",
|
||||
"path": "/var/lib/hello-web/index.html",
|
||||
"mode": "0644",
|
||||
"content": "hello from hello-web, routed by the mesh\n"
|
||||
},
|
||||
@@ -54,7 +54,7 @@
|
||||
"8080"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:state}/index.html:/www/index.html:ro"
|
||||
"/var/lib/hello-web/index.html:/www/index.html:ro"
|
||||
],
|
||||
"args": [
|
||||
"sh",
|
||||
|
||||
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/home-assistant
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts \
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
@@ -22,6 +22,3 @@ COPY --from=build /app/modules/home-assistant/dist /app/modules/home-assistant/d
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/home-assistant/dist/index.js,/app/modules/home-assistant/dist/tools/index.js
|
||||
# NOT dist/provisions/index.js: that is a step the host runs to completion, named by the
|
||||
# `provisions` container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run
|
||||
# inside the serving sidecar too, and exit it.
|
||||
|
||||
@@ -9,8 +9,8 @@
|
||||
"state.changed"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker",
|
||||
"token": "${dir:mesh-state}/token"
|
||||
"broker": "/var/lib/mesh/home-assistant/broker",
|
||||
"token": "/var/lib/mesh/home-assistant/token"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -18,63 +18,40 @@
|
||||
"port": 8123,
|
||||
"protocol": "tcp",
|
||||
"from": "mesh",
|
||||
"why": "the dashboard, the API and the companion apps"
|
||||
},
|
||||
{
|
||||
"name": "sonos-events",
|
||||
"port": 1400,
|
||||
"protocol": "tcp",
|
||||
"from": "mesh",
|
||||
"why": "the Sonos integration's event callback: speakers push their state changes here"
|
||||
},
|
||||
{
|
||||
"name": "webrtc",
|
||||
"port": 18555,
|
||||
"protocol": "tcp",
|
||||
"from": "mesh",
|
||||
"why": "the bundled go2rtc's WebRTC port, which camera streams to a browser use"
|
||||
"why": "the dashboard and the API"
|
||||
}
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/mesh/home-assistant",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "directory",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "written",
|
||||
"type": "directory",
|
||||
"mode": "0700"
|
||||
"path": "/services/home-assistant/config",
|
||||
"mode": "0700",
|
||||
"owner": "1000:1000"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "home-assistant",
|
||||
"image": "ghcr.io/home-assistant/home-assistant@sha256:d8922685169707fd91e8b9729902d975f06157d005e422874d201e0261dda196",
|
||||
"image": "ghcr.io/home-assistant/home-assistant@sha256:14931c6b13756317849f46da1d01b45937a1150db66c081cfe529d48215943fe",
|
||||
"network": "host",
|
||||
"env": {
|
||||
"TZ": "Etc/UTC"
|
||||
},
|
||||
"volumes": [
|
||||
"${dir:config}:/config"
|
||||
"/services/home-assistant/config:/config"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/home-assistant/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
@@ -85,92 +62,35 @@
|
||||
"name": "mesh-home-assistant",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
"/var/lib/mesh/home-assistant/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/home-assistant/token:/run/secrets/token:ro",
|
||||
"/var/lib/mesh/home-assistant/config.json:/run/config/config.json:ro",
|
||||
"/services/home-assistant/config:/var/lib/home-assistant/config:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
|
||||
"MESH_HOMEASSISTANT_URL": "http://127.0.0.1:8123",
|
||||
"MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json"
|
||||
"MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_HOMEASSISTANT_CONFIG_DIR": "/var/lib/home-assistant/config"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
},
|
||||
{
|
||||
"id": "provisions",
|
||||
"type": "container",
|
||||
"name": "mesh-home-assistant-provisions",
|
||||
"network": "host",
|
||||
"run-once": true,
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/token:/run/secrets/token:ro",
|
||||
"${dir:written}:/var/lib/home-assistant-provisions",
|
||||
"${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
|
||||
"${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
|
||||
"${dir:state}/sonarr-api.json:/run/provisions/sonarr-api.json:ro",
|
||||
"${dir:state}/sonarr-api.secret:/run/provisions/sonarr-api.secret:ro",
|
||||
"${dir:state}/radarr-api.json:/run/provisions/radarr-api.json:ro",
|
||||
"${dir:state}/radarr-api.secret:/run/provisions/radarr-api.secret:ro",
|
||||
"${dir:state}/lidarr-api.json:/run/provisions/lidarr-api.json:ro",
|
||||
"${dir:state}/lidarr-api.secret:/run/provisions/lidarr-api.secret:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
|
||||
"MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_PROVISIONS_DIR": "/run/provisions",
|
||||
"MESH_WRITTEN_DIR": "/var/lib/home-assistant-provisions"
|
||||
},
|
||||
"args": [
|
||||
"run",
|
||||
"/app/modules/home-assistant/dist/provisions/index.js"
|
||||
],
|
||||
"restart-on": [
|
||||
"bound-mqtt-topic",
|
||||
"secret-mqtt-topic",
|
||||
"bound-sonarr-api",
|
||||
"secret-sonarr-api",
|
||||
"bound-radarr-api",
|
||||
"secret-radarr-api",
|
||||
"bound-lidarr-api",
|
||||
"secret-lidarr-api"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
"lidarr-api",
|
||||
"mqtt-topic",
|
||||
"radarr-api",
|
||||
"route",
|
||||
"sonarr-api"
|
||||
"route"
|
||||
],
|
||||
"contributes": {
|
||||
"mqtt-topic": {
|
||||
"topics": [
|
||||
"#"
|
||||
]
|
||||
},
|
||||
"route": {
|
||||
"label": "home-assistant",
|
||||
"endpoint": "web"
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "${dir:state}/route.json",
|
||||
"mqtt-topic": "${dir:state}/mqtt-topic.json",
|
||||
"sonarr-api": "${dir:state}/sonarr-api.json",
|
||||
"radarr-api": "${dir:state}/radarr-api.json",
|
||||
"lidarr-api": "${dir:state}/lidarr-api.json"
|
||||
},
|
||||
"secrets": {
|
||||
"mqtt-topic": "${dir:state}/mqtt-topic.secret",
|
||||
"sonarr-api": "${dir:state}/sonarr-api.secret",
|
||||
"radarr-api": "${dir:state}/radarr-api.secret",
|
||||
"lidarr-api": "${dir:state}/lidarr-api.secret"
|
||||
"route": "/var/lib/mesh/home-assistant/route.json"
|
||||
},
|
||||
"build": {
|
||||
"on": [
|
||||
|
||||
@@ -1,14 +1,9 @@
|
||||
{
|
||||
"name": "@novox/module-home-assistant",
|
||||
"version": "0.1.0",
|
||||
"description": "home-assistant \u2014 home automation platform. Its API client, tools and events live here (novox/hq ADR 0039).",
|
||||
"description": "home-assistant — home automation platform. Its API client, tools and events live here (novox/hq ADR 0039).",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
|
||||
"typecheck": "tsc -p tsconfig.json",
|
||||
"test": "node --test --experimental-strip-types 'test/*.test.ts'"
|
||||
},
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.0"
|
||||
},
|
||||
|
||||
@@ -1,486 +0,0 @@
|
||||
// How home-assistant's provisions step brings Home Assistant's integrations in line with what the
|
||||
// mesh bound: the MQTT integration to `mqtt-topic`, the Sonarr, Radarr and Lidarr integrations to
|
||||
// `sonarr-api`, `radarr-api` and `lidarr-api`. Pure logic over two seams — Home Assistant's config
|
||||
// flows (hass.ts) and the broker/apps — so it is tested against fakes (test/provisions.test.ts).
|
||||
//
|
||||
// The half that reads files and talks HTTP lives beside it (mesh.ts, hass.ts, probe.ts, index.ts).
|
||||
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import type { Hass, SchemaField } from "./hass.js";
|
||||
import type { Probe } from "./probe.js";
|
||||
|
||||
/** What the mesh wrote at `binds.<provision>` (the controller's binding document). */
|
||||
export interface Binding {
|
||||
provision?: string;
|
||||
from?: string;
|
||||
at?: string;
|
||||
as?: string;
|
||||
serves?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** How one provision came out. Never carries a credential. */
|
||||
export type Outcome =
|
||||
| { what: string; result: "unchanged"; note?: string }
|
||||
| { what: string; result: "written"; fields: string[]; note?: string }
|
||||
| { what: string; result: "equivalent"; note: string }
|
||||
| { what: string; result: "refused"; problem: string };
|
||||
|
||||
/** A port the binding serves, or undefined when it names none usable. */
|
||||
export function portOf(serves: Record<string, unknown> | undefined): number | undefined {
|
||||
const port = Number(serves?.port);
|
||||
return Number.isInteger(port) && port > 0 && port <= 65535 ? port : undefined;
|
||||
}
|
||||
|
||||
/** A host as it goes into a URL: an IPv6 literal bracketed. */
|
||||
export function urlHost(host: string): string {
|
||||
return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
|
||||
}
|
||||
|
||||
/**
|
||||
* What this step last wrote, per target, as a digest: the only way to know "already as the mesh
|
||||
* says" for a credential Home Assistant will not show back. A sha256 over the target and the values,
|
||||
* never the values; kept in the module's own placed directory.
|
||||
*/
|
||||
export interface Marks {
|
||||
get(name: string): Promise<string | undefined>;
|
||||
set(name: string, digest: string): Promise<void>;
|
||||
}
|
||||
|
||||
export function digest(...parts: (string | number)[]): string {
|
||||
return createHash("sha256").update(parts.map(String).join("\u0000")).digest("hex");
|
||||
}
|
||||
|
||||
/** An error as text with the credential taken out, raw and URL-encoded. */
|
||||
export function scrub(err: unknown, ...secrets: (string | undefined)[]): string {
|
||||
let text = err instanceof Error ? err.message : String(err);
|
||||
for (const s of secrets) {
|
||||
if (!s) continue;
|
||||
for (const form of new Set([s, encodeURIComponent(s)])) text = text.split(form).join("***");
|
||||
}
|
||||
return text;
|
||||
}
|
||||
|
||||
/**
|
||||
* What a form would submit if a person pressed "submit" without touching it: each field's
|
||||
* suggested value (what Home Assistant pre-fills from the entry), else its default; a section's
|
||||
* fields nested under its name. The step lays only the connection fields over this, so every other
|
||||
* choice the entry carries is sent back exactly as Home Assistant showed it.
|
||||
*/
|
||||
export function formValues(schema: readonly SchemaField[] | null | undefined): Record<string, unknown> {
|
||||
const out: Record<string, unknown> = {};
|
||||
for (const field of schema ?? []) {
|
||||
if (Array.isArray(field.schema)) {
|
||||
out[field.name] = formValues(field.schema);
|
||||
continue;
|
||||
}
|
||||
const suggested = field.description?.suggested_value;
|
||||
if (suggested !== undefined && suggested !== null) out[field.name] = suggested;
|
||||
else if (field.default !== undefined) out[field.name] = field.default;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/** Whether a form has a field of this name at its top level. */
|
||||
export function hasField(schema: readonly SchemaField[] | null | undefined, name: string): boolean {
|
||||
return (schema ?? []).some((f) => f.name === name);
|
||||
}
|
||||
|
||||
// ---- MQTT ----
|
||||
|
||||
// Home Assistant's MQTT integration, pointed at the broker the mesh bound — `mqtt-topic`.
|
||||
//
|
||||
// **Why a step.** Home Assistant keeps its broker, login and password in its MQTT config entry
|
||||
// (`.storage/core.config_entries`), not in a file the mesh could fill with `${bound:mqtt-topic:at}`.
|
||||
// So this reads the binding and the pair credential and makes the entry say the same thing, through
|
||||
// the MQTT integration's own reconfigure flow — the flow its "Reconfigure" button runs, which tests
|
||||
// the connection itself and saves nothing it could not connect with.
|
||||
//
|
||||
// **Only the connection, and only when it differs.** Broker, port, username, password. The protocol
|
||||
// version, client id, keepalive, TLS choices and discovery options the entry holds are sent back
|
||||
// exactly as Home Assistant pre-filled them. Whether the password already matches cannot be read
|
||||
// back (Home Assistant never shows a stored password), so the step keeps a digest of what it last
|
||||
// wrote: equal broker/port/username and an equal digest is "already as the mesh says".
|
||||
//
|
||||
// **Nothing loses its connection without someone seeing it.** Before Home Assistant is touched the
|
||||
// broker itself is asked whether it takes the delivered login (the provisioner creates it within
|
||||
// seconds of the grant): if not, nothing is written and the step fails saying why, and Home
|
||||
// Assistant keeps the login it has — the carried `luffy` on ace, which mosquitto keeps. If Home
|
||||
// Assistant's own connection test refuses the new settings, the flow saves nothing, and the step
|
||||
// fails with Home Assistant's reason. A login that may not subscribe to the discovery topics is said
|
||||
// as a warning: discovery would find nothing.
|
||||
|
||||
export const MQTT_PROVISION = "mqtt-topic";
|
||||
/** Home Assistant's discovery prefix, subscribed to whenever discovery is on (the default). */
|
||||
export const DISCOVERY_FILTER = "homeassistant/#";
|
||||
|
||||
export interface MqttWanted {
|
||||
host: string;
|
||||
port: number;
|
||||
username: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
export type Wanted = { ok: true; want: MqttWanted } | { ok: false; problem: string };
|
||||
|
||||
/** The broker, port and login the mesh says Home Assistant uses. */
|
||||
export function wantedMqtt(binding: Binding | undefined, credential: string | undefined): Wanted {
|
||||
if (!binding) return { ok: false, problem: `no binding for ${MQTT_PROVISION} was delivered — the mesh writes it before this step runs` };
|
||||
const host = typeof binding.at === "string" ? binding.at.trim() : "";
|
||||
if (!host) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no host (at)` };
|
||||
const port = portOf(binding.serves);
|
||||
if (port === undefined) return { ok: false, problem: `the ${MQTT_PROVISION} binding serves no usable port (${String(binding.serves?.port)})` };
|
||||
const scheme = binding.serves?.scheme;
|
||||
if (scheme !== undefined && scheme !== "mqtt") {
|
||||
return { ok: false, problem: `the ${MQTT_PROVISION} binding serves scheme ${String(scheme)}; this step writes plain MQTT` };
|
||||
}
|
||||
const username = typeof binding.as === "string" ? binding.as.trim() : "";
|
||||
if (!username) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no login (as)` };
|
||||
const password = (credential ?? "").replace(/\n$/, "");
|
||||
if (!password) return { ok: false, problem: `the ${MQTT_PROVISION} credential is empty or was not delivered` };
|
||||
return { ok: true, want: { host, port, username, password } };
|
||||
}
|
||||
|
||||
export interface MqttDeps {
|
||||
hass: Hass;
|
||||
probe: Probe;
|
||||
marks: Marks;
|
||||
}
|
||||
|
||||
const markFor = (entryId: string, w: MqttWanted): string => digest("mqtt", entryId, w.host, w.port, w.username, w.password);
|
||||
|
||||
/** Bring Home Assistant's MQTT entry in line with the mesh. Never throws: every failure is an outcome. */
|
||||
export async function reconcileMqtt(deps: MqttDeps, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
|
||||
const what = "mqtt";
|
||||
const w = wantedMqtt(binding, credential);
|
||||
if ("problem" in w) return { what, result: "refused", problem: w.problem };
|
||||
const want = w.want;
|
||||
|
||||
// The broker first: a login it does not take is never written into Home Assistant.
|
||||
let note: string | undefined;
|
||||
try {
|
||||
const probe = await deps.probe(want.host, want.port, want.username, want.password, DISCOVERY_FILTER);
|
||||
if (probe.connack === 4 || probe.connack === 5) {
|
||||
return {
|
||||
what,
|
||||
result: "refused",
|
||||
problem:
|
||||
`the broker at ${want.host}:${want.port} does not (yet) take the login ${want.username} with the delivered ` +
|
||||
`password (CONNACK ${probe.connack}); mosquitto's provisioner creates it from the grant — nothing was ` +
|
||||
`written, and Home Assistant keeps the broker login it has`,
|
||||
};
|
||||
}
|
||||
if (probe.connack !== 0) {
|
||||
return { what, result: "refused", problem: `the broker at ${want.host}:${want.port} answered CONNACK ${probe.connack}; nothing was written` };
|
||||
}
|
||||
if (probe.suback === 0x80) {
|
||||
note =
|
||||
`warning: ${want.username} may not subscribe to ${DISCOVERY_FILTER} — MQTT discovery will find nothing; ` +
|
||||
`grant it with the mqtt-topic contribution's \`topics\``;
|
||||
}
|
||||
} catch (err) {
|
||||
return {
|
||||
what,
|
||||
result: "refused",
|
||||
problem: `the broker at ${want.host}:${want.port} could not be asked: ${scrub(err, want.password)}; nothing was written`,
|
||||
};
|
||||
}
|
||||
|
||||
try {
|
||||
const entries = (await deps.hass.entries("mqtt")).filter((e) => e.domain === "mqtt");
|
||||
if (entries.length > 1) {
|
||||
return { what, result: "refused", problem: `Home Assistant has ${entries.length} MQTT entries; which one the mesh owns is not guessed` };
|
||||
}
|
||||
if (entries.length === 0) return await createEntry(deps, want, note);
|
||||
|
||||
const entry = entries[0];
|
||||
const flow = await deps.hass.startFlow("mqtt", entry.entry_id);
|
||||
if (flow.type !== "form" || !flow.flow_id || !flow.data_schema) {
|
||||
if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
|
||||
return { what, result: "refused", problem: `Home Assistant's MQTT reconfigure flow answered ${flow.type}${flow.reason ? ` (${flow.reason})` : ""}` };
|
||||
}
|
||||
const current = formValues(flow.data_schema);
|
||||
const fields: string[] = [];
|
||||
if (String(current.broker ?? "") !== want.host) fields.push("broker");
|
||||
if (Number(current.port ?? 0) !== want.port) fields.push("port");
|
||||
if (String(current.username ?? "") !== want.username) fields.push("username");
|
||||
if ((await deps.marks.get("mqtt")) !== markFor(entry.entry_id, want)) fields.push("password");
|
||||
if (fields.length === 0) {
|
||||
await deps.hass.abortFlow(flow.flow_id);
|
||||
return note ? { what, result: "unchanged", note } : { what, result: "unchanged" };
|
||||
}
|
||||
|
||||
const saved = await deps.hass.stepFlow(flow.flow_id, {
|
||||
...current,
|
||||
broker: want.host,
|
||||
port: want.port,
|
||||
username: want.username,
|
||||
password: want.password,
|
||||
});
|
||||
if (saved.type === "abort" && saved.reason === "reconfigure_successful") {
|
||||
await deps.marks.set("mqtt", markFor(entry.entry_id, want));
|
||||
return { what, result: "written", fields, ...(note ? { note } : {}) };
|
||||
}
|
||||
if (saved.flow_id) await deps.hass.abortFlow(saved.flow_id);
|
||||
return {
|
||||
what,
|
||||
result: "refused",
|
||||
problem:
|
||||
`Home Assistant's own connection test refused ${want.username}@${want.host}:${want.port} ` +
|
||||
`(${describe(saved)}); its MQTT entry is unchanged`,
|
||||
};
|
||||
} catch (err) {
|
||||
return { what, result: "refused", problem: scrub(err, want.password) };
|
||||
}
|
||||
}
|
||||
|
||||
/** A fresh Home Assistant has no MQTT entry: made through the integration's user flow. */
|
||||
async function createEntry(deps: MqttDeps, want: MqttWanted, note?: string): Promise<Outcome> {
|
||||
const what = "mqtt";
|
||||
let flow = await deps.hass.startFlow("mqtt");
|
||||
if (flow.type === "form" && flow.step_id !== "broker" && flow.flow_id) {
|
||||
// Anything before the broker form (none outside the Supervisor) is not this step's to answer.
|
||||
await deps.hass.abortFlow(flow.flow_id);
|
||||
return { what, result: "refused", problem: `Home Assistant's MQTT user flow asked ${flow.step_id} before the broker` };
|
||||
}
|
||||
if (flow.type !== "form" || !flow.flow_id) {
|
||||
return { what, result: "refused", problem: `Home Assistant's MQTT user flow answered ${describe(flow)}` };
|
||||
}
|
||||
const shown = formValues(flow.data_schema);
|
||||
// A new entry's form has no value for its two certificate choices (a reconfigure pre-fills them
|
||||
// from the entry): plain MQTT, so neither a CA nor a client certificate.
|
||||
const other = (shown.other_settings ?? {}) as Record<string, unknown>;
|
||||
if (flow.data_schema?.some((f) => f.name === "other_settings")) {
|
||||
shown.other_settings = { set_ca_cert: "off", set_client_cert: false, ...other };
|
||||
}
|
||||
flow = await deps.hass.stepFlow(flow.flow_id, {
|
||||
...shown,
|
||||
broker: want.host,
|
||||
port: want.port,
|
||||
username: want.username,
|
||||
password: want.password,
|
||||
});
|
||||
if (flow.type === "create_entry") {
|
||||
const id = (flow.result as { entry_id?: string } | undefined)?.entry_id;
|
||||
if (id) await deps.marks.set("mqtt", markFor(id, want));
|
||||
return { what, result: "written", fields: ["entry"], ...(note ? { note } : {}) };
|
||||
}
|
||||
if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
|
||||
return { what, result: "refused", problem: `Home Assistant refused a new MQTT entry for ${want.host}:${want.port} (${describe(flow)})` };
|
||||
}
|
||||
|
||||
export function describe(r: { type: string; reason?: string; errors?: Record<string, string> | null }): string {
|
||||
const errors = r.errors ? Object.entries(r.errors).map(([k, v]) => `${k}: ${v}`).join(", ") : "";
|
||||
return [r.type, r.reason, errors].filter(Boolean).join(" — ");
|
||||
}
|
||||
|
||||
// ---- Sonarr, Radarr, Lidarr ----
|
||||
|
||||
// Home Assistant's Sonarr, Radarr and Lidarr integrations, pointed at the apps the mesh bound —
|
||||
// `sonarr-api`, `radarr-api`, `lidarr-api` (their providers: mesh-catalog #156).
|
||||
//
|
||||
// **What Home Assistant lets anyone change, and what it does not.** Each integration keeps a URL and
|
||||
// an API key in its config entry. None of the three has a reconfigure flow: Home Assistant changes
|
||||
// them only through the flow its UI runs —
|
||||
// - a **user flow** makes a new entry (validated against the app);
|
||||
// - a **reauth flow**, which Home Assistant starts by itself when the app refuses the key it holds,
|
||||
// takes a new key (Sonarr) or a new URL and key (Radarr, Lidarr);
|
||||
// - anything else — the URL of a working entry — only by removing the integration and adding it
|
||||
// again, which throws away its entities' names, areas and history links. **This step never
|
||||
// removes an entry.**
|
||||
// So, per app:
|
||||
// 1. The bound key is tried against the bound app first. Refused, nothing is written: until the
|
||||
// operator accepts the app's own key for this pair, the mesh delivers a value it minted, which
|
||||
// no Servarr app takes (novox/hq ADR 0092) — the failure names the `secret accept` that fixes it.
|
||||
// 2. No entry: one is made through the user flow.
|
||||
// 3. A reauth flow Home Assistant started for the entry: finished with the bound key (and URL,
|
||||
// where the integration's reauth asks for one).
|
||||
// 4. An entry whose URL (read from the device the integration registered, `configuration_url`)
|
||||
// is the bound one and which is loaded: already as the mesh says. The key needs no digest here:
|
||||
// a Servarr app has one key, so an entry loaded against the app holds the key the app took.
|
||||
// 5. A working entry at a different URL that reaches **the same app** — the same process, by the
|
||||
// app's own status (start time, data folder, version) — is left as it is and said: ace's entries
|
||||
// say `127.0.0.1:<port>` and the binding says `ace.internal:<port>`, one Sonarr either way.
|
||||
// 6. Anything else is refused, loudly, with what the operator can do; nothing is removed.
|
||||
|
||||
|
||||
export interface ServarrApp {
|
||||
/** The integration's domain, also the app. */
|
||||
domain: "sonarr" | "radarr" | "lidarr";
|
||||
/** The provision it is required as: the `requires`, `binds` and `secrets` key. */
|
||||
provision: string;
|
||||
/** The app's status endpoint: answers 401 to a wrong key, and says which process answered. */
|
||||
statusPath: string;
|
||||
}
|
||||
|
||||
export const APPS: readonly ServarrApp[] = [
|
||||
{ domain: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
|
||||
{ domain: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status" },
|
||||
{ domain: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
|
||||
];
|
||||
|
||||
/** The HTTP the step needs toward the apps, so a test can stand fakes in. */
|
||||
export interface Http {
|
||||
fetch(url: string, init?: { method?: string; headers?: Record<string, string> }): Promise<{ status: number; text(): Promise<string> }>;
|
||||
}
|
||||
|
||||
export type AppWanted = { ok: true; url: string; key: string; from: string } | { ok: false; problem: string };
|
||||
|
||||
/** The URL and key the mesh says Home Assistant uses for this app. */
|
||||
export function wantedApp(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): AppWanted {
|
||||
if (!binding) return { ok: false, problem: `no binding for ${spec.provision} was delivered — the mesh writes it before this step runs` };
|
||||
const at = typeof binding.at === "string" ? binding.at.trim() : "";
|
||||
if (!at) return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
|
||||
const port = portOf(binding.serves);
|
||||
if (port === undefined) return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(binding.serves?.port)})` };
|
||||
const scheme = typeof binding.serves?.scheme === "string" && binding.serves.scheme ? binding.serves.scheme : "http";
|
||||
if (scheme !== "http" && scheme !== "https") return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}` };
|
||||
const base = typeof binding.serves?.["url-base"] === "string" ? String(binding.serves["url-base"]).trim().replace(/^\/+|\/+$/g, "") : "";
|
||||
const key = (credential ?? "").trim();
|
||||
if (!key) return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
|
||||
return {
|
||||
ok: true,
|
||||
url: `${scheme}://${urlHost(at)}:${port}${base ? `/${base}` : ""}`,
|
||||
key,
|
||||
from: typeof binding.from === "string" ? binding.from : "",
|
||||
};
|
||||
}
|
||||
|
||||
/** Two URLs naming the same place: scheme, host, port (explicit or default) and base path. */
|
||||
export function sameUrl(a: string | null | undefined, b: string): boolean {
|
||||
if (!a) return false;
|
||||
try {
|
||||
const x = new URL(a);
|
||||
const y = new URL(b);
|
||||
const port = (u: URL) => u.port || (u.protocol === "https:" ? "443" : "80");
|
||||
const path = (u: URL) => u.pathname.replace(/\/+$/, "");
|
||||
return x.protocol === y.protocol && x.hostname.toLowerCase() === y.hostname.toLowerCase() && port(x) === port(y) && path(x) === path(y);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
type Status = { taken: true; status: Record<string, unknown> } | { taken: false };
|
||||
|
||||
/** The app's status with this key: `taken: false` when it refuses the key; throws when it cannot be asked. */
|
||||
export async function appStatus(http: Http, spec: ServarrApp, url: string, key: string): Promise<Status> {
|
||||
const res = await http.fetch(`${url.replace(/\/+$/, "")}${spec.statusPath}`, {
|
||||
method: "GET",
|
||||
headers: { "X-Api-Key": key, Accept: "application/json" },
|
||||
});
|
||||
if (res.status === 401 || res.status === 403) return { taken: false };
|
||||
if (res.status < 200 || res.status >= 300) throw new Error(`${spec.domain} answered ${res.status} at ${spec.statusPath}`);
|
||||
return { taken: true, status: JSON.parse(await res.text()) as Record<string, unknown> };
|
||||
}
|
||||
|
||||
/** Whether two status answers came from one running app. */
|
||||
export function sameInstance(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
|
||||
const facts = ["startTime", "appData", "version"];
|
||||
return facts.every((k) => a[k] !== undefined && a[k] !== null && a[k] === b[k]);
|
||||
}
|
||||
|
||||
/** The remedy for a refused key, in the controller's words (ADR 0092). */
|
||||
export function acceptRemedy(spec: ServarrApp, from: string): string {
|
||||
return (
|
||||
`${spec.domain} refuses the ${spec.provision} credential the mesh delivered, so nothing was written into ` +
|
||||
`Home Assistant. A Servarr app has one API key and the mesh cannot make it: accept ${spec.domain}'s own key ` +
|
||||
`for this pair — \`secret accept <this node> home-assistant ${spec.provision} --provider ${from || "<its node>"} ` +
|
||||
`--from <file holding ${spec.domain}'s ApiKey>\``
|
||||
);
|
||||
}
|
||||
|
||||
export interface ServarrDeps {
|
||||
hass: Hass;
|
||||
http: Http;
|
||||
}
|
||||
|
||||
/** The input a Servarr form takes: what it shows, with the URL (where asked) and the key laid over. */
|
||||
function servarrInput(schema: readonly SchemaField[] | null | undefined, url: string, key: string): Record<string, unknown> {
|
||||
const input = formValues(schema);
|
||||
if (hasField(schema, "url")) input.url = url;
|
||||
if (hasField(schema, "api_key")) input.api_key = key;
|
||||
return input;
|
||||
}
|
||||
|
||||
/** Bring Home Assistant's entry for one app in line with the mesh. Never throws. */
|
||||
export async function reconcileApp(deps: ServarrDeps, spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
|
||||
const what = spec.domain;
|
||||
const w = wantedApp(spec, binding, credential);
|
||||
if ("problem" in w) return { what, result: "refused", problem: w.problem };
|
||||
|
||||
let bound: Status;
|
||||
try {
|
||||
bound = await appStatus(deps.http, spec, w.url, w.key);
|
||||
} catch (err) {
|
||||
return { what, result: "refused", problem: `${spec.domain} could not be asked at ${w.url}: ${scrub(err, w.key)}` };
|
||||
}
|
||||
if (!bound.taken) return { what, result: "refused", problem: acceptRemedy(spec, w.from) };
|
||||
|
||||
try {
|
||||
const entries = (await deps.hass.entries(spec.domain)).filter((e) => e.domain === spec.domain);
|
||||
if (entries.length > 1) {
|
||||
return { what, result: "refused", problem: `Home Assistant has ${entries.length} ${spec.domain} entries; which one the mesh owns is not guessed` };
|
||||
}
|
||||
|
||||
// No entry: made, through the integration's own user flow, which validates the key itself.
|
||||
if (entries.length === 0) {
|
||||
const flow = await deps.hass.startFlow(spec.domain);
|
||||
if (flow.type !== "form" || !flow.flow_id) return { what, result: "refused", problem: `Home Assistant's ${spec.domain} user flow answered ${describe(flow)}` };
|
||||
const made = await deps.hass.stepFlow(flow.flow_id, servarrInput(flow.data_schema, w.url, w.key));
|
||||
if (made.type === "create_entry") return { what, result: "written", fields: ["entry"] };
|
||||
if (made.flow_id) await deps.hass.abortFlow(made.flow_id);
|
||||
return { what, result: "refused", problem: `Home Assistant refused a new ${spec.domain} entry at ${w.url} (${describe(made)})` };
|
||||
}
|
||||
|
||||
const entry = entries[0];
|
||||
if (entry.disabled_by) return { what, result: "unchanged", note: `the ${spec.domain} entry is disabled (by ${entry.disabled_by}); left alone` };
|
||||
|
||||
// A reauth Home Assistant started because the app refused its key: finished with the bound one.
|
||||
const reauth = (await deps.hass.flowsInProgress()).find(
|
||||
(f) => f.handler === spec.domain && f.context?.source === "reauth" && f.context?.entry_id === entry.entry_id,
|
||||
);
|
||||
if (reauth) {
|
||||
let step = await deps.hass.stepFlow(reauth.flow_id, {}); // reauth_confirm: a confirmation, no fields
|
||||
if (step.type === "form" && step.flow_id && step.step_id !== "reauth_confirm") {
|
||||
const input = servarrInput(step.data_schema, w.url, w.key);
|
||||
const fields = ["api_key", ...(hasField(step.data_schema, "url") ? ["url"] : [])];
|
||||
step = await deps.hass.stepFlow(step.flow_id, input);
|
||||
if (step.type === "abort" && step.reason === "reauth_successful") return { what, result: "written", fields };
|
||||
}
|
||||
return { what, result: "refused", problem: `Home Assistant's ${spec.domain} reauth did not take the bound key and URL (${describe(step)})` };
|
||||
}
|
||||
|
||||
const device = (await deps.hass.devices()).find((d) => d.config_entries?.includes(entry.entry_id) && d.configuration_url);
|
||||
const current = device?.configuration_url ?? undefined;
|
||||
if (entry.state === "loaded" && sameUrl(current, w.url)) return { what, result: "unchanged" };
|
||||
|
||||
if (entry.state === "loaded" && current) {
|
||||
let there: Status | undefined;
|
||||
try {
|
||||
there = await appStatus(deps.http, spec, current, w.key);
|
||||
} catch {
|
||||
there = undefined;
|
||||
}
|
||||
if (there?.taken && sameInstance(there.status, bound.status)) {
|
||||
return {
|
||||
what,
|
||||
result: "equivalent",
|
||||
note:
|
||||
`Home Assistant reaches ${spec.domain} at ${current}, the same running app the mesh bound at ${w.url}; ` +
|
||||
`Home Assistant has no way to change a working ${spec.domain} entry's URL short of removing it, so it is left as it is`,
|
||||
};
|
||||
}
|
||||
}
|
||||
return {
|
||||
what,
|
||||
result: "refused",
|
||||
problem:
|
||||
`Home Assistant's ${spec.domain} entry (${entry.state ?? "unknown state"}) points at ${current ?? "an unknown URL"}, ` +
|
||||
`not the ${spec.domain} the mesh bound at ${w.url}. Home Assistant only lets a working entry's URL change by ` +
|
||||
`removing and re-adding the integration, which this step never does: remove it in Home Assistant ` +
|
||||
`(Settings → Devices & services → ${spec.domain}) and the next run adds it at the bound URL`,
|
||||
};
|
||||
} catch (err) {
|
||||
return { what, result: "refused", problem: scrub(err, w.key) };
|
||||
}
|
||||
}
|
||||
@@ -1,160 +0,0 @@
|
||||
// Home Assistant's own configuration API, as the provisions step uses it — the supported way to
|
||||
// change an integration's connection. Home Assistant keeps every integration in
|
||||
// `.storage/core.config_entries`, a file it owns and rewrites; the mesh may not write it, and it is
|
||||
// not a file the mesh could merge into. What Home Assistant offers instead is the same thing its UI
|
||||
// uses: **config flows** over REST (`/api/config/config_entries/flow`) — a user flow creates an
|
||||
// entry, a reconfigure flow changes one, a reauth flow (which Home Assistant starts itself when a
|
||||
// credential stops working) replaces its credential — each validated by the integration's own
|
||||
// connection test before anything is saved. The two things REST does not answer (which flows Home
|
||||
// Assistant has started, which device an entry made) come over its WebSocket API.
|
||||
//
|
||||
// Nothing here reads `.storage`. Authenticated with the module's accepted long-lived access token.
|
||||
|
||||
/** A config entry as `GET /api/config/config_entries/entry` lists it — no data, no credentials. */
|
||||
export interface ConfigEntry {
|
||||
entry_id: string;
|
||||
domain: string;
|
||||
title?: string;
|
||||
source?: string;
|
||||
state?: string;
|
||||
disabled_by?: string | null;
|
||||
}
|
||||
|
||||
/** One field of a flow's form, as Home Assistant serializes a voluptuous schema. */
|
||||
export interface SchemaField {
|
||||
name: string;
|
||||
type?: string;
|
||||
required?: boolean;
|
||||
optional?: boolean;
|
||||
default?: unknown;
|
||||
description?: { suggested_value?: unknown } | null;
|
||||
/** A section (`type: "expandable"`) carries its own fields. */
|
||||
schema?: SchemaField[];
|
||||
}
|
||||
|
||||
/** What a flow answered: another form, an entry made, or the flow ended (abort). */
|
||||
export interface FlowResult {
|
||||
type: string;
|
||||
flow_id?: string;
|
||||
handler?: string;
|
||||
step_id?: string;
|
||||
data_schema?: SchemaField[] | null;
|
||||
errors?: Record<string, string> | null;
|
||||
reason?: string;
|
||||
result?: { entry_id?: string } | unknown;
|
||||
}
|
||||
|
||||
/** A flow in progress that Home Assistant started itself (a reauth, a discovery). */
|
||||
export interface FlowProgress {
|
||||
flow_id: string;
|
||||
handler: string;
|
||||
step_id?: string;
|
||||
context?: { source?: string; entry_id?: string };
|
||||
}
|
||||
|
||||
/** A device from the device registry; an integration names where its app is as configuration_url. */
|
||||
export interface DeviceEntry {
|
||||
id: string;
|
||||
config_entries?: string[];
|
||||
configuration_url?: string | null;
|
||||
}
|
||||
|
||||
export interface Hass {
|
||||
entries(domain: string): Promise<ConfigEntry[]>;
|
||||
/** A user flow for `handler`, or — given an entry — a reconfigure flow for it. */
|
||||
startFlow(handler: string, entryId?: string): Promise<FlowResult>;
|
||||
stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult>;
|
||||
abortFlow(flowId: string): Promise<void>;
|
||||
flowsInProgress(): Promise<FlowProgress[]>;
|
||||
devices(): Promise<DeviceEntry[]>;
|
||||
}
|
||||
|
||||
/** Home Assistant over HTTP: REST for entries and flows, one short WebSocket session per question. */
|
||||
export class HassApi implements Hass {
|
||||
private readonly base: string;
|
||||
|
||||
constructor(url: string, private readonly token: string) {
|
||||
this.base = url.replace(/\/$/, "");
|
||||
}
|
||||
|
||||
private async rest(method: string, path: string, body?: unknown): Promise<unknown> {
|
||||
const res = await fetch(`${this.base}${path}`, {
|
||||
method,
|
||||
headers: {
|
||||
Authorization: `Bearer ${this.token}`,
|
||||
Accept: "application/json",
|
||||
...(body !== undefined ? { "Content-Type": "application/json" } : {}),
|
||||
},
|
||||
body: body !== undefined ? JSON.stringify(body) : undefined,
|
||||
});
|
||||
const text = await res.text();
|
||||
if (!res.ok) {
|
||||
// Home Assistant's error text names fields, never echoes their values.
|
||||
throw new Error(`Home Assistant ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
|
||||
}
|
||||
return text ? (JSON.parse(text) as unknown) : undefined;
|
||||
}
|
||||
|
||||
async entries(domain: string): Promise<ConfigEntry[]> {
|
||||
return ((await this.rest("GET", `/api/config/config_entries/entry?domain=${encodeURIComponent(domain)}`)) ??
|
||||
[]) as ConfigEntry[];
|
||||
}
|
||||
|
||||
async startFlow(handler: string, entryId?: string): Promise<FlowResult> {
|
||||
return (await this.rest("POST", "/api/config/config_entries/flow", {
|
||||
handler,
|
||||
show_advanced_options: true,
|
||||
...(entryId ? { entry_id: entryId } : {}),
|
||||
})) as FlowResult;
|
||||
}
|
||||
|
||||
async stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult> {
|
||||
return (await this.rest("POST", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`, input)) as FlowResult;
|
||||
}
|
||||
|
||||
async abortFlow(flowId: string): Promise<void> {
|
||||
await this.rest("DELETE", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`).catch(() => undefined);
|
||||
}
|
||||
|
||||
async flowsInProgress(): Promise<FlowProgress[]> {
|
||||
return (await this.ws("config_entries/flow/progress")) as FlowProgress[];
|
||||
}
|
||||
|
||||
async devices(): Promise<DeviceEntry[]> {
|
||||
return (await this.ws("config/device_registry/list")) as DeviceEntry[];
|
||||
}
|
||||
|
||||
/** One WebSocket command: connect, authenticate, ask, close. */
|
||||
private ws(type: string): Promise<unknown> {
|
||||
const url = `${this.base.replace(/^http/, "ws")}/api/websocket`;
|
||||
return new Promise((resolve, reject) => {
|
||||
const socket = new WebSocket(url);
|
||||
const timer = setTimeout(() => {
|
||||
socket.close();
|
||||
reject(new Error(`Home Assistant's WebSocket did not answer ${type} within 30s`));
|
||||
}, 30_000);
|
||||
const done = (fn: () => void): void => {
|
||||
clearTimeout(timer);
|
||||
socket.close();
|
||||
fn();
|
||||
};
|
||||
socket.onerror = () => done(() => reject(new Error(`Home Assistant's WebSocket at ${url} failed`)));
|
||||
socket.onmessage = (event: { data: unknown }) => {
|
||||
const msg = JSON.parse(String(event.data)) as {
|
||||
type: string;
|
||||
id?: number;
|
||||
success?: boolean;
|
||||
result?: unknown;
|
||||
error?: { message?: string };
|
||||
};
|
||||
if (msg.type === "auth_required") socket.send(JSON.stringify({ type: "auth", access_token: this.token }));
|
||||
else if (msg.type === "auth_invalid") done(() => reject(new Error("Home Assistant refused the token")));
|
||||
else if (msg.type === "auth_ok") socket.send(JSON.stringify({ id: 1, type }));
|
||||
else if (msg.type === "result" && msg.id === 1) {
|
||||
if (msg.success) done(() => resolve(msg.result));
|
||||
else done(() => reject(new Error(`Home Assistant ${type}: ${msg.error?.message ?? "failed"}`)));
|
||||
}
|
||||
};
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -1,84 +0,0 @@
|
||||
// home-assistant's provisions step — run once by the host after Home Assistant starts, and again
|
||||
// whenever a binding or pair credential it reads changes (the container's `restart-on`, novox/hq
|
||||
// ADR 0099). It points Home Assistant's MQTT integration at the `mqtt-topic` broker and its Sonarr,
|
||||
// Radarr and Lidarr integrations at the `sonarr-api`, `radarr-api` and `lidarr-api` apps, through
|
||||
// Home Assistant's own config flows (connections.ts). It connects to no mesh broker.
|
||||
//
|
||||
// Exits non-zero when anything could not be put right, so the node reports the step failed and the
|
||||
// host runs it again on the next apply. Declared last in the manifest, so its failing gates nothing
|
||||
// else of home-assistant's (novox/hq ADR 0136). Never prints a key or password.
|
||||
|
||||
import { join } from "node:path";
|
||||
|
||||
import { APPS, MQTT_PROVISION, reconcileApp, reconcileMqtt, type Outcome } from "./connections.js";
|
||||
import { HassApi } from "./hass.js";
|
||||
import { marksIn, readBinding, readIfThere } from "./mesh.js";
|
||||
import { probeBroker } from "./probe.js";
|
||||
|
||||
const dir = process.env.MESH_PROVISIONS_DIR ?? "/run/provisions";
|
||||
const url = process.env.MESH_HOMEASSISTANT_URL ?? "http://127.0.0.1:8123";
|
||||
const token = (await readIfThere(process.env.MESH_HOMEASSISTANT_TOKEN_FILE))?.trim() ?? "";
|
||||
const marks = marksIn(process.env.MESH_WRITTEN_DIR ?? "/var/lib/home-assistant-provisions");
|
||||
const waitSeconds = Number(process.env.MESH_HOMEASSISTANT_WAIT_SECONDS ?? "300");
|
||||
|
||||
if (!token) {
|
||||
console.error("[hass-provisions] no Home Assistant token — home-assistant's own `token` secret has not been accepted");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
/** Home Assistant answers /api/ with 200 once it is up and the token is good. */
|
||||
async function ready(): Promise<boolean> {
|
||||
const until = Date.now() + waitSeconds * 1000;
|
||||
for (;;) {
|
||||
try {
|
||||
const res = await fetch(`${url.replace(/\/$/, "")}/api/`, { headers: { Authorization: `Bearer ${token}` } });
|
||||
if (res.status === 200) return true;
|
||||
if (res.status === 401 || res.status === 403) {
|
||||
console.error("[hass-provisions] Home Assistant refuses the token — accept a long-lived access token it issued");
|
||||
return false;
|
||||
}
|
||||
} catch {
|
||||
// not listening yet
|
||||
}
|
||||
if (Date.now() >= until) return false;
|
||||
await new Promise((r) => setTimeout(r, 3000));
|
||||
}
|
||||
}
|
||||
|
||||
if (!(await ready())) {
|
||||
console.error(`[hass-provisions] Home Assistant did not answer at ${url} within ${waitSeconds}s`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const hass = new HassApi(url, token);
|
||||
const read = async (p: string) => [await readBinding(join(dir, `${p}.json`)), await readIfThere(join(dir, `${p}.secret`))] as const;
|
||||
|
||||
const outcomes: Outcome[] = [];
|
||||
{
|
||||
const [binding, secret] = await read(MQTT_PROVISION);
|
||||
outcomes.push(await reconcileMqtt({ hass, probe: probeBroker, marks }, binding, secret));
|
||||
}
|
||||
for (const spec of APPS) {
|
||||
const [binding, secret] = await read(spec.provision);
|
||||
outcomes.push(await reconcileApp({ hass, http: { fetch: (u, init) => fetch(u, init) } }, spec, binding, secret));
|
||||
}
|
||||
|
||||
let failed = 0;
|
||||
for (const o of outcomes) {
|
||||
switch (o.result) {
|
||||
case "unchanged":
|
||||
console.log(`[hass-provisions] ${o.what}: already as the mesh says${o.note ? ` — ${o.note}` : ""}`);
|
||||
break;
|
||||
case "written":
|
||||
console.log(`[hass-provisions] ${o.what}: wrote ${o.fields.join(", ")}; Home Assistant's own test passed${o.note ? ` — ${o.note}` : ""}`);
|
||||
break;
|
||||
case "equivalent":
|
||||
console.log(`[hass-provisions] ${o.what}: ${o.note}`);
|
||||
break;
|
||||
case "refused":
|
||||
failed++;
|
||||
console.error(`[hass-provisions] ${o.what}: ${o.problem}`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
process.exitCode = failed > 0 ? 1 : 0;
|
||||
@@ -1,42 +0,0 @@
|
||||
// What the mesh delivered to home-assistant's provisions step, and the step's own small memory.
|
||||
//
|
||||
// Per provision it requires, the mesh writes two files beside each other (the manifest's `binds` and
|
||||
// `secrets`): `<provision>.json`, the binding — where the provider is (`at`), what it serves (`port`,
|
||||
// `scheme`, …) and the login this module presents (`as`) — and `<provision>.secret`, the pair
|
||||
// credential. Nothing here guesses a host, a port or a key.
|
||||
|
||||
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import type { Binding, Marks } from "./connections.js";
|
||||
|
||||
/** A file the mesh wrote, or undefined when it is not there. */
|
||||
export async function readIfThere(path: string | undefined): Promise<string | undefined> {
|
||||
if (!path) return undefined;
|
||||
return readFile(path, "utf8").catch(() => undefined);
|
||||
}
|
||||
|
||||
/** A binding file parsed, or undefined when absent or not JSON. */
|
||||
export async function readBinding(path: string): Promise<Binding | undefined> {
|
||||
const raw = await readIfThere(path);
|
||||
if (raw === undefined) return undefined;
|
||||
try {
|
||||
return JSON.parse(raw) as Binding;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
export function marksIn(dir: string): Marks {
|
||||
return {
|
||||
async get(name) {
|
||||
return (await readIfThere(join(dir, `${name}.digest`)))?.trim() || undefined;
|
||||
},
|
||||
async set(name, value) {
|
||||
await mkdir(dir, { recursive: true, mode: 0o700 });
|
||||
const path = join(dir, `${name}.digest`);
|
||||
await writeFile(`${path}.tmp`, `${value}\n`, { mode: 0o600 });
|
||||
await rename(`${path}.tmp`, path);
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -1,117 +0,0 @@
|
||||
// Ask the broker, before Home Assistant is told anything, whether it takes the login and password
|
||||
// the mesh delivered — and whether that login may subscribe to Home Assistant's discovery topics.
|
||||
//
|
||||
// One MQTT 3.1.1 session: CONNECT (clean, a throwaway client id, so Home Assistant's own session is
|
||||
// never taken over), read the CONNACK, optionally SUBSCRIBE once and read the SUBACK, DISCONNECT.
|
||||
// No dependency: the handful of bytes MQTT needs for this are written here.
|
||||
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { connect } from "node:net";
|
||||
|
||||
export interface ProbeResult {
|
||||
/** 0 accepted; 4 bad username or password; 5 not authorised. */
|
||||
connack: number;
|
||||
/** The SUBACK return code for the filter asked about: 0–2 granted, 0x80 refused. */
|
||||
suback?: number;
|
||||
}
|
||||
|
||||
export type Probe = (host: string, port: number, username: string, password: string, subscribe?: string) => Promise<ProbeResult>;
|
||||
|
||||
function str(v: string): Buffer {
|
||||
const b = Buffer.from(v, "utf8");
|
||||
const len = Buffer.alloc(2);
|
||||
len.writeUInt16BE(b.length);
|
||||
return Buffer.concat([len, b]);
|
||||
}
|
||||
|
||||
function packet(type: number, body: Buffer): Buffer {
|
||||
let remaining = body.length;
|
||||
const lenBytes: number[] = [];
|
||||
do {
|
||||
let byte = remaining % 128;
|
||||
remaining = Math.floor(remaining / 128);
|
||||
if (remaining > 0) byte |= 0x80;
|
||||
lenBytes.push(byte);
|
||||
} while (remaining > 0);
|
||||
return Buffer.concat([Buffer.from([type, ...lenBytes]), body]);
|
||||
}
|
||||
|
||||
/** The first complete packet in `buf`: its type byte, its body, and how many bytes it took. */
|
||||
export function firstPacket(buf: Buffer): { type: number; body: Buffer; used: number } | undefined {
|
||||
if (buf.length < 2) return undefined;
|
||||
let length = 0;
|
||||
let multiplier = 1;
|
||||
let i = 1;
|
||||
for (;;) {
|
||||
if (i >= buf.length) return undefined;
|
||||
const byte = buf[i++];
|
||||
length += (byte & 0x7f) * multiplier;
|
||||
if ((byte & 0x80) === 0) break;
|
||||
multiplier *= 128;
|
||||
if (i > 4) throw new Error("malformed MQTT remaining length");
|
||||
}
|
||||
if (buf.length < i + length) return undefined;
|
||||
return { type: buf[0], body: buf.subarray(i, i + length), used: i + length };
|
||||
}
|
||||
|
||||
export const probeBroker: Probe = (host, port, username, password, subscribe) => {
|
||||
const connectBody = Buffer.concat([
|
||||
str("MQTT"),
|
||||
Buffer.from([4, 0xc2, 0, 10]), // level 4 (3.1.1); username + password + clean session; keepalive 10s
|
||||
str(`mesh-probe-${randomBytes(6).toString("hex")}`),
|
||||
str(username),
|
||||
str(password),
|
||||
]);
|
||||
return new Promise((resolve, reject) => {
|
||||
const socket = connect({ host, port });
|
||||
let buf = Buffer.alloc(0);
|
||||
const result: ProbeResult = { connack: -1 };
|
||||
const timer = setTimeout(() => {
|
||||
socket.destroy();
|
||||
reject(new Error(`no answer from the broker at ${host}:${port} within 10s`));
|
||||
}, 10_000);
|
||||
const finish = (): void => {
|
||||
clearTimeout(timer);
|
||||
if (result.connack === 0) socket.end(Buffer.from([0xe0, 0]));
|
||||
else socket.destroy();
|
||||
resolve(result);
|
||||
};
|
||||
socket.on("connect", () => socket.write(packet(0x10, connectBody)));
|
||||
socket.on("data", (chunk) => {
|
||||
buf = Buffer.concat([buf, chunk]);
|
||||
for (;;) {
|
||||
let p;
|
||||
try {
|
||||
p = firstPacket(buf);
|
||||
} catch (err) {
|
||||
clearTimeout(timer);
|
||||
socket.destroy();
|
||||
reject(err);
|
||||
return;
|
||||
}
|
||||
if (!p) return;
|
||||
buf = buf.subarray(p.used);
|
||||
const kind = p.type >> 4;
|
||||
if (kind === 2) {
|
||||
result.connack = p.body[1] ?? -1;
|
||||
if (result.connack !== 0 || !subscribe) return finish();
|
||||
// SUBSCRIBE, packet id 1, one filter at QoS 0.
|
||||
socket.write(packet(0x82, Buffer.concat([Buffer.from([0, 1]), str(subscribe), Buffer.from([0])])));
|
||||
} else if (kind === 9) {
|
||||
result.suback = p.body[2];
|
||||
return finish();
|
||||
}
|
||||
}
|
||||
});
|
||||
socket.on("error", (err) => {
|
||||
clearTimeout(timer);
|
||||
reject(err);
|
||||
});
|
||||
socket.on("close", () => {
|
||||
if (result.connack === -1) {
|
||||
clearTimeout(timer);
|
||||
reject(new Error(`the broker at ${host}:${port} closed the connection without answering`));
|
||||
}
|
||||
});
|
||||
});
|
||||
};
|
||||
@@ -1,293 +0,0 @@
|
||||
// What holds home-assistant's provisions step (provisions/*.ts): Home Assistant's MQTT entry is
|
||||
// made to use the broker, port and login the mesh bound — only after the broker takes that login,
|
||||
// through the reconfigure flow, keeping every other setting as Home Assistant pre-filled it, and not
|
||||
// again once it already says so; its Sonarr/Radarr/Lidarr entries are made, finished (reauth), left
|
||||
// alone when they already reach the bound app, and never removed; a key the app refuses (the mesh's
|
||||
// minted value before the operator accepts the app's) is never written.
|
||||
//
|
||||
// Home Assistant and the apps are fakes answering as the real ones do (flow shapes checked against
|
||||
// ghcr.io/home-assistant/home-assistant 2026.9.3, the build ace runs).
|
||||
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
|
||||
import type { ConfigEntry, DeviceEntry, FlowProgress, FlowResult, Hass, SchemaField } from "../provisions/hass.ts";
|
||||
|
||||
import type { Binding, Marks } from "../provisions/connections.ts";
|
||||
import { APPS, formValues, reconcileApp, reconcileMqtt, sameUrl, type Http, type ServarrApp } from "../provisions/connections.ts";
|
||||
import type { Probe } from "../provisions/probe.ts";
|
||||
|
||||
const PWD_NOT_CHANGED = "__**password_not_changed**__";
|
||||
const MINTED = "mesh-minted-password";
|
||||
|
||||
function mqttBinding(): Binding {
|
||||
return { provision: "mqtt-topic", from: "ace", at: "ace.internal", as: "mesh_ace_hass", serves: { scheme: "mqtt", port: 1883 } };
|
||||
}
|
||||
|
||||
/** The MQTT reconfigure form as Home Assistant serializes it, pre-filled from an entry. */
|
||||
function brokerForm(data: Record<string, unknown>): SchemaField[] {
|
||||
return [
|
||||
{ name: "broker", type: "string", required: true, description: { suggested_value: data.broker } },
|
||||
{ name: "port", type: "integer", required: true, default: 1883, description: { suggested_value: data.port } },
|
||||
{ name: "protocol", type: "select", required: true, default: "3.1.1", description: { suggested_value: data.protocol } },
|
||||
{ name: "username", type: "string", optional: true, description: { suggested_value: data.username } },
|
||||
{ name: "password", type: "string", optional: true, description: { suggested_value: data.password ? PWD_NOT_CHANGED : undefined } },
|
||||
{
|
||||
name: "other_settings",
|
||||
type: "expandable",
|
||||
required: true,
|
||||
schema: [
|
||||
{ name: "keepalive", type: "integer", optional: true, description: { suggested_value: 60 } },
|
||||
{ name: "transport", type: "select", required: true, default: "tcp", description: { suggested_value: "tcp" } },
|
||||
{ name: "set_ca_cert", type: "select", required: true, description: { suggested_value: "off" } },
|
||||
{ name: "set_client_cert", type: "boolean", required: true, description: { suggested_value: false } },
|
||||
],
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
interface FakeOpts {
|
||||
entries?: Record<string, (ConfigEntry & { data: Record<string, unknown> })[]>;
|
||||
/** What Home Assistant's own connection test accepts. */
|
||||
accepts?: (data: Record<string, unknown>) => boolean;
|
||||
reauth?: FlowProgress[];
|
||||
devices?: DeviceEntry[];
|
||||
}
|
||||
|
||||
function fakeHass(opts: FakeOpts = {}) {
|
||||
const entries = opts.entries ?? {};
|
||||
const calls: string[] = [];
|
||||
const submitted: Record<string, unknown>[] = [];
|
||||
const flows = new Map<string, { handler: string; entryId?: string; step: string; reauth?: boolean }>();
|
||||
let n = 0;
|
||||
const accepts = opts.accepts ?? (() => true);
|
||||
const form = (id: string, step: string, schema: SchemaField[], errors?: Record<string, string>): FlowResult => ({
|
||||
type: "form", flow_id: id, step_id: step, data_schema: schema, errors: errors ?? null,
|
||||
});
|
||||
const servarrUser: SchemaField[] = [
|
||||
{ name: "url", type: "string", required: true },
|
||||
{ name: "api_key", type: "string", required: true },
|
||||
{ name: "more_options", type: "expandable", required: true, schema: [{ name: "verify_ssl", type: "boolean", optional: true, default: false }] },
|
||||
];
|
||||
const hass: Hass = {
|
||||
async entries(domain) {
|
||||
calls.push(`entries ${domain}`);
|
||||
return (entries[domain] ?? []).map(({ data: _d, ...e }) => e);
|
||||
},
|
||||
async startFlow(handler, entryId) {
|
||||
calls.push(`start ${handler}${entryId ? ` ${entryId}` : ""}`);
|
||||
const id = `f${++n}`;
|
||||
if (handler === "mqtt") {
|
||||
const entry = entryId ? entries.mqtt.find((e) => e.entry_id === entryId) : undefined;
|
||||
if (entryId && !entry) return { type: "abort", reason: "not_found" };
|
||||
flows.set(id, { handler, entryId, step: "broker" });
|
||||
return form(id, "broker", brokerForm(entry?.data ?? {}));
|
||||
}
|
||||
if (entryId) return { type: "abort", reason: "not_implemented" }; // no reconfigure for Servarr
|
||||
flows.set(id, { handler, step: "user" });
|
||||
return form(id, "user", servarrUser);
|
||||
},
|
||||
async stepFlow(flowId, input) {
|
||||
calls.push(`step ${flowId}`);
|
||||
const flow = flows.get(flowId);
|
||||
if (!flow) throw new Error(`Home Assistant POST flow/${flowId} answered 404`);
|
||||
if (flow.step === "reauth_confirm") {
|
||||
flow.step = "user";
|
||||
return form(flowId, "user", [
|
||||
{ name: "url", type: "string", required: true, default: "http://old:1" },
|
||||
{ name: "api_key", type: "string", optional: true },
|
||||
{ name: "verify_ssl", type: "boolean", optional: true, default: false },
|
||||
]);
|
||||
}
|
||||
submitted.push(input);
|
||||
if (flow.handler === "mqtt") {
|
||||
const entry = entries.mqtt?.find((e) => e.entry_id === flow.entryId);
|
||||
const data = { ...input, ...(input.password === PWD_NOT_CHANGED ? { password: entry?.data.password } : {}) };
|
||||
if (!accepts(data)) return form(flowId, "broker", brokerForm(data), { base: "cannot_connect" });
|
||||
flows.delete(flowId);
|
||||
if (entry) {
|
||||
entry.data = data;
|
||||
return { type: "abort", reason: "reconfigure_successful" };
|
||||
}
|
||||
(entries.mqtt ??= []).push({ entry_id: "new-mqtt", domain: "mqtt", state: "loaded", data });
|
||||
return { type: "create_entry", result: { entry_id: "new-mqtt" } };
|
||||
}
|
||||
if (!accepts(input)) return form(flowId, "user", servarrUser, { base: "invalid_auth" });
|
||||
flows.delete(flowId);
|
||||
if (flow.reauth) return { type: "abort", reason: "reauth_successful" };
|
||||
(entries[flow.handler] ??= []).push({ entry_id: `new-${flow.handler}`, domain: flow.handler, state: "loaded", data: input });
|
||||
return { type: "create_entry", result: { entry_id: `new-${flow.handler}` } };
|
||||
},
|
||||
async abortFlow(flowId) {
|
||||
calls.push(`abort ${flowId}`);
|
||||
flows.delete(flowId);
|
||||
},
|
||||
async flowsInProgress() {
|
||||
for (const f of opts.reauth ?? []) flows.set(f.flow_id, { handler: f.handler, entryId: f.context?.entry_id, step: "reauth_confirm", reauth: true });
|
||||
return opts.reauth ?? [];
|
||||
},
|
||||
async devices() {
|
||||
return opts.devices ?? [];
|
||||
},
|
||||
};
|
||||
return { hass, calls, submitted, entries };
|
||||
}
|
||||
|
||||
function memoryMarks(): Marks & { store: Map<string, string> } {
|
||||
const store = new Map<string, string>();
|
||||
return { store, get: async (k) => store.get(k), set: async (k, v) => void store.set(k, v) };
|
||||
}
|
||||
|
||||
const takes = (suback = 0): Probe => async (_h, _p, user, pass) => ({ connack: user === "mesh_ace_hass" && pass === MINTED ? 0 : 5, suback });
|
||||
|
||||
const aceMqttEntry = () => ({
|
||||
entry_id: "7d1e", domain: "mqtt", state: "loaded",
|
||||
data: { broker: "127.0.0.1", port: 1883, protocol: "5", username: "luffy", password: "luffys-password" },
|
||||
});
|
||||
|
||||
test("mqtt: the broker is asked first; a login it does not take is never written", async () => {
|
||||
const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
|
||||
const out = await reconcileMqtt({ hass: f.hass, probe: async () => ({ connack: 5 }), marks: memoryMarks() }, mqttBinding(), MINTED);
|
||||
assert.equal(out.result, "refused");
|
||||
assert.match((out as { problem: string }).problem, /does not \(yet\) take the login mesh_ace_hass/);
|
||||
assert.deepEqual(f.calls, []); // Home Assistant not even asked
|
||||
assert.equal(f.entries.mqtt[0].data.username, "luffy");
|
||||
});
|
||||
|
||||
test("mqtt: ace's entry (127.0.0.1, luffy) is moved to the bound broker and login, every other setting kept", async () => {
|
||||
const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
|
||||
const marks = memoryMarks();
|
||||
const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), `${MINTED}\n`);
|
||||
assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["broker", "username", "password"] });
|
||||
assert.deepEqual(f.entries.mqtt[0].data, {
|
||||
broker: "ace.internal", port: 1883, protocol: "5", username: "mesh_ace_hass", password: MINTED,
|
||||
other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
|
||||
});
|
||||
assert.ok(marks.store.get("mqtt"));
|
||||
assert.ok(![...marks.store.values()].some((v) => v.includes(MINTED)));
|
||||
|
||||
// Run again: nothing differs, the flow is opened to read and closed without submitting.
|
||||
const before = f.submitted.length;
|
||||
const again = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
|
||||
assert.deepEqual(again, { what: "mqtt", result: "unchanged" });
|
||||
assert.equal(f.submitted.length, before);
|
||||
assert.match(f.calls.at(-1) ?? "", /^abort /);
|
||||
});
|
||||
|
||||
test("mqtt: a new password alone is written (the digest tells)", async () => {
|
||||
const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
|
||||
const marks = memoryMarks();
|
||||
await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
|
||||
const rotated: Probe = async () => ({ connack: 0, suback: 0 });
|
||||
const out = await reconcileMqtt({ hass: f.hass, probe: rotated, marks }, mqttBinding(), "rotated");
|
||||
assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["password"] });
|
||||
assert.equal(f.entries.mqtt[0].data.password, "rotated");
|
||||
});
|
||||
|
||||
test("mqtt: Home Assistant's own connection test refusing saves nothing and fails loudly", async () => {
|
||||
const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] }, accepts: () => false });
|
||||
const marks = memoryMarks();
|
||||
const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
|
||||
assert.equal(out.result, "refused");
|
||||
assert.match((out as { problem: string }).problem, /cannot_connect.*unchanged/);
|
||||
assert.equal(f.entries.mqtt[0].data.username, "luffy");
|
||||
assert.equal(marks.store.size, 0);
|
||||
});
|
||||
|
||||
test("mqtt: a fresh Home Assistant gets an entry; a grant without the discovery topics is warned about", async () => {
|
||||
const f = fakeHass();
|
||||
const out = await reconcileMqtt({ hass: f.hass, probe: takes(0x80), marks: memoryMarks() }, mqttBinding(), MINTED);
|
||||
assert.equal(out.result, "written");
|
||||
assert.match((out as { note?: string }).note ?? "", /may not subscribe to homeassistant\/#/);
|
||||
assert.equal(f.entries.mqtt[0].data.broker, "ace.internal");
|
||||
});
|
||||
|
||||
test("mqtt: two entries, or a binding without a port, are refused rather than guessed", async () => {
|
||||
const f = fakeHass({ entries: { mqtt: [aceMqttEntry(), { ...aceMqttEntry(), entry_id: "other" }] } });
|
||||
assert.equal((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, mqttBinding(), MINTED)).result, "refused");
|
||||
const noPort = { ...mqttBinding(), serves: {} };
|
||||
assert.match(((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, noPort, MINTED)) as { problem: string }).problem, /no usable port/);
|
||||
});
|
||||
|
||||
// ---- Servarr ----
|
||||
|
||||
const SONARR = APPS.find((a) => a.domain === "sonarr") as ServarrApp;
|
||||
const RADARR = APPS.find((a) => a.domain === "radarr") as ServarrApp;
|
||||
const KEY = "the-apps-own-key";
|
||||
const servarrBinding = (port: number, at = "ace.internal"): Binding => ({ provision: "sonarr-api", from: "ace", at, as: "mesh_ace_hass", serves: { scheme: "http", port, "url-base": "" } });
|
||||
|
||||
/** One running Sonarr, answering on several addresses (127.0.0.1 and ace.internal are one host). */
|
||||
function apps(instances: Record<string, { startTime: string }>): Http & { asked: string[] } {
|
||||
const asked: string[] = [];
|
||||
return {
|
||||
asked,
|
||||
async fetch(url, init) {
|
||||
asked.push(url);
|
||||
const u = new URL(url);
|
||||
const inst = instances[`${u.hostname}:${u.port}`];
|
||||
if (!inst) throw new Error("connect ECONNREFUSED");
|
||||
if (init?.headers?.["X-Api-Key"] !== KEY) return { status: 401, text: async () => "" };
|
||||
return { status: 200, text: async () => JSON.stringify({ version: "4.0.15", appData: "/config", startTime: inst.startTime }) };
|
||||
},
|
||||
};
|
||||
}
|
||||
const oneSonarr = () => apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "t1" } });
|
||||
const sonarrEntry = (state = "loaded") => ({ entry_id: "5a1d", domain: "sonarr", state, data: { url: "http://127.0.0.1:8989", api_key: KEY } });
|
||||
|
||||
test("servarr: the mesh's minted key is never written; the remedy names the accept", async () => {
|
||||
const f = fakeHass({ entries: { sonarr: [sonarrEntry()] } });
|
||||
const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), "minted-by-the-mesh");
|
||||
assert.equal(out.result, "refused");
|
||||
assert.match((out as { problem: string }).problem, /secret accept <this node> home-assistant sonarr-api --provider ace/);
|
||||
assert.deepEqual(f.calls, []);
|
||||
});
|
||||
|
||||
test("servarr: ace's entry at 127.0.0.1 reaches the same Sonarr the mesh bound at ace.internal — left, and said", async () => {
|
||||
const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
|
||||
const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
|
||||
assert.equal(out.result, "equivalent");
|
||||
assert.equal(f.submitted.length, 0);
|
||||
});
|
||||
|
||||
test("servarr: an entry already at the bound URL is unchanged", async () => {
|
||||
const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://ace.internal:8989" }] });
|
||||
assert.deepEqual(await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY), { what: "sonarr", result: "unchanged" });
|
||||
});
|
||||
|
||||
test("servarr: a working entry that reaches a different app is refused, and nothing is removed", async () => {
|
||||
const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
|
||||
const two = apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "another" } });
|
||||
const out = await reconcileApp({ hass: f.hass, http: two }, SONARR, servarrBinding(8989), KEY);
|
||||
assert.equal(out.result, "refused");
|
||||
assert.match((out as { problem: string }).problem, /never does/);
|
||||
assert.equal(f.entries.sonarr.length, 1);
|
||||
});
|
||||
|
||||
test("servarr: no entry — one is made at the bound URL through the user flow", async () => {
|
||||
const f = fakeHass({ entries: {} });
|
||||
const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
|
||||
assert.deepEqual(out, { what: "sonarr", result: "written", fields: ["entry"] });
|
||||
assert.deepEqual(f.submitted[0], { url: "http://ace.internal:8989", api_key: KEY, more_options: { verify_ssl: false } });
|
||||
});
|
||||
|
||||
test("servarr: a reauth Home Assistant started is finished with the bound URL and key", async () => {
|
||||
const entry = { ...sonarrEntry("setup_error"), domain: "radarr", entry_id: "1955" };
|
||||
const f = fakeHass({
|
||||
entries: { radarr: [entry] },
|
||||
reauth: [{ flow_id: "r1", handler: "radarr", step_id: "reauth_confirm", context: { source: "reauth", entry_id: "1955" } }],
|
||||
});
|
||||
const radarr = apps({ "ace.internal:7878": { startTime: "t" } });
|
||||
const out = await reconcileApp({ hass: f.hass, http: radarr }, RADARR, { ...servarrBinding(7878), provision: "radarr-api" }, KEY);
|
||||
assert.deepEqual(out, { what: "radarr", result: "written", fields: ["api_key", "url"] });
|
||||
assert.deepEqual(f.submitted[0], { url: "http://ace.internal:7878", api_key: KEY, verify_ssl: false });
|
||||
});
|
||||
|
||||
test("form values: suggested first, then default, sections nested", () => {
|
||||
assert.deepEqual(formValues(brokerForm({ broker: "b", port: 1, protocol: "5", username: "u", password: "p" })), {
|
||||
broker: "b", port: 1, protocol: "5", username: "u", password: PWD_NOT_CHANGED,
|
||||
other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
|
||||
});
|
||||
assert.ok(sameUrl("http://ace.internal:8989/", "http://ace.internal:8989"));
|
||||
assert.ok(sameUrl("http://ACE.internal", "http://ace.internal:80"));
|
||||
assert.ok(!sameUrl("http://127.0.0.1:8989", "http://ace.internal:8989"));
|
||||
});
|
||||
@@ -8,14 +8,5 @@
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": [
|
||||
"client.ts",
|
||||
"index.ts",
|
||||
"tools/index.ts",
|
||||
"provisions/hass.ts",
|
||||
"provisions/probe.ts",
|
||||
"provisions/connections.ts",
|
||||
"provisions/mesh.ts",
|
||||
"provisions/index.ts"
|
||||
]
|
||||
"include": ["client.ts", "index.ts", "tools/index.ts"]
|
||||
}
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
"stream.stopped"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/icecast/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -44,8 +44,8 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/icecast",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -91,7 +91,7 @@
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/icecast/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
@@ -102,8 +102,8 @@
|
||||
"name": "mesh-icecast",
|
||||
"network": "icecast",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
"/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",
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
"container-runtime"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker",
|
||||
"broker": "/var/lib/mesh/influxdb/broker",
|
||||
"admin": "${dir:state}/admin.secret",
|
||||
"admin-token": "${dir:state}/admin-token.secret"
|
||||
},
|
||||
@@ -42,8 +42,8 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/influxdb",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -96,7 +96,7 @@
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/influxdb/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
@@ -107,8 +107,8 @@
|
||||
"name": "mesh-influxdb",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"/var/lib/mesh/influxdb/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/influxdb/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/admin-token.secret:/run/secrets/admin-token:ro",
|
||||
"${dir:grants}:${dir:grants}:ro"
|
||||
],
|
||||
|
||||
@@ -26,13 +26,13 @@
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"mongodb-database": "${dir:state}/database.json",
|
||||
"s3-bucket": "${dir:state}/store.json",
|
||||
"route": "${dir:state}/route.json"
|
||||
"mongodb-database": "/var/lib/invoicing/database.json",
|
||||
"s3-bucket": "/var/lib/invoicing/store.json",
|
||||
"route": "/var/lib/invoicing/route.json"
|
||||
},
|
||||
"secrets": {
|
||||
"mongodb-database": "${dir:state}/database.secret",
|
||||
"s3-bucket": "${dir:state}/store.secret"
|
||||
"mongodb-database": "/var/lib/invoicing/database.secret",
|
||||
"s3-bucket": "/var/lib/invoicing/store.secret"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -54,19 +54,19 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/invoicing",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/invoicing",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "api-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/api.env",
|
||||
"path": "/var/lib/invoicing/api.env",
|
||||
"mode": "0600",
|
||||
"content": "NODE_ENV=production\nPORT=9000\nMONGO_URL=mongodb://${bound:mongodb-database:as}:${secret:mongodb-database}@${bound:mongodb-database:at}:${bound:mongodb-database:port}/${bound:mongodb-database:as}?authSource=${bound:mongodb-database:as}\nMONGO_DB=${bound:mongodb-database:as}\nMINIO_BUCKET=mesh-novox-invoice\nMINIO_ENDPOINT=${bound:s3-bucket:at}\nMINIO_PORT=${bound:s3-bucket:port}\nMINIO_ACCESSKEY=${bound:s3-bucket:as}\nMINIO_SECRET=${secret:s3-bucket}\n"
|
||||
},
|
||||
@@ -103,7 +103,7 @@
|
||||
"GID": "2201"
|
||||
},
|
||||
"env-file": [
|
||||
"${dir:state}/api.env"
|
||||
"/var/lib/invoicing/api.env"
|
||||
],
|
||||
"ports": [
|
||||
"9000"
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# jackett'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 in
|
||||
# the base images, published like any other artifact — which 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 (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/jackett
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/jackett/dist /app/modules/jackett/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/jackett/dist/tools/index.js
|
||||
@@ -0,0 +1,136 @@
|
||||
// The Jackett API client — jackett's own code, living in the module (novox/hq ADR 0039). Jackett is
|
||||
// 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 { existsSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
export interface JackettIndexer {
|
||||
id: string;
|
||||
name: string;
|
||||
type: string; // "public" | "private" | "semi-public"
|
||||
configured: boolean;
|
||||
siteLink?: string;
|
||||
lastError?: string;
|
||||
}
|
||||
|
||||
export interface JackettResult {
|
||||
title: string;
|
||||
tracker: string;
|
||||
category?: string;
|
||||
size: number;
|
||||
seeders?: number;
|
||||
peers?: number;
|
||||
publishDate?: string;
|
||||
link?: string;
|
||||
}
|
||||
|
||||
/** 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 {};
|
||||
try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
|
||||
catch { return {}; }
|
||||
}
|
||||
|
||||
export class JackettClient {
|
||||
readonly baseUrl: string;
|
||||
|
||||
constructor(
|
||||
url: string,
|
||||
private readonly apiKey: string,
|
||||
) {
|
||||
this.baseUrl = url.replace(/\/$/, "");
|
||||
}
|
||||
|
||||
/**
|
||||
* Build from the module's resolved environment. Jackett's REST API is keyed, so both the URL and
|
||||
* the key must be present. The key is read from the settings-merged config or MESH_JACKETT_API_KEY,
|
||||
* 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
|
||||
?? 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 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);
|
||||
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
|
||||
const res = await fetch(url.toString(), { headers: { Accept: "application/json" } });
|
||||
if (!res.ok) throw new Error(`Jackett API ${path}: ${res.status} ${await res.text()}`);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
/**
|
||||
* 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 url = new URL(`${this.baseUrl}/api/v2.0/indexers/all/results/torznab/api`);
|
||||
url.searchParams.set("apikey", this.apiKey);
|
||||
url.searchParams.set("t", "indexers");
|
||||
url.searchParams.set("configured", configuredOnly ? "true" : "false");
|
||||
const res = await fetch(url.toString(), { headers: { Accept: "application/xml" } });
|
||||
if (!res.ok) throw new Error(`Jackett API torznab t=indexers: ${res.status} ${await res.text()}`);
|
||||
const xml = await res.text();
|
||||
// Torznab reports failures (a wrong key among them) as 200 with an <error> body.
|
||||
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;
|
||||
}
|
||||
|
||||
/**
|
||||
* A Torznab search across one indexer, or the "all" aggregate. Jackett returns a normalised JSON
|
||||
* result set regardless of the underlying tracker, which is the whole point of the proxy.
|
||||
*/
|
||||
async search(query: string, indexer = "all", limit = 25): Promise<JackettResult[]> {
|
||||
const raw = await this.get(`/api/v2.0/indexers/${encodeURIComponent(indexer)}/results`, { Query: query });
|
||||
const results = Array.isArray(raw?.Results) ? raw.Results : [];
|
||||
return results.slice(0, limit).map((r: any) => ({
|
||||
title: r.Title,
|
||||
tracker: r.Tracker ?? r.TrackerId ?? "unknown",
|
||||
category: Array.isArray(r.CategoryDesc) ? r.CategoryDesc.join(", ") : r.CategoryDesc,
|
||||
size: r.Size ?? 0,
|
||||
seeders: r.Seeders,
|
||||
peers: r.Peers,
|
||||
publishDate: r.PublishDate,
|
||||
link: r.Link ?? r.Details,
|
||||
}));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,131 @@
|
||||
{
|
||||
"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: its web UI, and the Torznab feeds the *arr apps search through, which other modules reach as jackett-api"
|
||||
}
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh/jackett",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"owner": "1000:1000"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "jackett",
|
||||
"image": "lscr.io/linuxserver/jackett@sha256:7b19f4f6ac33d855ca9226600ecbd096ee678f66da28b13a7c09980b035ff583",
|
||||
"env": {
|
||||
"PUID": "1000",
|
||||
"PGID": "1000",
|
||||
"TZ": "Etc/UTC"
|
||||
},
|
||||
"ports": [
|
||||
"9117"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:config}:/config"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-jackett",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"/var/lib/mesh/jackett/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:config}:/var/lib/jackett/config:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"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"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "/var/lib/mesh/jackett/broker"
|
||||
},
|
||||
"requires": [
|
||||
"route"
|
||||
],
|
||||
"contributes": {
|
||||
"route": {
|
||||
"label": "indexers",
|
||||
"endpoint": "web"
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "${dir:state}/route.json"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "@novox/module-jackett",
|
||||
"version": "0.1.0",
|
||||
"description": "jackett — indexer proxy. Its API client and tools live here (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"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
// jackett's tools — its own code (novox/hq ADR 0039), importing jackett's client. Jackett has
|
||||
// nothing worth watching (an indexer proxy answers queries; it has no timeline of its own), so it
|
||||
// is a tools-only module: no events entrypoint, no broker. What is useful is asking it things.
|
||||
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { JackettClient } from "../client.js";
|
||||
|
||||
export function getJackettTools(jackett: JackettClient): ToolDefinition[] {
|
||||
return [
|
||||
{
|
||||
name: "jackett_indexers",
|
||||
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);
|
||||
return { count: indexers.length, indexers };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "jackett_search",
|
||||
description: "Torznab search across Jackett's indexers, returning normalised torrent results.",
|
||||
input: {
|
||||
query: { type: "string", description: "the search query" },
|
||||
indexer: { type: "string", description: 'an indexer id, or "all" to aggregate (default "all")' },
|
||||
limit: { type: "number", description: "max results (default 25)" },
|
||||
},
|
||||
run: async (args) => {
|
||||
const query = String(args.query);
|
||||
const results = await jackett.search(
|
||||
query,
|
||||
args.indexer ? String(args.indexer) : "all",
|
||||
args.limit ? Number(args.limit) : 25,
|
||||
);
|
||||
return { query, count: results.length, results };
|
||||
},
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
// Only exposed when Jackett is configured; otherwise jackett contributes no tools rather than
|
||||
// failing the whole runtime.
|
||||
registerModuleTools("jackett", (env) => {
|
||||
try {
|
||||
return getJackettTools(JackettClient.fromEnv(env));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
});
|
||||
@@ -8,5 +8,5 @@
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["tools/index.ts", "tools/runs.ts"]
|
||||
"include": ["client.ts", "tools/index.ts"]
|
||||
}
|
||||
+10
-10
@@ -2,26 +2,26 @@
|
||||
"module": "jira",
|
||||
"version": "1",
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"token": "/var/lib/jira/token",
|
||||
"broker": "/var/lib/mesh/jira/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/jira",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/jira",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/config.json",
|
||||
"path": "/var/lib/jira/config.json",
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
@@ -32,9 +32,9 @@
|
||||
"name": "mesh-runtime-jira",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
"/var/lib/jira/config.json:/run/config/config.json:ro",
|
||||
"/var/lib/jira/token:/run/secrets/token:ro",
|
||||
"/var/lib/mesh/jira/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_JIRA_TOKEN_FILE": "/run/secrets/token",
|
||||
|
||||
@@ -17,7 +17,7 @@ FROM ${BUILD_BASE} AS build
|
||||
# resolved away.
|
||||
WORKDIR /app/modules/keycloak
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts \
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
@@ -27,4 +27,4 @@ COPY --from=build /app/modules/keycloak/dist /app/modules/keycloak/dist
|
||||
# the convention novox/hq issues 060/061 settled. A container that instead ran only its
|
||||
# provisioner (`run`) served no tools and emitted no events; a container that named no command
|
||||
# ran no provisioner at all.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js,/app/modules/keycloak/dist/provisioner/index.js
|
||||
ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js
|
||||
|
||||
@@ -12,45 +12,6 @@ function meshConfig(file?: string): Record<string, string> {
|
||||
catch { return {}; }
|
||||
}
|
||||
|
||||
/** A secret file's value, trailing newline trimmed; undefined when unset or unreadable. */
|
||||
function secretFile(file?: string): string | undefined {
|
||||
if (!file) return undefined;
|
||||
try { return readFileSync(file, "utf8").replace(/\n$/, "") || undefined; }
|
||||
catch { return undefined; }
|
||||
}
|
||||
|
||||
/** A client as the admin API represents it — only the fields this module reads or writes are typed;
|
||||
* the rest travel through untouched, so an update never drops what somebody else set. */
|
||||
export interface ClientRepresentation {
|
||||
id?: string;
|
||||
clientId: string;
|
||||
name?: string;
|
||||
enabled?: boolean;
|
||||
protocol?: string;
|
||||
publicClient?: boolean;
|
||||
clientAuthenticatorType?: string;
|
||||
secret?: string;
|
||||
rootUrl?: string;
|
||||
baseUrl?: string;
|
||||
redirectUris?: string[];
|
||||
webOrigins?: string[];
|
||||
standardFlowEnabled?: boolean;
|
||||
implicitFlowEnabled?: boolean;
|
||||
directAccessGrantsEnabled?: boolean;
|
||||
serviceAccountsEnabled?: boolean;
|
||||
attributes?: Record<string, string>;
|
||||
protocolMappers?: ProtocolMapperRepresentation[];
|
||||
[other: string]: unknown;
|
||||
}
|
||||
|
||||
export interface ProtocolMapperRepresentation {
|
||||
id?: string;
|
||||
name: string;
|
||||
protocol: string;
|
||||
protocolMapper: string;
|
||||
config: Record<string, string>;
|
||||
}
|
||||
|
||||
export class KeycloakClient {
|
||||
readonly baseUrl: string;
|
||||
readonly defaultRealm: string;
|
||||
@@ -79,13 +40,8 @@ export class KeycloakClient {
|
||||
const cfg = meshConfig(env.MESH_KEYCLOAK_CONFIG_FILE);
|
||||
const url = cfg.url ?? env.MESH_KEYCLOAK_URL ?? `http://127.0.0.1:${env.KEYCLOAK_PORT ?? "8080"}`;
|
||||
const adminUser = cfg.user ?? env.MESH_KEYCLOAK_ADMIN ?? env.KEYCLOAK_ADMIN ?? "admin";
|
||||
// The admin password reaches the runtime as a file (novox/hq ADR 0086): the module's own `admin`
|
||||
// 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 adminPass = cfg.password ?? env.MESH_KEYCLOAK_PASSWORD ?? env.KEYCLOAK_ADMIN_PASSWORD;
|
||||
if (!adminPass) throw new Error("no Keycloak admin password — set MESH_KEYCLOAK_PASSWORD");
|
||||
const realm = cfg.realm ?? env.MESH_KEYCLOAK_REALM ?? "master";
|
||||
return new KeycloakClient(url, adminUser, adminPass, realm);
|
||||
}
|
||||
@@ -203,50 +159,6 @@ export class KeycloakClient {
|
||||
return client.id as string;
|
||||
}
|
||||
|
||||
/** The one client with exactly this clientId, or undefined. The admin API's `clientId` filter is an
|
||||
* exact match unless `search=true` is asked for. */
|
||||
async findClient(realm: string, clientId: string): Promise<ClientRepresentation | undefined> {
|
||||
const found = await this.request<ClientRepresentation[]>(
|
||||
`/${realm}/clients?clientId=${encodeURIComponent(clientId)}`);
|
||||
return found.find((c) => c.clientId === clientId);
|
||||
}
|
||||
|
||||
async createClientFrom(realm: string, rep: ClientRepresentation): Promise<void> {
|
||||
await this.request(`/${realm}/clients`, { method: "POST", body: JSON.stringify(rep) });
|
||||
}
|
||||
|
||||
/** Replace a client's representation, addressed by its internal id. */
|
||||
async updateClient(realm: string, id: string, rep: ClientRepresentation): Promise<void> {
|
||||
await this.request(`/${realm}/clients/${id}`, { method: "PUT", body: JSON.stringify(rep) });
|
||||
}
|
||||
|
||||
async deleteClientById(realm: string, id: string): Promise<void> {
|
||||
await this.request(`/${realm}/clients/${id}`, { method: "DELETE" });
|
||||
}
|
||||
|
||||
async clientSecretById(realm: string, id: string): Promise<string | undefined> {
|
||||
const result = await this.request<{ value?: string }>(`/${realm}/clients/${id}/client-secret`);
|
||||
return result.value;
|
||||
}
|
||||
|
||||
async listClientMappers(realm: string, id: string): Promise<ProtocolMapperRepresentation[]> {
|
||||
return this.request(`/${realm}/clients/${id}/protocol-mappers/models`);
|
||||
}
|
||||
|
||||
async addClientMapper(realm: string, id: string, mapper: ProtocolMapperRepresentation): Promise<void> {
|
||||
await this.request(`/${realm}/clients/${id}/protocol-mappers/models`, {
|
||||
method: "POST",
|
||||
body: JSON.stringify(mapper),
|
||||
});
|
||||
}
|
||||
|
||||
async updateClientMapper(realm: string, id: string, mapper: ProtocolMapperRepresentation): Promise<void> {
|
||||
await this.request(`/${realm}/clients/${id}/protocol-mappers/models/${mapper.id}`, {
|
||||
method: "PUT",
|
||||
body: JSON.stringify(mapper),
|
||||
});
|
||||
}
|
||||
|
||||
async deleteClient(realm: string, clientId: string): Promise<void> {
|
||||
await this.request(`/${realm}/clients/${await this.resolveClientId(realm, clientId)}`, { method: "DELETE" });
|
||||
}
|
||||
|
||||
@@ -1,12 +1,6 @@
|
||||
{
|
||||
"module": "keycloak",
|
||||
"version": "1",
|
||||
"provides": [
|
||||
{
|
||||
"name": "oidc-client",
|
||||
"scope": "mesh"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
"postgres-database",
|
||||
"route"
|
||||
@@ -21,11 +15,11 @@
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"postgres-database": "${dir:state}/database.json",
|
||||
"route": "${dir:state}/route.json"
|
||||
"postgres-database": "/var/lib/keycloak/database.json",
|
||||
"route": "/var/lib/keycloak/route.json"
|
||||
},
|
||||
"secrets": {
|
||||
"postgres-database": "${dir:state}/database.secret"
|
||||
"postgres-database": "/var/lib/keycloak/database.secret"
|
||||
},
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
@@ -47,53 +41,34 @@
|
||||
"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",
|
||||
"issuer": "${setting:issuer}"
|
||||
}
|
||||
},
|
||||
"receives": {
|
||||
"oidc-client": "${dir:grants}/mesh.json"
|
||||
},
|
||||
"grants": {
|
||||
"oidc-client": "${dir:grants}"
|
||||
},
|
||||
"own-secrets": {
|
||||
"admin": "${dir:state}/admin.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"admin": "/var/lib/keycloak/admin.secret",
|
||||
"broker": "/var/lib/mesh/keycloak/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/keycloak",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
},
|
||||
{
|
||||
"id": "grants",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/keycloak",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "admin-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/admin.env",
|
||||
"path": "/var/lib/keycloak/admin.env",
|
||||
"mode": "0600",
|
||||
"content": "KEYCLOAK_ADMIN=admin\nKEYCLOAK_ADMIN_PASSWORD=${secret:admin}\n"
|
||||
},
|
||||
{
|
||||
"id": "database-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/database.env",
|
||||
"path": "/var/lib/keycloak/database.env",
|
||||
"mode": "0600",
|
||||
"content": "KC_DB_URL=jdbc:postgresql://${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\nKC_DB_USERNAME=${bound:postgres-database:as}\nKC_DB_PASSWORD=${secret:postgres-database}\n"
|
||||
},
|
||||
@@ -103,10 +78,10 @@
|
||||
"name": "keycloak"
|
||||
},
|
||||
{
|
||||
"id": "hostname",
|
||||
"id": "hostname-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/hostname.env",
|
||||
"mode": "0644",
|
||||
"path": "/var/lib/keycloak/hostname.env",
|
||||
"mode": "0600",
|
||||
"content": "KC_HOSTNAME=https://${bound:route:name}\n"
|
||||
},
|
||||
{
|
||||
@@ -125,22 +100,19 @@
|
||||
"KC_PROXY_HEADERS": "xforwarded"
|
||||
},
|
||||
"env-file": [
|
||||
"${dir:state}/admin.env",
|
||||
"${dir:state}/database.env",
|
||||
"${dir:state}/hostname.env"
|
||||
"/var/lib/keycloak/admin.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",
|
||||
"restart-on": [
|
||||
"hostname"
|
||||
]
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/keycloak/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
@@ -151,17 +123,13 @@
|
||||
"name": "mesh-keycloak",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/admin.secret:/run/secrets/admin:ro",
|
||||
"${dir:grants}:${dir:grants}:ro"
|
||||
"/var/lib/mesh/keycloak/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/keycloak/config.json:/run/config/config.json: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_PASSWORD_FILE": "/run/secrets/admin",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
"MESH_KEYCLOAK_CONFIG_FILE": "/run/config/config.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
|
||||
@@ -1,185 +0,0 @@
|
||||
// What the `oidc-client` provision means in Keycloak: one confidential OpenID Connect client per
|
||||
// consumer, in the realm this module serves, under the name and secret the mesh gave both ends.
|
||||
// The provisioner (provisioner/index.ts) is the sdk harness calling these; they are here, apart from
|
||||
// it, so they can be exercised against a fake admin API without a broker or a contributions file.
|
||||
//
|
||||
// **The client id and the secret are the mesh's, not Keycloak's (novox/hq ADR 0048).** The mesh
|
||||
// derives the consumer's identity (`as`, e.g. `mesh_ace_grafana`) and hands it to both ends — the
|
||||
// consumer names it as its client id through `${bound:oidc-client:as}` — and mints the secret, which
|
||||
// this sets as the client's secret. Keycloak generates neither.
|
||||
//
|
||||
// **Where the consumer's browser comes back to is the consumer's to say.** Its contribution carries
|
||||
// `callback` (a path, e.g. `/login/generic_oauth`) and the `label`/`endpoint` of the endpoint it is
|
||||
// reached on; the mesh composes that endpoint's names into `name` (public) and `internal-name`
|
||||
// (private network) exactly as it does for a route (novox/hq ADR 0056, 0138), so the redirect URI
|
||||
// registered here is built from the same names the proxy serves the consumer under.
|
||||
//
|
||||
// **Only what the mesh made is touched.** A client this module creates carries the attribute
|
||||
// `mesh.provisioned=true`, and its id starts with the mesh's own prefix. A client with the same id
|
||||
// that lacks the mark is somebody else's: it is refused, never adopted, never updated, never deleted.
|
||||
|
||||
import type { ClientRepresentation, KeycloakClient, ProtocolMapperRepresentation } from "./client.js";
|
||||
|
||||
/** The attribute marking a client as the mesh's own work. */
|
||||
export const MARK = "mesh.provisioned";
|
||||
|
||||
/** The mapper every mesh client carries: realm roles as a flat `roles` claim in the id token, the
|
||||
* access token and userinfo — what a consumer maps its own roles from (grafana's role path reads
|
||||
* `roles[*]`), and what the predecessor added to its hand-made clients by hand. */
|
||||
export const ROLES_MAPPER: ProtocolMapperRepresentation = {
|
||||
name: "realm roles",
|
||||
protocol: "openid-connect",
|
||||
protocolMapper: "oidc-usermodel-realm-role-mapper",
|
||||
config: {
|
||||
"claim.name": "roles",
|
||||
"jsonType.label": "String",
|
||||
multivalued: "true",
|
||||
"id.token.claim": "true",
|
||||
"access.token.claim": "true",
|
||||
"userinfo.token.claim": "true",
|
||||
},
|
||||
};
|
||||
|
||||
/** One consumer, as the harness hands it over. */
|
||||
export interface OidcGrant {
|
||||
readonly as: string;
|
||||
readonly password: string;
|
||||
readonly values: Readonly<Record<string, unknown>>;
|
||||
readonly consumer?: string;
|
||||
}
|
||||
|
||||
/** The realm named by an issuer URL — `https://id.example/realms/Novox` is realm `Novox`. The issuer is
|
||||
* the one value an assignment sets (it is also what consumers are served), so the realm is read
|
||||
* out of it rather than set a second time where the two could disagree. */
|
||||
export function realmOf(issuer: string): string {
|
||||
let path: string;
|
||||
try {
|
||||
path = new URL(issuer).pathname;
|
||||
} catch {
|
||||
throw new Error(`the issuer ${JSON.stringify(issuer)} is not a URL`);
|
||||
}
|
||||
const m = /\/realms\/([^/]+)\/?$/.exec(path);
|
||||
if (!m) throw new Error(`the issuer ${JSON.stringify(issuer)} does not end in /realms/<realm>`);
|
||||
return decodeURIComponent(m[1]);
|
||||
}
|
||||
|
||||
/** The redirect URIs a consumer's contribution asks for: its callback under each name the mesh
|
||||
* composed for its endpoint. Refused when there is nothing to register — a client that accepts no
|
||||
* redirect is a client nobody can log in through, and one that accepts any is worse. */
|
||||
export function redirectsOf(values: Readonly<Record<string, unknown>>): { root: string; redirects: string[] } {
|
||||
const callback = values.callback;
|
||||
if (typeof callback !== "string" || !callback.startsWith("/")) {
|
||||
throw new Error(`contributes no callback path (\`callback\`, starting with "/"): ${JSON.stringify(callback)}`);
|
||||
}
|
||||
const names: string[] = [];
|
||||
for (const key of ["name", "internal-name"]) {
|
||||
const n = values[key];
|
||||
if (typeof n === "string" && n.trim() !== "" && !names.includes(n.trim())) names.push(n.trim());
|
||||
}
|
||||
if (names.length === 0) {
|
||||
throw new Error("has no name the mesh composed (`name` / `internal-name`) — contribute a `label` and the `endpoint` it is reached on");
|
||||
}
|
||||
return { root: `https://${names[0]}`, redirects: names.map((n) => `https://${n}${callback}`) };
|
||||
}
|
||||
|
||||
/** The fields the mesh owns on a client it made. Everything else on the client is left as found. */
|
||||
function wanted(g: OidcGrant): ClientRepresentation {
|
||||
const { root, redirects } = redirectsOf(g.values);
|
||||
return {
|
||||
clientId: g.as,
|
||||
name: g.as,
|
||||
description: `made by the mesh for ${g.consumer ? `a module on ${g.consumer}` : "a consumer"} — do not edit; it is reset`,
|
||||
enabled: true,
|
||||
protocol: "openid-connect",
|
||||
publicClient: false,
|
||||
clientAuthenticatorType: "client-secret",
|
||||
secret: g.password,
|
||||
rootUrl: root,
|
||||
baseUrl: root,
|
||||
redirectUris: redirects,
|
||||
standardFlowEnabled: true,
|
||||
implicitFlowEnabled: false,
|
||||
directAccessGrantsEnabled: false,
|
||||
serviceAccountsEnabled: false,
|
||||
};
|
||||
}
|
||||
|
||||
function sameSet(a: readonly string[] | undefined, b: readonly string[]): boolean {
|
||||
const x = [...(a ?? [])].sort();
|
||||
const y = [...b].sort();
|
||||
return x.length === y.length && x.every((v, i) => v === y[i]);
|
||||
}
|
||||
|
||||
function marked(c: ClientRepresentation): boolean {
|
||||
return c.attributes?.[MARK] === "true";
|
||||
}
|
||||
|
||||
export class OidcClients {
|
||||
constructor(private readonly kc: KeycloakClient, readonly realm: string) {}
|
||||
|
||||
/** Create the consumer's client, or bring the mesh's existing one back to what the grant says.
|
||||
* Returns whether it was newly created. Idempotent: applying the same grant twice changes nothing
|
||||
* the second time beyond re-asserting it. */
|
||||
async ensure(g: OidcGrant): Promise<"created" | "updated"> {
|
||||
const want = wanted(g);
|
||||
const found = await this.kc.findClient(this.realm, g.as);
|
||||
if (found && !marked(found)) {
|
||||
throw new Error(
|
||||
`realm ${this.realm} already has a client ${g.as} the mesh did not make — left alone; ` +
|
||||
`delete or rename it if the mesh should own that id`);
|
||||
}
|
||||
if (!found) {
|
||||
await this.kc.createClientFrom(this.realm, {
|
||||
...want,
|
||||
attributes: { [MARK]: "true" },
|
||||
protocolMappers: [ROLES_MAPPER],
|
||||
});
|
||||
return "created";
|
||||
}
|
||||
// Overlay what the mesh owns on what is there, so a field Keycloak added or an operator set on a
|
||||
// field the mesh does not own survives the update.
|
||||
await this.kc.updateClient(this.realm, found.id!, {
|
||||
...found,
|
||||
...want,
|
||||
attributes: { ...(found.attributes ?? {}), [MARK]: "true" },
|
||||
});
|
||||
await this.ensureMapper(found.id!);
|
||||
return "updated";
|
||||
}
|
||||
|
||||
private async ensureMapper(id: string): Promise<void> {
|
||||
const mappers = await this.kc.listClientMappers(this.realm, id);
|
||||
const have = mappers.find((m) => m.name === ROLES_MAPPER.name);
|
||||
if (!have) {
|
||||
await this.kc.addClientMapper(this.realm, id, ROLES_MAPPER);
|
||||
return;
|
||||
}
|
||||
const drifted =
|
||||
have.protocolMapper !== ROLES_MAPPER.protocolMapper ||
|
||||
Object.entries(ROLES_MAPPER.config).some(([k, v]) => have.config?.[k] !== v);
|
||||
if (drifted) {
|
||||
await this.kc.updateClientMapper(this.realm, id, { ...ROLES_MAPPER, id: have.id });
|
||||
}
|
||||
}
|
||||
|
||||
/** Whether Keycloak still holds this consumer's client exactly as the grant says: present, the
|
||||
* mesh's, enabled, confidential, with the mesh's secret and the redirects asked for. Reads only. */
|
||||
async holds(g: OidcGrant): Promise<boolean> {
|
||||
const want = wanted(g);
|
||||
const found = await this.kc.findClient(this.realm, g.as);
|
||||
if (!found || !marked(found) || found.enabled === false || found.publicClient) return false;
|
||||
if (!sameSet(found.redirectUris, want.redirectUris!)) return false;
|
||||
const mappers = await this.kc.listClientMappers(this.realm, found.id!);
|
||||
if (!mappers.some((m) => m.name === ROLES_MAPPER.name)) return false;
|
||||
return (await this.kc.clientSecretById(this.realm, found.id!)) === g.password;
|
||||
}
|
||||
|
||||
/** Withdraw a consumer's client — only one the mesh made. Returns what happened, for the log. */
|
||||
async remove(as: string): Promise<"removed" | "absent" | "not ours"> {
|
||||
const found = await this.kc.findClient(this.realm, as);
|
||||
if (!found) return "absent";
|
||||
if (!marked(found)) return "not ours";
|
||||
await this.kc.deleteClientById(this.realm, found.id!);
|
||||
return "removed";
|
||||
}
|
||||
}
|
||||
@@ -1,15 +1,11 @@
|
||||
{
|
||||
"name": "@novox/module-keycloak",
|
||||
"version": "0.1.0",
|
||||
"description": "keycloak — identity and access; provides the mesh oidc-client interface. Its admin API client, provisioner, tools and events live here (novox/hq ADR 0039).",
|
||||
"description": "keycloak — identity and access. Its admin API client, tools and events live here (novox/hq ADR 0039).",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
|
||||
"test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
|
||||
},
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.1"
|
||||
"@novox/mesh-sdk": "^0.1.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
|
||||
@@ -1,73 +0,0 @@
|
||||
// keycloak's provisioner — the adapter that makes keycloak a provider of the mesh `oidc-client`
|
||||
// interface. The reconcile loop, the contributions file and reading the mesh's minted secret are the
|
||||
// sdk harness's; this writes only the per-service half: how Keycloak creates, checks and removes a
|
||||
// consumer's client (novox/hq ADR 0039/0040/0048). What a client is, and which ones are the mesh's,
|
||||
// is in ../oidc.ts.
|
||||
//
|
||||
// The `oidc-client` interface: a consumer logs people in through the realm this module serves, as
|
||||
// the confidential client `as` with the secret the mesh minted, and is redirected back to the
|
||||
// callback it contributed under the names the mesh composed for its endpoint. What it is served —
|
||||
// the issuer and the endpoint paths under it — is in the manifest's `serves`, settled with the
|
||||
// assignment's settings.
|
||||
//
|
||||
// **The realm is read out of the issuer**, the one value an assignment sets (settings reach both the
|
||||
// served facts and this module's config.json): a realm set in one place and an issuer in another
|
||||
// would let the consumer be told one realm while its client is made in another.
|
||||
|
||||
import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
|
||||
import { emit } from "@novox/mesh-sdk/events";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { KeycloakClient } from "../client.js";
|
||||
import { OidcClients, realmOf } from "../oidc.js";
|
||||
|
||||
/** The issuer this assignment serves, from the settings-merged config the mesh delivers. */
|
||||
function issuer(): string {
|
||||
const file = process.env.MESH_KEYCLOAK_CONFIG_FILE;
|
||||
let cfg: Record<string, unknown> = {};
|
||||
if (file) {
|
||||
try {
|
||||
cfg = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
|
||||
} catch {
|
||||
// Absent or unreadable: fall through to the environment, and refuse below if that is empty too.
|
||||
}
|
||||
}
|
||||
const said = typeof cfg.issuer === "string" ? cfg.issuer : process.env.MESH_KEYCLOAK_ISSUER;
|
||||
if (!said) throw new Error("no issuer — the module's config.json carries none and MESH_KEYCLOAK_ISSUER is unset");
|
||||
return said;
|
||||
}
|
||||
|
||||
const clients = new OidcClients(KeycloakClient.fromEnv(), realmOf(issuer()));
|
||||
|
||||
/** Emit a lifecycle event without letting a broker hiccup fail the provisioning itself. */
|
||||
async function announce(type: string, body: Record<string, string>): Promise<void> {
|
||||
try {
|
||||
await emit(type, body);
|
||||
} catch (err) {
|
||||
console.error(`[provisioner:oidc-client] emit ${type} failed: ${err}`);
|
||||
}
|
||||
}
|
||||
|
||||
runProvisioner("oidc-client", {
|
||||
async create(p: Provision): Promise<void> {
|
||||
const done = await clients.ensure(p);
|
||||
if (done === "created") {
|
||||
console.log(`[provisioner:oidc-client] created client ${p.as} in realm ${clients.realm}`);
|
||||
await announce("client.created", { realm: clients.realm, clientId: p.as, consumer: p.consumer ?? "" });
|
||||
}
|
||||
},
|
||||
|
||||
async remove(p: { as: string }): Promise<void> {
|
||||
const done = await clients.remove(p.as);
|
||||
if (done === "not ours") {
|
||||
console.error(`[provisioner:oidc-client] ${p.as}: a client of that id exists that the mesh did not make — left alone`);
|
||||
} else if (done === "removed") {
|
||||
console.log(`[provisioner:oidc-client] removed client ${p.as} from realm ${clients.realm}`);
|
||||
}
|
||||
},
|
||||
|
||||
// Asked every minute by the harness: whether Keycloak still holds this consumer's client exactly as
|
||||
// the mesh gave it, so a client deleted or edited behind the mesh's back is made again (hq issue 120).
|
||||
async holds(p: Provision): Promise<boolean> {
|
||||
return clients.holds(p);
|
||||
},
|
||||
});
|
||||
@@ -1,239 +0,0 @@
|
||||
// What holds keycloak to the `oidc-client` provision (oidc.ts): one confidential client per consumer,
|
||||
// under the id and secret the mesh gave, redirecting only to the consumer's own callback under the
|
||||
// names the mesh composed; made once and brought back on every apply; and a client the mesh did not
|
||||
// make — same id or not — never adopted, changed or deleted.
|
||||
//
|
||||
// Keycloak is a fake: the admin routes the module touches, answering with the status codes and the
|
||||
// shapes Keycloak gives. Run against the compiled module (npm test builds first), the way the runtime
|
||||
// loads it.
|
||||
|
||||
import { test, after } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
|
||||
import { randomUUID } from "node:crypto";
|
||||
|
||||
import { KeycloakClient } from "../dist/client.js";
|
||||
import { MARK, OidcClients, ROLES_MAPPER, realmOf, redirectsOf } from "../dist/oidc.js";
|
||||
|
||||
type Client = Record<string, any>;
|
||||
|
||||
/** The realm's clients, by internal id, and what the fake was asked. */
|
||||
const realm = "Novox";
|
||||
const clients = new Map<string, Client>();
|
||||
const calls: string[] = [];
|
||||
|
||||
function body(req: IncomingMessage): Promise<any> {
|
||||
return new Promise((resolve) => {
|
||||
let raw = "";
|
||||
req.on("data", (c) => (raw += c));
|
||||
req.on("end", () => resolve(raw ? JSON.parse(raw) : undefined));
|
||||
});
|
||||
}
|
||||
|
||||
function send(res: ServerResponse, status: number, value?: unknown): void {
|
||||
res.writeHead(status, { "Content-Type": "application/json" });
|
||||
res.end(value === undefined ? "" : JSON.stringify(value));
|
||||
}
|
||||
|
||||
const server = createServer(async (req, res) => {
|
||||
const url = new URL(req.url!, "http://fake");
|
||||
calls.push(`${req.method} ${url.pathname}`);
|
||||
if (url.pathname === "/realms/master/protocol/openid-connect/token") {
|
||||
return send(res, 200, { access_token: "t", expires_in: 300 });
|
||||
}
|
||||
const base = `/admin/realms/${realm}/clients`;
|
||||
if (!url.pathname.startsWith(base)) return send(res, 404, { error: "Realm not found." });
|
||||
const rest = url.pathname.slice(base.length).split("/").filter(Boolean);
|
||||
if (rest.length === 0 && req.method === "GET") {
|
||||
const want = url.searchParams.get("clientId");
|
||||
return send(res, 200, [...clients.values()].filter((c) => !want || c.clientId === want));
|
||||
}
|
||||
if (rest.length === 0 && req.method === "POST") {
|
||||
const rep = await body(req);
|
||||
if ([...clients.values()].some((c) => c.clientId === rep.clientId)) {
|
||||
return send(res, 409, { errorMessage: `Client ${rep.clientId} already exists` });
|
||||
}
|
||||
const id = randomUUID();
|
||||
const mappers = (rep.protocolMappers ?? []).map((m: Client) => ({ ...m, id: randomUUID() }));
|
||||
clients.set(id, { ...rep, id, protocolMappers: mappers });
|
||||
return send(res, 201);
|
||||
}
|
||||
const c = clients.get(rest[0]);
|
||||
if (!c) return send(res, 404, { error: "Could not find client" });
|
||||
if (rest.length === 1 && req.method === "PUT") {
|
||||
// Keycloak ignores protocolMappers on a client update: they have their own endpoints.
|
||||
const rep = await body(req);
|
||||
clients.set(c.id, { ...rep, id: c.id, protocolMappers: c.protocolMappers });
|
||||
return send(res, 204);
|
||||
}
|
||||
if (rest.length === 1 && req.method === "DELETE") {
|
||||
clients.delete(c.id);
|
||||
return send(res, 204);
|
||||
}
|
||||
if (rest[1] === "client-secret" && req.method === "GET") {
|
||||
return send(res, 200, { type: "secret", value: c.secret });
|
||||
}
|
||||
if (rest[1] === "protocol-mappers") {
|
||||
if (req.method === "GET") return send(res, 200, c.protocolMappers ?? []);
|
||||
if (req.method === "POST") {
|
||||
c.protocolMappers = [...(c.protocolMappers ?? []), { ...(await body(req)), id: randomUUID() }];
|
||||
return send(res, 201);
|
||||
}
|
||||
if (req.method === "PUT") {
|
||||
const m = await body(req);
|
||||
c.protocolMappers = c.protocolMappers.map((x: Client) => (x.id === rest[4] ? m : x));
|
||||
return send(res, 204);
|
||||
}
|
||||
}
|
||||
send(res, 405);
|
||||
});
|
||||
await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
|
||||
after(() => server.close());
|
||||
const port = (server.address() as { port: number }).port;
|
||||
|
||||
const oidc = new OidcClients(new KeycloakClient(`http://127.0.0.1:${port}`, "admin", "pw"), realm);
|
||||
|
||||
/** Grafana on ace, as the mesh hands it to the provisioner. */
|
||||
function grafana(secret = "s3cret", values: Record<string, unknown> = {}) {
|
||||
return {
|
||||
as: "mesh_ace_grafana",
|
||||
password: secret,
|
||||
consumer: "ace",
|
||||
values: {
|
||||
label: "grafana", endpoint: "web", port: 20010, callback: "/login/generic_oauth",
|
||||
name: "grafana.zurag.be", "internal-name": "grafana.ace.internal", ...values,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function only(clientId: string): Client {
|
||||
const found = [...clients.values()].filter((c) => c.clientId === clientId);
|
||||
assert.equal(found.length, 1, `exactly one client ${clientId}, found ${found.length}`);
|
||||
return found[0];
|
||||
}
|
||||
|
||||
test("the realm is read out of the issuer, and an issuer that names none is refused", () => {
|
||||
assert.equal(realmOf("https://keycloak.novox.be/realms/Novox"), "Novox");
|
||||
assert.equal(realmOf("https://keycloak.novox.be/realms/Novox/"), "Novox");
|
||||
assert.equal(realmOf("http://127.0.0.1:18500/realms/master"), "master");
|
||||
assert.throws(() => realmOf("https://keycloak.novox.be"), /realms/);
|
||||
assert.throws(() => realmOf("keycloak"), /not a URL/);
|
||||
});
|
||||
|
||||
test("the redirect is the consumer's callback under every name the mesh composed for it", () => {
|
||||
assert.deepEqual(redirectsOf(grafana().values), {
|
||||
root: "https://grafana.zurag.be",
|
||||
redirects: ["https://grafana.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"],
|
||||
});
|
||||
// A route reaching only the private network has only the internal name, and that is enough.
|
||||
assert.deepEqual(redirectsOf({ callback: "/cb", "internal-name": "x.ace.internal" }).redirects,
|
||||
["https://x.ace.internal/cb"]);
|
||||
assert.throws(() => redirectsOf({ name: "grafana.zurag.be" }), /callback/);
|
||||
assert.throws(() => redirectsOf({ name: "grafana.zurag.be", callback: "login" }), /callback/);
|
||||
assert.throws(() => redirectsOf({ callback: "/cb" }), /label/);
|
||||
});
|
||||
|
||||
test("a consumer is given one confidential client, under its id and the mesh's secret", async () => {
|
||||
clients.clear();
|
||||
assert.equal(await oidc.ensure(grafana()), "created");
|
||||
const c = only("mesh_ace_grafana");
|
||||
assert.equal(c.publicClient, false);
|
||||
assert.equal(c.clientAuthenticatorType, "client-secret");
|
||||
assert.equal(c.secret, "s3cret");
|
||||
assert.equal(c.enabled, true);
|
||||
assert.equal(c.standardFlowEnabled, true);
|
||||
assert.equal(c.directAccessGrantsEnabled, false);
|
||||
assert.equal(c.implicitFlowEnabled, false);
|
||||
assert.deepEqual(c.redirectUris, [
|
||||
"https://grafana.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"]);
|
||||
assert.equal(c.attributes[MARK], "true");
|
||||
assert.deepEqual(c.protocolMappers.map((m: Client) => m.name), [ROLES_MAPPER.name]);
|
||||
assert.equal(await oidc.holds(grafana()), true);
|
||||
});
|
||||
|
||||
test("applying the same grant again makes no second client", async () => {
|
||||
clients.clear();
|
||||
await oidc.ensure(grafana());
|
||||
assert.equal(await oidc.ensure(grafana()), "updated");
|
||||
assert.equal(await oidc.ensure(grafana()), "updated");
|
||||
only("mesh_ace_grafana");
|
||||
assert.equal(only("mesh_ace_grafana").protocolMappers.length, 1, "the roles mapper is not added twice");
|
||||
});
|
||||
|
||||
test("a new secret or a moved name is applied in place, and what the mesh does not own survives", async () => {
|
||||
clients.clear();
|
||||
await oidc.ensure(grafana());
|
||||
const id = only("mesh_ace_grafana").id;
|
||||
// Something the mesh does not own, set on the client after it was made.
|
||||
clients.get(id)!.consentRequired = true;
|
||||
clients.get(id)!.attributes["post.logout.redirect.uris"] = "+";
|
||||
|
||||
assert.equal(await oidc.holds(grafana("rotated")), false, "a rotated secret is not held until applied");
|
||||
await oidc.ensure(grafana("rotated", { name: "dash.zurag.be" }));
|
||||
const c = only("mesh_ace_grafana");
|
||||
assert.equal(c.id, id, "updated, not replaced");
|
||||
assert.equal(c.secret, "rotated");
|
||||
assert.deepEqual(c.redirectUris, [
|
||||
"https://dash.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"]);
|
||||
assert.equal(c.rootUrl, "https://dash.zurag.be");
|
||||
assert.equal(c.consentRequired, true);
|
||||
assert.equal(c.attributes["post.logout.redirect.uris"], "+");
|
||||
assert.equal(c.attributes[MARK], "true");
|
||||
assert.equal(await oidc.holds(grafana("rotated", { name: "dash.zurag.be" })), true);
|
||||
});
|
||||
|
||||
test("a client lost or edited behind the mesh's back is not held, and is made whole again", async () => {
|
||||
clients.clear();
|
||||
await oidc.ensure(grafana());
|
||||
const c = only("mesh_ace_grafana");
|
||||
c.redirectUris = ["*"];
|
||||
assert.equal(await oidc.holds(grafana()), false, "a widened redirect is not what the mesh gave");
|
||||
await oidc.ensure(grafana());
|
||||
assert.equal(await oidc.holds(grafana()), true);
|
||||
|
||||
only("mesh_ace_grafana").protocolMappers = [];
|
||||
assert.equal(await oidc.holds(grafana()), false, "a client without its roles mapper is not held");
|
||||
await oidc.ensure(grafana());
|
||||
assert.equal(await oidc.holds(grafana()), true);
|
||||
|
||||
clients.clear();
|
||||
assert.equal(await oidc.holds(grafana()), false);
|
||||
});
|
||||
|
||||
test("a client of the same id the mesh did not make is refused, and left exactly as it was", async () => {
|
||||
clients.clear();
|
||||
clients.set("theirs", { id: "theirs", clientId: "mesh_ace_grafana", secret: "their-secret", redirectUris: ["*"] });
|
||||
const before = JSON.stringify(clients.get("theirs"));
|
||||
const writes = calls.length;
|
||||
await assert.rejects(oidc.ensure(grafana()), /did not make/);
|
||||
assert.equal(JSON.stringify(clients.get("theirs")), before);
|
||||
assert.ok(calls.slice(writes).every((c) => c.startsWith("GET") || c.startsWith("POST /realms/master")),
|
||||
`only reads were made: ${calls.slice(writes).join(", ")}`);
|
||||
assert.equal(await oidc.holds(grafana()), false);
|
||||
assert.equal(await oidc.remove("mesh_ace_grafana"), "not ours");
|
||||
assert.ok(clients.has("theirs"), "a client the mesh did not make is never deleted");
|
||||
});
|
||||
|
||||
test("the predecessor's hand-made client is never touched: the mesh's has its own id", async () => {
|
||||
clients.clear();
|
||||
clients.set("hal", { id: "hal", clientId: "grafana", secret: "old", redirectUris: ["https://grafana.zurag.be/*"] });
|
||||
await oidc.ensure(grafana());
|
||||
assert.equal(clients.get("hal")!.secret, "old");
|
||||
only("mesh_ace_grafana");
|
||||
assert.equal(await oidc.remove("grafana"), "not ours");
|
||||
assert.ok(clients.has("hal"));
|
||||
});
|
||||
|
||||
test("a withdrawn consumer's client is removed, and an absent one is not an error", async () => {
|
||||
clients.clear();
|
||||
await oidc.ensure(grafana());
|
||||
assert.equal(await oidc.remove("mesh_ace_grafana"), "removed");
|
||||
assert.equal([...clients.values()].length, 0);
|
||||
assert.equal(await oidc.remove("mesh_ace_grafana"), "absent");
|
||||
});
|
||||
|
||||
test("a contribution with no callback makes no client at all", async () => {
|
||||
clients.clear();
|
||||
await assert.rejects(oidc.ensure({ ...grafana(), values: { name: "grafana.zurag.be" } }), /callback/);
|
||||
assert.equal(clients.size, 0);
|
||||
});
|
||||
@@ -8,5 +8,5 @@
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["client.ts", "oidc.ts", "index.ts", "provisioner/index.ts", "tools/index.ts"]
|
||||
"include": ["client.ts", "index.ts", "tools/index.ts"]
|
||||
}
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# lab's runtime: the tool runtime, carrying this module's code, and the toolchain the lab's suite
|
||||
# builds the mesh with (novox/hq ADR 0172). It reaches the machine's virtualisation and container
|
||||
# runtime through their sockets, so what it raises is what a hand run on this machine raises.
|
||||
#
|
||||
# Every download is pinned by its checksum: an image that builds the mesh is the last place to take
|
||||
# whatever an upstream serves today.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/lab
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc tools/index.ts tools/runs.ts --rootDir . \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends git make ca-certificates curl python3 file iproute2 sudo \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
RUN curl -fsSL -o /tmp/go.tgz https://go.dev/dl/go1.26.8.linux-amd64.tar.gz \
|
||||
&& echo "d0f743b33e8d8945e6b1f432edd15785c70507121d6e2a723b21285eddf8b57b /tmp/go.tgz" | sha256sum -c - \
|
||||
&& tar -C /usr/local -xzf /tmp/go.tgz && rm /tmp/go.tgz
|
||||
RUN curl -fsSL -o /usr/local/bin/incus https://github.com/lxc/incus/releases/download/v7.5.1/bin.linux.incus.x86_64 \
|
||||
&& echo "7bd6223b369f4d693fcde695bd8549a73b5b3d403735329212483702aa22c179 /usr/local/bin/incus" | sha256sum -c - \
|
||||
&& chmod 0755 /usr/local/bin/incus
|
||||
RUN curl -fsSL -o /tmp/docker.tgz https://download.docker.com/linux/static/stable/x86_64/docker-28.5.2.tgz \
|
||||
&& echo "ea90cfd12e1eeb12aa1c971741adb8bd4ed88e2a574eaac13f5029a1dbc6300d /tmp/docker.tgz" | sha256sum -c - \
|
||||
&& tar -C /tmp -xzf /tmp/docker.tgz docker/docker && mv /tmp/docker/docker /usr/local/bin/docker && rm -rf /tmp/docker /tmp/docker.tgz
|
||||
ENV PATH=/usr/local/go/bin:$PATH
|
||||
COPY --from=build /app/modules/lab/dist /app/modules/lab/dist
|
||||
ENV MESH_TOOL_MODULES=/app/modules/lab/dist/tools/index.js
|
||||
@@ -1,82 +0,0 @@
|
||||
{
|
||||
"module": "lab",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"container-runtime",
|
||||
"virtualisation"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
},
|
||||
{
|
||||
"id": "work",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh-lab-runs",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "runtime-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/lab.env",
|
||||
"mode": "0600",
|
||||
"content": "MESH_LAB_FORGE=${setting:forge}\n"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-lab",
|
||||
"network": "host",
|
||||
"env-file": [
|
||||
"${dir:state}/lab.env"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:work}:${dir:work}",
|
||||
"/var/run/docker.sock:/var/run/docker.sock",
|
||||
"/var/lib/incus/unix.socket:/var/lib/incus/unix.socket"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_LAB_WORK": "${dir:work}"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-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,9 +0,0 @@
|
||||
{
|
||||
"name": "@novox/module-lab",
|
||||
"version": "0.1.0",
|
||||
"description": "lab — the lab, as a module: runs beds against the forge's branches when the mesh asks (novox/hq ADR 0172).",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"dependencies": { "@novox/mesh-sdk": "^0.1.0" },
|
||||
"devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" }
|
||||
}
|
||||
@@ -1,86 +0,0 @@
|
||||
// lab's tools — the lab, as the mesh asks for it (novox/hq ADR 0172). They run on the machine the
|
||||
// lab is assigned to, and only there: a bed raises virtual machines on that machine's virtualisation.
|
||||
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { listRuns, readStatus, REPOSITORIES, running, start, stop, tail } from "./runs.js";
|
||||
|
||||
export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
|
||||
const work = env.MESH_LAB_WORK ?? "/var/lib/mesh-lab-runs";
|
||||
const forge = (env.MESH_LAB_FORGE ?? "").replace(/\/+$/, "");
|
||||
return [
|
||||
{
|
||||
name: "lab_check",
|
||||
description: "Whether this machine can run the lab's beds: the lab's own check, against the forge's main branch.",
|
||||
input: {},
|
||||
run: async () => {
|
||||
if (!forge) return { ok: false, output: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
|
||||
const dir = `${work}/check`;
|
||||
spawnSync("rm", ["-rf", dir]);
|
||||
const clone = spawnSync("git", ["clone", "--quiet", "--depth", "1", `${forge}/novox/mesh-lab.git`, dir], { encoding: "utf8" });
|
||||
if (clone.status !== 0) return { ok: false, output: clone.stderr };
|
||||
spawnSync("npm", ["ci", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir, encoding: "utf8" });
|
||||
const check = spawnSync("node", ["--experimental-strip-types", "src/cli.ts", "check"], { cwd: dir, encoding: "utf8" });
|
||||
return { ok: check.status === 0, output: `${check.stdout}${check.stderr}`.trim() };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "lab_run",
|
||||
description:
|
||||
"Run the lab's beds against branches on the forge: fresh checkouts of every repository the lab builds, " +
|
||||
"side by side, then the suite on the named test files. Answers at once with the run's id; lab_status " +
|
||||
"and lab_log follow it. One run at a time.",
|
||||
input: {
|
||||
tests: { type: "string", description: "the bed test files, comma-separated, relative to mesh-lab (e.g. test/integration/mesh.test.ts)" },
|
||||
refs: {
|
||||
type: "string",
|
||||
description: `a JSON object of repository to branch, for any of ${REPOSITORIES.join(", ")}; the rest run main`,
|
||||
},
|
||||
},
|
||||
run: async (args) => {
|
||||
if (!forge) return { started: false, reason: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
|
||||
const tests = String(args.tests ?? "").split(",").map((s) => s.trim()).filter(Boolean);
|
||||
if (tests.length === 0) return { started: false, reason: "name at least one bed test file" };
|
||||
let refs: Record<string, string> = {};
|
||||
if (args.refs) {
|
||||
try {
|
||||
refs = JSON.parse(String(args.refs)) as Record<string, string>;
|
||||
} catch {
|
||||
return { started: false, reason: "refs is not a JSON object of repository to branch" };
|
||||
}
|
||||
}
|
||||
const stranger = Object.keys(refs).filter((r) => !REPOSITORIES.includes(r));
|
||||
if (stranger.length > 0) return { started: false, reason: `the lab does not build ${stranger.join(", ")}` };
|
||||
const busy = running(work);
|
||||
if (busy) return { started: false, reason: `${busy.id} is still ${busy.state}; one run at a time`, running: busy };
|
||||
return { started: true, run: start(work, forge, tests, refs) };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "lab_status",
|
||||
description: "A run's state, the commits it tested and how it ended — or every run, newest first, when no id is given.",
|
||||
input: { id: { type: "string", description: "the run's id (optional)" } },
|
||||
run: async (args) => {
|
||||
if (args.id) return readStatus(work, String(args.id)) ?? { found: false, id: String(args.id) };
|
||||
return { runs: listRuns(work).slice(0, 10) };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "lab_log",
|
||||
description: "The last lines of a run's log.",
|
||||
input: {
|
||||
id: { type: "string", description: "the run's id" },
|
||||
lines: { type: "number", description: "how many lines from the end (default 200)" },
|
||||
},
|
||||
run: async (args) => ({ id: String(args.id), log: tail(work, String(args.id), Number(args.lines ?? 200)) }),
|
||||
},
|
||||
{
|
||||
name: "lab_stop",
|
||||
description: "Stop a run and everything it started.",
|
||||
input: { id: { type: "string", description: "the run's id" } },
|
||||
run: async (args) => stop(work, String(args.id)) ?? { found: false, id: String(args.id) },
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
registerModuleTools("lab", (env) => getLabTools(env));
|
||||
@@ -1,175 +0,0 @@
|
||||
// A lab run: fresh checkouts of the named branches, side by side, then the lab's suite on the named
|
||||
// beds (novox/hq ADR 0172).
|
||||
//
|
||||
// **A run is a detached script with its own process group**, so it outlives the tool call that started
|
||||
// it and `stop` ends everything it started. It writes what it is doing to a status file beside its log,
|
||||
// and that file is the whole of what the tools read back: a runtime that restarts mid-run still answers
|
||||
// for it, and says it was lost rather than pretending it is still going.
|
||||
|
||||
import { spawn } from "node:child_process";
|
||||
import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
/** The repositories a lab run checks out, side by side, as the lab expects its siblings. */
|
||||
export const REPOSITORIES = ["mesh-lab", "mesh-controller", "mesh-host", "mesh-catalog", "mesh-tools", "mesh-sdk"];
|
||||
|
||||
export interface RunStatus {
|
||||
id: string;
|
||||
state: "checking-out" | "building" | "running" | "passed" | "failed" | "stopped" | "lost";
|
||||
started: string;
|
||||
ended?: string;
|
||||
tests: string[];
|
||||
refs: Record<string, string>;
|
||||
commits?: Record<string, string>;
|
||||
exit?: number;
|
||||
pid?: number;
|
||||
}
|
||||
|
||||
export function runDir(work: string, id: string): string {
|
||||
return join(work, id);
|
||||
}
|
||||
|
||||
function statusPath(work: string, id: string): string {
|
||||
return join(runDir(work, id), "status.json");
|
||||
}
|
||||
|
||||
export function readStatus(work: string, id: string): RunStatus | undefined {
|
||||
try {
|
||||
const s = JSON.parse(readFileSync(statusPath(work, id), "utf8")) as RunStatus;
|
||||
// A run whose process is gone while its status still says it is going was lost — the runtime or
|
||||
// the machine restarted under it. Said, rather than left reading as running for ever.
|
||||
if (!["passed", "failed", "stopped", "lost"].includes(s.state) && s.pid && !alive(s.pid)) {
|
||||
s.state = "lost";
|
||||
}
|
||||
return s;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function alive(pid: number): boolean {
|
||||
try {
|
||||
process.kill(pid, 0);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function listRuns(work: string): RunStatus[] {
|
||||
if (!existsSync(work)) return [];
|
||||
return readdirSync(work)
|
||||
.filter((d) => d.startsWith("run-"))
|
||||
.map((id) => readStatus(work, id))
|
||||
.filter((s): s is RunStatus => !!s)
|
||||
.sort((a, b) => b.started.localeCompare(a.started));
|
||||
}
|
||||
|
||||
/** The run still going, if any: one at a time, because two would contend for the same machine. */
|
||||
export function running(work: string): RunStatus | undefined {
|
||||
return listRuns(work).find((s) => !["passed", "failed", "stopped", "lost"].includes(s.state));
|
||||
}
|
||||
|
||||
const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;
|
||||
|
||||
/**
|
||||
* The script one run executes. Every step writes its state first, so a run that dies says where.
|
||||
*
|
||||
* The environment is the one the lab's README describes for a run against sibling checkouts, pointed
|
||||
* at this run's own tree, so what is built and claimed is exactly what was checked out.
|
||||
*/
|
||||
export function script(work: string, id: string, forge: string, tests: string[], refs: Record<string, string>): string {
|
||||
const dir = runDir(work, id);
|
||||
const setState = (state: string) =>
|
||||
`node -e ${shellQuote(
|
||||
`const f=${JSON.stringify(join(dir, "status.json"))};const s=JSON.parse(require("fs").readFileSync(f,"utf8"));s.state=${JSON.stringify(state)};require("fs").writeFileSync(f,JSON.stringify(s,null,2))`,
|
||||
)}`;
|
||||
const clones = REPOSITORIES.map((repo) => {
|
||||
const ref = refs[repo] ?? "main";
|
||||
return [
|
||||
`git clone --quiet --depth 50 --branch ${shellQuote(ref)} ${shellQuote(`${forge}/novox/${repo}.git`)} ${shellQuote(join(dir, repo))}`,
|
||||
`echo "${repo} $(git -C ${shellQuote(join(dir, repo))} rev-parse HEAD)" >> ${shellQuote(join(dir, "commits.txt"))}`,
|
||||
].join("\n");
|
||||
}).join("\n");
|
||||
const bin = join(dir, "bin");
|
||||
return `set -euo pipefail
|
||||
cd ${shellQuote(dir)}
|
||||
${setState("checking-out")}
|
||||
${clones}
|
||||
node -e ${shellQuote(
|
||||
`const fs=require("fs");const f=${JSON.stringify(join(dir, "status.json"))};const s=JSON.parse(fs.readFileSync(f,"utf8"));s.commits=Object.fromEntries(fs.readFileSync(${JSON.stringify(join(dir, "commits.txt"))},"utf8").trim().split("\\n").map(l=>l.split(" ")));fs.writeFileSync(f,JSON.stringify(s,null,2))`,
|
||||
)}
|
||||
${setState("building")}
|
||||
# The @novox scope resolves from the mesh's own package registry on the forge, as the build machine
|
||||
# resolves it; nothing else is asked of it.
|
||||
printf '%s\n' ${shellQuote(`@novox:registry=${forge}/api/packages/novox/npm/`)} > ${shellQuote(join(dir, ".npmrc"))}
|
||||
export NPM_CONFIG_USERCONFIG=${shellQuote(join(dir, ".npmrc"))}
|
||||
for repo in mesh-sdk mesh-tools mesh-lab; do (cd ${shellQuote(dir)}/$repo && npm ci --no-audit --no-fund --loglevel=error); done
|
||||
(cd ${shellQuote(dir)}/mesh-sdk && npm run build --if-present)
|
||||
(cd ${shellQuote(dir)}/mesh-tools && npm run build --if-present)
|
||||
mkdir -p ${shellQuote(bin)}
|
||||
for p in postgres-provisioner objectstore-provisioner route-proxy; do
|
||||
(cd ${shellQuote(dir)}/mesh-controller && CGO_ENABLED=0 go build -o ${shellQuote(bin)}/$p ./examples/$p)
|
||||
done
|
||||
export MESH_LAB_HOST_BINARY=${shellQuote(join(dir, "mesh-host", "mesh-host"))}
|
||||
export MESH_LAB_BUNDLE=${shellQuote(join(dir, "mesh-host", "examples", "foundation-first-node-nats.lock"))}
|
||||
export MESH_LAB_MODULES=${shellQuote(join(dir, "mesh-controller", "examples", "modules"))}
|
||||
export MESH_LAB_BUILDER=${shellQuote(join(dir, "mesh-controller", "build", "mesh-builder"))}
|
||||
export MESH_LAB_BOOTSTRAP_BINARY=${shellQuote(join(dir, "mesh-host", "mesh-bootstrap"))}
|
||||
export MESH_LAB_CATALOG=${shellQuote(join(dir, "mesh-catalog", "modules"))}
|
||||
export MESH_LAB_PROVISIONER=${shellQuote(join(bin, "postgres-provisioner"))}
|
||||
export MESH_LAB_OBJECTSTORE_PROVISIONER=${shellQuote(join(bin, "objectstore-provisioner"))}
|
||||
export MESH_LAB_ROUTE_PROXY=${shellQuote(join(bin, "route-proxy"))}
|
||||
${setState("running")}
|
||||
cd ${shellQuote(join(dir, "mesh-lab"))}
|
||||
node --experimental-strip-types src/cli.ts suite ${tests.map(shellQuote).join(" ")}
|
||||
`;
|
||||
}
|
||||
|
||||
/** start begins a run and returns at once with its status. */
|
||||
export function start(work: string, forge: string, tests: string[], refs: Record<string, string>): RunStatus {
|
||||
const id = `run-${new Date().toISOString().replace(/[:.]/g, "-")}`;
|
||||
const dir = runDir(work, id);
|
||||
mkdirSync(dir, { recursive: true });
|
||||
const status: RunStatus = { id, state: "checking-out", started: new Date().toISOString(), tests, refs };
|
||||
writeFileSync(statusPath(work, id), JSON.stringify(status, null, 2));
|
||||
writeFileSync(join(dir, "run.sh"), script(work, id, forge, tests, refs), { mode: 0o700 });
|
||||
|
||||
// The wrapper records how the run ended, then removes the checkouts and keeps the log and status: a
|
||||
// run's tree is its own, and the next run starts from fresh ones (novox/hq ADR 0172).
|
||||
const wrapper = `bash ${shellQuote(join(dir, "run.sh"))} > ${shellQuote(join(dir, "run.log"))} 2>&1; code=$?
|
||||
node -e ${shellQuote(
|
||||
`const f=${JSON.stringify(statusPath(work, id))};const s=JSON.parse(require("fs").readFileSync(f,"utf8"));if(s.state!=="stopped"){s.state=process.argv[1]==="0"?"passed":"failed"};s.exit=Number(process.argv[1]);s.ended=new Date().toISOString();require("fs").writeFileSync(f,JSON.stringify(s,null,2))`,
|
||||
)} "$code"
|
||||
cd ${shellQuote(dir)} && rm -rf ${REPOSITORIES.map(shellQuote).join(" ")} bin`;
|
||||
const child = spawn("bash", ["-c", wrapper], { detached: true, stdio: "ignore" });
|
||||
child.unref();
|
||||
status.pid = child.pid;
|
||||
writeFileSync(statusPath(work, id), JSON.stringify(status, null, 2));
|
||||
return status;
|
||||
}
|
||||
|
||||
/** stop ends a run and everything it started, by its process group. */
|
||||
export function stop(work: string, id: string): RunStatus | undefined {
|
||||
const s = readStatus(work, id);
|
||||
if (!s || !s.pid) return s;
|
||||
if (["passed", "failed", "stopped", "lost"].includes(s.state)) return s;
|
||||
s.state = "stopped";
|
||||
writeFileSync(statusPath(work, id), JSON.stringify(s, null, 2));
|
||||
try {
|
||||
process.kill(-s.pid, "SIGTERM");
|
||||
} catch {
|
||||
// Already gone between the read and the kill.
|
||||
}
|
||||
return s;
|
||||
}
|
||||
|
||||
/** tail is the last lines of a run's log. */
|
||||
export function tail(work: string, id: string, lines: number): string {
|
||||
try {
|
||||
const all = readFileSync(join(runDir(work, id), "run.log"), "utf8").split("\n");
|
||||
return all.slice(-Math.max(1, lines)).join("\n");
|
||||
} catch {
|
||||
return "";
|
||||
}
|
||||
}
|
||||
@@ -27,7 +27,7 @@
|
||||
"own-secrets": {
|
||||
"server-password": "${dir:state}/server-password.secret",
|
||||
"openai-api-key": "${dir:state}/openai-api-key.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/letta/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -42,8 +42,8 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/letta",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -80,7 +80,7 @@
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/letta/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{\n \"password\": \"${secret:server-password}\"\n}\n",
|
||||
"merge": "json"
|
||||
@@ -91,8 +91,8 @@
|
||||
"name": "mesh-letta",
|
||||
"network": "letta",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
"/var/lib/mesh/letta/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/letta/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# lidarr'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 in
|
||||
# the base images, published like any other artifact — which 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 (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/lidarr
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/lidarr/dist /app/modules/lidarr/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/lidarr/dist/index.js,/app/modules/lidarr/dist/tools/index.js
|
||||
@@ -0,0 +1,144 @@
|
||||
// The Lidarr API client — lidarr's own code, living in the module (novox/hq ADR 0039). Ported from
|
||||
// the shared hal `arr` client, but self-contained: in nox each Servarr app owns its own copy, so a
|
||||
// change to Lidarr's API rebuilds only lidarr and nothing else. Both this module's tools and its
|
||||
// events entrypoint import it, and nothing outside lidarr does.
|
||||
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
// Lidarr speaks the v1 API (Radarr/Sonarr are v3); its content is the "artist".
|
||||
const API_VERSION = "v1";
|
||||
const CONTENT_ENDPOINT = "artist";
|
||||
const APP_NAME = "Lidarr";
|
||||
|
||||
export interface LidarrQueueItem {
|
||||
/** The queue record id — stable while the item is in the queue, so events can diff on it. */
|
||||
id: number;
|
||||
title: string;
|
||||
status: string;
|
||||
size: string;
|
||||
sizeleft: string;
|
||||
timeleft?: string;
|
||||
}
|
||||
|
||||
export interface LidarrCalendarItem {
|
||||
title: string;
|
||||
date: string;
|
||||
overview?: string;
|
||||
}
|
||||
|
||||
export interface LidarrContentItem {
|
||||
title: string;
|
||||
status?: string;
|
||||
monitored: boolean;
|
||||
}
|
||||
|
||||
export class LidarrClient {
|
||||
readonly baseUrl: string;
|
||||
|
||||
constructor(
|
||||
url: string,
|
||||
private readonly apiKey: string,
|
||||
) {
|
||||
this.baseUrl = url.replace(/\/$/, "");
|
||||
}
|
||||
|
||||
/**
|
||||
* Build from the module's resolved environment. The URL defaults to the server on this node (the
|
||||
* runtime shares its network), and the API key is read from MESH_LIDARR_API_KEY or, failing that,
|
||||
* discovered from the server's own config.xml under MESH_LIDARR_CONFIG_DIR — the same file Lidarr
|
||||
* writes it to, so a running server needs nothing configured by hand. Throws when no key can be
|
||||
* found, so the tools/events simply do not load (the harness treats the throw as "exposes
|
||||
* nothing").
|
||||
*/
|
||||
static fromEnv(env: NodeJS.ProcessEnv = process.env): LidarrClient {
|
||||
const url = env.MESH_LIDARR_URL ?? `http://127.0.0.1:${env.MESH_LIDARR_PORT ?? "8686"}`;
|
||||
const configDir = env.MESH_LIDARR_CONFIG_DIR ?? "/config";
|
||||
const apiKey = env.MESH_LIDARR_API_KEY ?? LidarrClient.detectApiKey(configDir);
|
||||
if (!apiKey) {
|
||||
throw new Error("Lidarr not configured — set MESH_LIDARR_API_KEY or make the config dir readable");
|
||||
}
|
||||
return new LidarrClient(url, apiKey);
|
||||
}
|
||||
|
||||
/** Discover the API key from the server's config.xml, falling back to null. Every Servarr app
|
||||
* writes <ApiKey> into config.xml at the root of its config directory. */
|
||||
static detectApiKey(configDir: string): string | null {
|
||||
const config = join(configDir, "config.xml");
|
||||
if (existsSync(config)) {
|
||||
const match = readFileSync(config, "utf8").match(/<ApiKey>([^<]+)<\/ApiKey>/);
|
||||
if (match) return match[1];
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
private async get(endpoint: string, params?: Record<string, string>): Promise<unknown> {
|
||||
const url = new URL(`${this.baseUrl}/api/${API_VERSION}/${endpoint}`);
|
||||
if (params) {
|
||||
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
|
||||
}
|
||||
const res = await fetch(url.toString(), { headers: { "X-Api-Key": this.apiKey } });
|
||||
if (!res.ok) throw new Error(`${APP_NAME} API /${endpoint}: ${res.status} ${await res.text()}`);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
async getStatus(): Promise<{ appName: string; version: string }> {
|
||||
const data = (await this.get("system/status")) as { appName?: string; version?: string };
|
||||
return { appName: data.appName || APP_NAME, version: data.version ?? "unknown" };
|
||||
}
|
||||
|
||||
async getContent(limit?: number): Promise<LidarrContentItem[]> {
|
||||
const data = await this.get(CONTENT_ENDPOINT);
|
||||
const items: any[] = Array.isArray(data) ? data : ((data as any)?.records ?? []);
|
||||
const mapped = items.map((item) => ({
|
||||
// Lidarr's content is an artist; its display name is artistName, not title.
|
||||
title: item.artistName ?? item.title ?? "Unknown",
|
||||
status: item.status,
|
||||
monitored: item.monitored ?? true,
|
||||
}));
|
||||
return limit ? mapped.slice(0, limit) : mapped;
|
||||
}
|
||||
|
||||
/** Library search is a filter over existing content, not an indexer lookup — same as hal's. */
|
||||
async searchContent(term: string): Promise<LidarrContentItem[]> {
|
||||
const all = await this.getContent();
|
||||
const lower = term.toLowerCase();
|
||||
return all.filter((item) => item.title.toLowerCase().includes(lower));
|
||||
}
|
||||
|
||||
async getQueue(): Promise<{ totalRecords: number; items: LidarrQueueItem[] }> {
|
||||
const data = (await this.get("queue", { pageSize: "50" })) as { totalRecords?: number; records?: any[] };
|
||||
const records = data.records ?? [];
|
||||
return {
|
||||
totalRecords: data.totalRecords ?? records.length,
|
||||
items: records.map((r) => ({
|
||||
id: r.id,
|
||||
title: r.title ?? r.artist?.artistName ?? r.album?.title ?? "Unknown",
|
||||
status: r.status ?? "unknown",
|
||||
size: formatBytes(r.size ?? 0),
|
||||
sizeleft: formatBytes(r.sizeleft ?? 0),
|
||||
timeleft: r.timeleft,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
async getCalendar(days = 7): Promise<LidarrCalendarItem[]> {
|
||||
const start = new Date().toISOString().split("T")[0];
|
||||
const end = new Date(Date.now() + days * 86400000).toISOString().split("T")[0];
|
||||
const data = await this.get("calendar", { start, end });
|
||||
const items: any[] = Array.isArray(data) ? data : [];
|
||||
return items.map((item) => ({
|
||||
// A Lidarr calendar entry is an album release.
|
||||
title: item.title ?? item.artist?.artistName ?? "Unknown",
|
||||
date: item.releaseDate ?? "",
|
||||
overview: item.overview?.slice(0, 150),
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
function formatBytes(bytes: number): string {
|
||||
if (bytes === 0) return "0 B";
|
||||
const units = ["B", "KB", "MB", "GB", "TB"];
|
||||
const i = Math.floor(Math.log(bytes) / Math.log(1024));
|
||||
return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
// lidarr's events. The tool runtime imports this once the broker is bound. It watches the download
|
||||
// queue and turns its comings and goings into mesh events.
|
||||
//
|
||||
// Emits (novox/hq ADR 0041/0042):
|
||||
// module.lidarr.album.grabbed — a release entered the queue (Lidarr grabbed it)
|
||||
// module.lidarr.download.completed — a release left the queue, imported. The download.completed
|
||||
// routing key matches what a media consumer subscribes to
|
||||
// (module.*.download.completed) to rescan its library.
|
||||
// Consumes: none.
|
||||
//
|
||||
// The queue is polled and diffed, primed silently on the first look (like plex's index.ts) so a
|
||||
// restart mid-download does not re-announce everything already in flight as freshly grabbed.
|
||||
|
||||
import { emit } from "@novox/mesh-sdk/events";
|
||||
import { LidarrClient, type LidarrQueueItem } from "./client.js";
|
||||
|
||||
// Building the client throws when Lidarr has no URL/key yet. Like the tools (see tools/index.ts),
|
||||
// the events entrypoint must not crash the runtime for that — it stays idle until configured.
|
||||
function buildClient(): LidarrClient | null {
|
||||
try {
|
||||
return LidarrClient.fromEnv();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
const lidarr = buildClient();
|
||||
|
||||
// Lidarr removes an item from the queue once it has been imported; a "warning"/"failed" status is
|
||||
// how a stuck or broken grab shows itself, so we do not call those a completion when they vanish.
|
||||
const FAILED_STATUSES = new Set(["failed", "warning"]);
|
||||
|
||||
const inQueue = new Map<number, LidarrQueueItem>();
|
||||
let primed = false;
|
||||
|
||||
async function pollQueue(lidarr: LidarrClient): Promise<void> {
|
||||
const { items } = await lidarr.getQueue();
|
||||
const now = new Map(items.map((i) => [i.id, i]));
|
||||
|
||||
if (primed) {
|
||||
// Entered the queue since last look — Lidarr grabbed a release.
|
||||
for (const [id, item] of now) {
|
||||
if (!inQueue.has(id)) await emit("album.grabbed", { title: item.title, status: item.status });
|
||||
}
|
||||
// Left the queue — imported and done, unless it was last seen failing.
|
||||
for (const [id, item] of inQueue) {
|
||||
if (!now.has(id) && !FAILED_STATUSES.has(item.status)) {
|
||||
await emit("download.completed", { title: item.title });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
inQueue.clear();
|
||||
for (const [id, item] of now) inQueue.set(id, item);
|
||||
primed = true;
|
||||
}
|
||||
|
||||
const tick = (fn: () => Promise<void>, everyMs: number): void => {
|
||||
const run = (): void => void fn().catch((err) => console.error(`[lidarr] ${err}`));
|
||||
setInterval(run, everyMs);
|
||||
run();
|
||||
};
|
||||
|
||||
if (lidarr) {
|
||||
tick(() => pollQueue(lidarr), 30_000);
|
||||
console.log("[lidarr] watching the download queue, emitting grabs and completions");
|
||||
} else {
|
||||
console.log("[lidarr] not configured — events idle until an API key is available");
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
{
|
||||
"module": "lidarr",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"emits": [
|
||||
"album.grabbed",
|
||||
"download.completed"
|
||||
],
|
||||
"consumes": [],
|
||||
"own-secrets": {
|
||||
"broker": "/var/lib/mesh/lidarr/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
"name": "web",
|
||||
"port": 8686,
|
||||
"protocol": "tcp",
|
||||
"from": "mesh",
|
||||
"why": "managing music"
|
||||
}
|
||||
],
|
||||
"accesses": [
|
||||
{
|
||||
"path": "/services/media/music",
|
||||
"mode": "read-write"
|
||||
},
|
||||
{
|
||||
"path": "/services/media/downloads",
|
||||
"mode": "read-write"
|
||||
}
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh/lidarr",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "directory",
|
||||
"path": "/services/lidarr/config",
|
||||
"mode": "0700",
|
||||
"owner": "1000:1000"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "lidarr",
|
||||
"image": "lscr.io/linuxserver/lidarr@sha256:6b38dd330b0c653351c2e23c8b962ea51c95683dd7acace9d106c922baf85f75",
|
||||
"env": {
|
||||
"PUID": "1000",
|
||||
"PGID": "1000",
|
||||
"TZ": "Etc/UTC"
|
||||
},
|
||||
"ports": [
|
||||
"8686"
|
||||
],
|
||||
"volumes": [
|
||||
"/services/lidarr/config:/config",
|
||||
"/services/media/music:/music",
|
||||
"/services/media/downloads:/downloads"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-lidarr",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"/var/lib/mesh/lidarr/broker:/run/secrets/broker:ro",
|
||||
"/services/lidarr/config:/var/lib/lidarr/config:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_LIDARR_URL": "http://127.0.0.1:8686",
|
||||
"MESH_LIDARR_CONFIG_DIR": "/var/lib/lidarr/config"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
"route"
|
||||
],
|
||||
"contributes": {
|
||||
"route": {
|
||||
"label": "lidarr",
|
||||
"endpoint": "web"
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"route": "/var/lib/mesh/lidarr/route.json"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "@novox/module-lidarr",
|
||||
"version": "0.1.0",
|
||||
"description": "lidarr — music management. Its API client, tools and events live here (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"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
// lidarr's tools — ported from the shared hal sdk (novox/hq ADR 0039), importing lidarr's own
|
||||
// client. They return structured data (not pre-formatted text as hal did); the mesh serves them
|
||||
// through the sdk's tool harness.
|
||||
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { LidarrClient } from "../client.js";
|
||||
|
||||
export function getLidarrTools(lidarr: LidarrClient): ToolDefinition[] {
|
||||
return [
|
||||
{
|
||||
name: "lidarr_status",
|
||||
description: "Lidarr status overview: version, artist count, monitored count, queue size.",
|
||||
input: {},
|
||||
run: async () => {
|
||||
const [status, content, queue] = await Promise.all([
|
||||
lidarr.getStatus(),
|
||||
lidarr.getContent(),
|
||||
lidarr.getQueue(),
|
||||
]);
|
||||
return {
|
||||
app: status.appName,
|
||||
version: status.version,
|
||||
artists: content.length,
|
||||
monitored: content.filter((c) => c.monitored).length,
|
||||
queue: queue.totalRecords,
|
||||
};
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "lidarr_library",
|
||||
description: "List artists from the Lidarr library.",
|
||||
input: { limit: { type: "number", description: "max items to return (default 50)" } },
|
||||
run: async (args) => {
|
||||
const items = await lidarr.getContent(args.limit ? Number(args.limit) : 50);
|
||||
return { count: items.length, artists: items };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "lidarr_search",
|
||||
description: "Search the Lidarr library for artists by name (filters existing content, not indexers).",
|
||||
input: { query: { type: "string", description: "the search term" } },
|
||||
run: async (args) => {
|
||||
const query = String(args.query);
|
||||
return { query, results: await lidarr.searchContent(query) };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "lidarr_queue",
|
||||
description: "Show the Lidarr download queue — what is downloading and how far along.",
|
||||
input: {},
|
||||
run: async () => {
|
||||
const queue = await lidarr.getQueue();
|
||||
return { count: queue.totalRecords, items: queue.items };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "lidarr_calendar",
|
||||
description: "Upcoming album releases from the Lidarr calendar.",
|
||||
input: { days: { type: "number", description: "how many days to look ahead (default 7)" } },
|
||||
run: async (args) => {
|
||||
const days = args.days ? Number(args.days) : 7;
|
||||
const items = await lidarr.getCalendar(days);
|
||||
items.sort((a, b) => a.date.localeCompare(b.date));
|
||||
return { days, count: items.length, items };
|
||||
},
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
// The tools exist only when Lidarr is configured; without a URL and key, lidarr contributes none
|
||||
// rather than failing the whole runtime.
|
||||
registerModuleTools("lidarr", (env) => {
|
||||
try {
|
||||
return getLidarrTools(LidarrClient.fromEnv(env));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["client.ts", "index.ts", "tools/index.ts"]
|
||||
}
|
||||
@@ -6,24 +6,25 @@
|
||||
"model-access"
|
||||
],
|
||||
"binds": {
|
||||
"model-access": "${dir:state}/model.json"
|
||||
"model-access": "/var/lib/local-model-consumer/model.json"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/local-model-consumer",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/local-model-consumer/config",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "openai-env",
|
||||
"type": "file",
|
||||
"path": "${dir:config}/openai.env",
|
||||
"path": "/var/lib/local-model-consumer/config/openai.env",
|
||||
"mode": "0600",
|
||||
"content": "OPENAI_BASE_URL=http://${bound:model-access:at}:${bound:model-access:port}/v1\nOPENAI_MODEL=${bound:model-access:model}\nOPENAI_API_KEY=local\n"
|
||||
}
|
||||
|
||||
@@ -138,14 +138,14 @@
|
||||
}
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/mailu/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/mailu",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -462,13 +462,12 @@
|
||||
],
|
||||
"dns": [
|
||||
"192.168.203.254"
|
||||
],
|
||||
"logging": "journald"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime-config",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/config.json",
|
||||
"path": "/var/lib/mesh/mailu/config.json",
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
@@ -479,10 +478,10 @@
|
||||
"name": "mesh-mailu",
|
||||
"network": "mailu",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/mailu/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}/api-token.secret:/run/secrets/api-token:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"/var/lib/mesh/mailu/config.json:/run/config/config.json:ro",
|
||||
"/var/run/docker.sock:/var/run/docker.sock"
|
||||
],
|
||||
"env": {
|
||||
@@ -553,8 +552,7 @@
|
||||
],
|
||||
"serves": {
|
||||
"smtp": {
|
||||
"port": 587,
|
||||
"domain": "${setting:domain}"
|
||||
"port": 587
|
||||
}
|
||||
},
|
||||
"receives": {
|
||||
@@ -562,12 +560,5 @@
|
||||
},
|
||||
"grants": {
|
||||
"smtp": "${dir:grants}"
|
||||
},
|
||||
"jails": [
|
||||
{
|
||||
"name": "mailu-front",
|
||||
"failregex": "^.*(?:imap|pop3|submission|managesieve)-login: .*\\(auth failed, \\d+ attempts(?: in \\d+ secs)?\\):.*rip=<HOST>(?:,|$)",
|
||||
"jail": "backend = systemd\njournalmatch = CONTAINER_NAME=mailu-front\nport = smtp,submission,submissions,imap,imaps,pop3,pop3s\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -17,8 +17,8 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/marrytts",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
|
||||
@@ -20,13 +20,13 @@
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"postgres-database": "${dir:state}/database.json"
|
||||
"postgres-database": "/var/lib/mesh-catalog/database.json"
|
||||
},
|
||||
"secrets": {
|
||||
"postgres-database": "${dir:state}/database.secret"
|
||||
"postgres-database": "/var/lib/mesh-catalog/database.secret"
|
||||
},
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/mesh-catalog/broker"
|
||||
},
|
||||
"consumes": [
|
||||
"mesh-build-machine.built",
|
||||
@@ -43,19 +43,19 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/mesh-catalog",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/mesh-catalog",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "database-url",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/database.url",
|
||||
"path": "/var/lib/mesh-catalog/database.url",
|
||||
"mode": "0600",
|
||||
"content": "postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\n"
|
||||
},
|
||||
@@ -65,9 +65,9 @@
|
||||
"name": "mesh-catalog",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}:/run/state",
|
||||
"${dir:state}/database.url:/run/secrets/database-url:ro"
|
||||
"/var/lib/mesh/mesh-catalog/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh-catalog:/run/state",
|
||||
"/var/lib/mesh-catalog/database.url:/run/secrets/database-url:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
"*"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/mesh-console/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -24,8 +24,8 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/mesh-console",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
@@ -40,7 +40,7 @@
|
||||
"MESH_CONSOLE_LISTEN": "127.0.0.1:${port:4270}"
|
||||
},
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
"/var/lib/mesh/mesh-console/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
// mesh-vault's events entrypoint, loaded by the per-node tool host (the provisioner runs in the same
|
||||
// process — ADR 0052). The lifecycle events are EMITTED from the provisioner, where custody
|
||||
// actually changes (novox/hq ADR 0041/0042):
|
||||
// mesh-vault.provisioned — a consumer was granted a secret
|
||||
// mesh-vault.rotated — that consumer's value changed (`rotate secret`)
|
||||
// mesh-vault.deprovisioned — the consumer went away and its secret was withdrawn
|
||||
// module.mesh-vault.secret.provisioned — a consumer was granted a secret
|
||||
// module.mesh-vault.secret.rotated — that consumer's value changed (`rotate secret`)
|
||||
// module.mesh-vault.secret.deprovisioned — the consumer went away and its secret was withdrawn
|
||||
// Here the vault reacts to them, keeping a lightweight audit line of who holds what and when it
|
||||
// moved — the audit an owner of secrets is best placed to log. Fingerprints, never values.
|
||||
|
||||
@@ -16,15 +16,15 @@ interface SecretEvent {
|
||||
rotations?: number;
|
||||
}
|
||||
|
||||
await on<SecretEvent>("provisioned", async (e) => {
|
||||
await on<SecretEvent>("secret.provisioned", async (e) => {
|
||||
console.log(`[mesh-vault] secret provisioned for ${e.body.as} on ${e.body.consumer} (${e.body.fingerprint})`);
|
||||
});
|
||||
|
||||
await on<SecretEvent>("rotated", async (e) => {
|
||||
await on<SecretEvent>("secret.rotated", async (e) => {
|
||||
console.log(`[mesh-vault] secret rotated for ${e.body.as} — rotation ${e.body.rotations} (${e.body.fingerprint})`);
|
||||
});
|
||||
|
||||
await on<SecretEvent>("deprovisioned", async (e) => {
|
||||
await on<SecretEvent>("secret.deprovisioned", async (e) => {
|
||||
console.log(`[mesh-vault] secret withdrawn from ${e.body.as}`);
|
||||
});
|
||||
|
||||
|
||||
@@ -11,51 +11,54 @@
|
||||
"container-runtime"
|
||||
],
|
||||
"emits": [
|
||||
"provisioned",
|
||||
"rotated",
|
||||
"deprovisioned"
|
||||
"secret.provisioned",
|
||||
"secret.rotated",
|
||||
"secret.deprovisioned"
|
||||
],
|
||||
"consumes": [
|
||||
"mesh-vault.provisioned",
|
||||
"mesh-vault.rotated",
|
||||
"mesh-vault.deprovisioned"
|
||||
"mesh-vault.secret.provisioned",
|
||||
"mesh-vault.secret.rotated",
|
||||
"mesh-vault.secret.deprovisioned"
|
||||
],
|
||||
"receives": {
|
||||
"secret": "${dir:grants}/mesh.json"
|
||||
"secret": "/var/lib/mesh-vault/grants/mesh.json"
|
||||
},
|
||||
"grants": {
|
||||
"secret": "${dir:grants}"
|
||||
"secret": "/var/lib/mesh-vault/grants"
|
||||
},
|
||||
"keeps": "/var/lib/mesh-vault/root",
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/mesh-vault/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/mesh-vault",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/mesh-vault",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "grants",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh-vault/grants",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "ledger",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh-vault/ledger",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "root",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/mesh-vault/root",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
@@ -64,16 +67,16 @@
|
||||
"name": "mesh-vault",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:ledger}:${dir:ledger}",
|
||||
"${dir:root}:${dir:root}:ro"
|
||||
"/var/lib/mesh/mesh-vault/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh-vault/grants:/var/lib/mesh-vault/grants:ro",
|
||||
"/var/lib/mesh-vault/ledger:/var/lib/mesh-vault/ledger",
|
||||
"/var/lib/mesh-vault/root:/var/lib/mesh-vault/root:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json",
|
||||
"MESH_VAULT_LEDGER": "${dir:ledger}",
|
||||
"MESH_VAULT_ROOT": "${dir:root}"
|
||||
"MESH_RECEIVES": "/var/lib/mesh-vault/grants/mesh.json",
|
||||
"MESH_VAULT_LEDGER": "/var/lib/mesh-vault/ledger",
|
||||
"MESH_VAULT_ROOT": "/var/lib/mesh-vault/root"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
@@ -98,11 +101,5 @@
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
},
|
||||
"claims": [
|
||||
{
|
||||
"name": "mesh-vault",
|
||||
"scope": "mesh"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -43,6 +43,6 @@ runProvisioner("secret", {
|
||||
async remove(p: { as: string }): Promise<void> {
|
||||
if (!ledger.withdraw(p.as)) return;
|
||||
console.log(`[mesh-vault] withdrawn: ${p.as}`);
|
||||
await announce("deprovisioned", { as: p.as });
|
||||
await announce("secret.deprovisioned", { as: p.as });
|
||||
},
|
||||
});
|
||||
|
||||
+16
-15
@@ -53,37 +53,38 @@
|
||||
}
|
||||
},
|
||||
"receives": {
|
||||
"s3-bucket": "${dir:grants}/mesh.json"
|
||||
"s3-bucket": "/var/lib/minio/grants/mesh.json"
|
||||
},
|
||||
"grants": {
|
||||
"s3-bucket": "${dir:grants}"
|
||||
"s3-bucket": "/var/lib/minio/grants"
|
||||
},
|
||||
"own-secrets": {
|
||||
"root": "${dir:state}/root.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"root": "/var/lib/minio/root.secret",
|
||||
"broker": "/var/lib/mesh/minio/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/minio",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/minio",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "grants",
|
||||
"type": "directory",
|
||||
"path": "/var/lib/minio/grants",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "root-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/root.env",
|
||||
"path": "/var/lib/minio/root.env",
|
||||
"mode": "0600",
|
||||
"content": "MINIO_ROOT_USER=meshroot\nMINIO_BROWSER_REDIRECT_URL=https://${bound:route:name-console}\n"
|
||||
},
|
||||
@@ -111,7 +112,7 @@
|
||||
":9001"
|
||||
],
|
||||
"env-file": [
|
||||
"${dir:state}/root.env"
|
||||
"/var/lib/minio/root.env"
|
||||
],
|
||||
"ports": [
|
||||
"9000",
|
||||
@@ -119,7 +120,7 @@
|
||||
],
|
||||
"volumes": [
|
||||
"/var/lib/minio-store:/data",
|
||||
"${dir:state}/root.secret:/run/secrets/root:ro"
|
||||
"/var/lib/minio/root.secret:/run/secrets/root:ro"
|
||||
],
|
||||
"env": {
|
||||
"MINIO_ROOT_PASSWORD_FILE": "/run/secrets/root",
|
||||
@@ -132,9 +133,9 @@
|
||||
"name": "mesh-minio",
|
||||
"network": "minio-net",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:state}/root.secret:/run/secrets/root:ro"
|
||||
"/var/lib/mesh/minio/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/minio/grants:/var/lib/minio/grants:ro",
|
||||
"/var/lib/minio/root.secret:/run/secrets/root:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_MINIO_ENDPOINT": "http://minio:9000",
|
||||
@@ -142,7 +143,7 @@
|
||||
"MESH_MINIO_ROOT_PASSWORD_FILE": "/run/secrets/root",
|
||||
"MESH_MINIO_REGION": "eu-west",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
"MESH_RECEIVES": "/var/lib/minio/grants/mesh.json"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
|
||||
@@ -14,34 +14,34 @@
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"postgres-database": "${dir:state}/database.json"
|
||||
"postgres-database": "/var/lib/model-usage/database.json"
|
||||
},
|
||||
"secrets": {
|
||||
"postgres-database": "${dir:state}/database.secret"
|
||||
"postgres-database": "/var/lib/model-usage/database.secret"
|
||||
},
|
||||
"consumes": [
|
||||
"*.usage.*"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/model-usage/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/model-usage",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
"path": "/var/lib/model-usage",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "database-url",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/database.url",
|
||||
"path": "/var/lib/model-usage/database.url",
|
||||
"mode": "0600",
|
||||
"content": "postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\n"
|
||||
},
|
||||
@@ -52,9 +52,9 @@
|
||||
"image": "mesh-runtime-model-usage@sha256:0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}:/run/state",
|
||||
"${dir:state}/database.url:/run/secrets/database-url:ro"
|
||||
"/var/lib/mesh/model-usage/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/model-usage:/run/state",
|
||||
"/var/lib/model-usage/database.url:/run/secrets/database-url:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -40,15 +40,15 @@
|
||||
},
|
||||
"own-secrets": {
|
||||
"root": "${dir:state}/root.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"broker": "/var/lib/mesh/mongodb/broker"
|
||||
},
|
||||
"secrets-owner": "999:999",
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/mongodb",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -95,7 +95,7 @@
|
||||
"name": "mesh-mongodb",
|
||||
"network": "mongodb",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/mongodb/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:state}/root.secret:/run/secrets/root:ro"
|
||||
],
|
||||
|
||||
@@ -32,8 +32,8 @@
|
||||
"mqtt-topic": "${dir:grants}"
|
||||
},
|
||||
"own-secrets": {
|
||||
"admin": "${dir:mesh-state}/admin",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
"admin": "/var/lib/mesh/mosquitto/admin",
|
||||
"broker": "/var/lib/mesh/mosquitto/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -55,8 +55,8 @@
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/mosquitto",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -95,7 +95,7 @@
|
||||
"run-once": true,
|
||||
"volumes": [
|
||||
"${dir:data}:/mosquitto/data",
|
||||
"${dir:mesh-state}/admin:/run/secrets/admin:ro"
|
||||
"/var/lib/mesh/mosquitto/admin:/run/secrets/admin:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_PROVISION_MQTT": "mosquitto:1883",
|
||||
@@ -130,9 +130,9 @@
|
||||
"name": "mesh-mosquitto",
|
||||
"network": "mosquitto",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/mosquitto/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:mesh-state}/admin:/run/secrets/admin:ro"
|
||||
"/var/lib/mesh/mosquitto/admin:/run/secrets/admin:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
|
||||
@@ -20,20 +20,7 @@ COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
# **sqlcmd, which this module's client drives, has to be here** — it never was, so every tool failed
|
||||
# with `spawn sqlcmd ENOENT`. go-sqlcmd is one static binary; fetched at a pinned release and checked
|
||||
# against its digest, so a build that receives anything else stops here.
|
||||
FROM ${BUILD_BASE} AS sqlcmd
|
||||
ARG SQLCMD_VERSION=v1.10.0
|
||||
ARG SQLCMD_SHA256=92516d98c63d99b0994de5b61350c91f6915f9b76f139a59039fbcb225c2e987
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates bzip2 \
|
||||
&& curl -fsSL -o /tmp/sqlcmd.tar.bz2 \
|
||||
"https://github.com/microsoft/go-sqlcmd/releases/download/${SQLCMD_VERSION}/sqlcmd-linux-amd64.tar.bz2" \
|
||||
&& echo "${SQLCMD_SHA256} /tmp/sqlcmd.tar.bz2" | sha256sum -c - \
|
||||
&& tar -xjf /tmp/sqlcmd.tar.bz2 -C /usr/local/bin sqlcmd
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=sqlcmd /usr/local/bin/sqlcmd /usr/local/bin/sqlcmd
|
||||
COPY --from=build /app/modules/mssql/dist /app/modules/mssql/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 —
|
||||
|
||||
+10
-107
@@ -29,40 +29,11 @@ export interface MssqlConn {
|
||||
readonly port: number;
|
||||
readonly user: string;
|
||||
readonly password: string;
|
||||
/**
|
||||
* The read-only login's password, which the mesh mints for this module (`own-secrets.reader`).
|
||||
* Absent when the mesh has not delivered it: then a caller's statement is refused, never run as
|
||||
* the administrator (novox/hq issue 193).
|
||||
*/
|
||||
readonly readerPassword?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* The login a caller's statement runs as (novox/hq issue 193). It may connect to every database and
|
||||
* read every table, and holds no other permission. A statement cannot climb out of a login the way it
|
||||
* could out of a transaction wrapped around it as text, and the administrator — who can run programs
|
||||
* on the server — never runs a caller's text.
|
||||
*/
|
||||
export const READER = "mesh_mssql_reader";
|
||||
|
||||
/** Who a sqlcmd invocation logs in as, and whether the text is a caller's rather than the module's. */
|
||||
interface Invocation {
|
||||
readonly user: string;
|
||||
readonly password: string;
|
||||
/**
|
||||
* A caller's text: sqlcmd substitutes no `$(NAME)` in it, which would read this process's
|
||||
* environment — the administrator's password among it. (Its own commands are kept out by the
|
||||
* caller's text never beginning a line; see readOnlyQuery.)
|
||||
*/
|
||||
readonly caller: boolean;
|
||||
}
|
||||
|
||||
export class MssqlClient {
|
||||
constructor(private readonly conn: MssqlConn) {}
|
||||
|
||||
/** The reader is made once per process: idempotent, and repeating it re-sets a rotated password. */
|
||||
private readerReady?: Promise<void>;
|
||||
|
||||
/**
|
||||
* Build from the module's resolved environment. Reads MESH_MSSQL_* first (the documented
|
||||
* names), falling back to the MESH_PROVISION_* keys the manifest already sets on the provisioner
|
||||
@@ -77,9 +48,7 @@ export class MssqlClient {
|
||||
if (!host || !password) {
|
||||
throw new Error("mssql host or admin password is not set — mssql's own code cannot reach the server");
|
||||
}
|
||||
const readerPassword = env.MESH_MSSQL_READER_PASSWORD ??
|
||||
readSecretFile(env.MESH_MSSQL_READER_PASSWORD_FILE);
|
||||
return new MssqlClient({ host, port, user, password, readerPassword });
|
||||
return new MssqlClient({ host, port, user, password });
|
||||
}
|
||||
|
||||
get host(): string {
|
||||
@@ -117,12 +86,7 @@ export class MssqlClient {
|
||||
}
|
||||
|
||||
/** The one execution boundary: invoke `sqlcmd` and return its concatenated stdout. */
|
||||
private async sqlcmd(
|
||||
sql: string,
|
||||
database: string,
|
||||
variables: Record<string, string> = {},
|
||||
as: Invocation = { user: this.conn.user, password: this.conn.password, caller: false },
|
||||
): Promise<string> {
|
||||
private async sqlcmd(sql: string, database: string, variables: Record<string, string> = {}): Promise<string> {
|
||||
// `-h -1` drops the column-header rule; `-y 0`/`-Y 0` lift the display-width cap so a long
|
||||
// JSON document is not truncated; `-W` trims trailing whitespace so the JSON chunks rejoin
|
||||
// cleanly. sqlcmd from the mssql-tools ships in the runtime container, the way `psql` ships
|
||||
@@ -131,9 +95,8 @@ export class MssqlClient {
|
||||
"sqlcmd",
|
||||
[
|
||||
"-S", `${this.conn.host},${this.conn.port}`,
|
||||
"-U", as.user,
|
||||
"-U", this.conn.user,
|
||||
"-d", database,
|
||||
...(as.caller ? ["-x"] : []),
|
||||
"-C",
|
||||
"-b",
|
||||
"-h", "-1",
|
||||
@@ -144,7 +107,7 @@ export class MssqlClient {
|
||||
],
|
||||
// `variables` reach sqlcmd as environment variables, which it substitutes as `$(NAME)` scripting
|
||||
// variables: a value that must not appear on argv, or in the message of a failed command.
|
||||
{ env: { ...process.env, ...variables, SQLCMDPASSWORD: as.password }, maxBuffer: 16 << 20 },
|
||||
{ env: { ...process.env, ...variables, SQLCMDPASSWORD: this.conn.password }, maxBuffer: 16 << 20 },
|
||||
);
|
||||
return stdout;
|
||||
}
|
||||
@@ -262,78 +225,18 @@ export class MssqlClient {
|
||||
}));
|
||||
}
|
||||
|
||||
/**
|
||||
* Make the read-only login, idempotently, with the password the mesh minted for it: it may connect
|
||||
* to every database and read every table, and is taken out of the administrators' role should
|
||||
* anyone have put it there. Run as the administrator, because only it can make a login.
|
||||
*/
|
||||
async ensureReader(): Promise<void> {
|
||||
const password = this.conn.readerPassword;
|
||||
if (!password) throw readerMissing();
|
||||
const logins = await this.query(
|
||||
`SELECT 1 AS ok FROM sys.server_principals WHERE name = ${literal(READER)}`,
|
||||
);
|
||||
if (logins.length === 0) {
|
||||
await this.exec(
|
||||
`CREATE LOGIN ${ident(READER)} WITH PASSWORD = ${literal(password)}, CHECK_POLICY = OFF`,
|
||||
);
|
||||
} else {
|
||||
await this.exec(`ALTER LOGIN ${ident(READER)} WITH PASSWORD = ${literal(password)}`);
|
||||
await this.exec(`ALTER LOGIN ${ident(READER)} ENABLE`);
|
||||
}
|
||||
await this.exec(
|
||||
`IF IS_SRVROLEMEMBER('sysadmin', ${literal(READER)}) = 1 ` +
|
||||
`ALTER SERVER ROLE sysadmin DROP MEMBER ${ident(READER)}`,
|
||||
);
|
||||
await this.exec(`GRANT CONNECT ANY DATABASE TO ${ident(READER)}`);
|
||||
await this.exec(`GRANT SELECT ALL USER SECURABLES TO ${ident(READER)}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a caller's SELECT against a named database as the read-only login, for the mssql_query tool
|
||||
* (novox/hq issue 193). Read-only by the login, not by a transaction wrapped around the text; the
|
||||
* rows are rendered by FOR JSON. Never as the administrator: without the reader's password the call
|
||||
* is refused.
|
||||
*/
|
||||
/** Run a read-only SELECT against a named database, for the mssql_query tool. */
|
||||
async readOnlyQuery(database: string, sql: string): Promise<QueryResult> {
|
||||
const password = this.conn.readerPassword;
|
||||
if (!password) throw readerMissing();
|
||||
// **One line, refused otherwise.** sqlcmd reads a line that BEGINS with `:` or `!!` as its own
|
||||
// command rather than SQL, and `:!!` starts a program in this container, which holds the
|
||||
// administrator's password. Its switch for refusing those (-X) makes it ignore -Q in the
|
||||
// version shipped here, so instead no line of a caller's text can begin one: the text follows
|
||||
// this module's own on the first line, and a line break in it is refused. Proven on a throwaway
|
||||
// server: the same text at the start of a line ran a program; mid-line it is a syntax error.
|
||||
if (/[\r\n]/.test(sql)) {
|
||||
throw new Error(
|
||||
"mssql_query: the statement must be one line — sqlcmd takes a line beginning with ':' or " +
|
||||
"'!!' as a command of its own, which can start a program (novox/hq issue 193)",
|
||||
);
|
||||
}
|
||||
this.readerReady ??= this.ensureReader().catch((err) => {
|
||||
this.readerReady = undefined; // asked again next call, not failed for the process's life
|
||||
throw err;
|
||||
});
|
||||
await this.readerReady;
|
||||
const stdout = await this.sqlcmd(
|
||||
`SET NOCOUNT ON; ${stripTrailingSemis(sql)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`,
|
||||
// The read-only guarantee is a wrapping transaction that is always rolled back: any write the
|
||||
// statement attempts is undone. The rows are rendered by FOR JSON inside query().
|
||||
const rows = await this.query(
|
||||
`BEGIN TRANSACTION;\n${stripTrailingSemis(sql)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;\nROLLBACK;`,
|
||||
database,
|
||||
{},
|
||||
{ user: READER, password, caller: true },
|
||||
);
|
||||
const command = /^\s*([A-Za-z]+)/.exec(sql)?.[1]?.toUpperCase() ?? "";
|
||||
return { command, rows: parseJsonRows(stdout) };
|
||||
return { command: sql.trimStart().split(/\s+/)[0]?.toUpperCase() ?? "", rows };
|
||||
}
|
||||
}
|
||||
|
||||
function readerMissing(): Error {
|
||||
return new Error(
|
||||
"the read-only login's password was not delivered (own-secrets.reader, " +
|
||||
"MESH_MSSQL_READER_PASSWORD_FILE), so the statement is refused rather than run as the " +
|
||||
"administrator (novox/hq issue 193)",
|
||||
);
|
||||
}
|
||||
|
||||
/** Generate a URL-safe password. */
|
||||
export function generatePassword(): string {
|
||||
return randomBytes(24).toString("base64url");
|
||||
|
||||
@@ -38,15 +38,14 @@
|
||||
},
|
||||
"own-secrets": {
|
||||
"sa": "${dir:state}/sa.secret",
|
||||
"broker": "${dir:mesh-state}/broker",
|
||||
"reader": "${dir:state}/reader.secret"
|
||||
"broker": "/var/lib/mesh/mssql/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
"path": "/var/lib/mesh/mssql",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
@@ -100,17 +99,15 @@
|
||||
"name": "mesh-mssql",
|
||||
"network": "mssql",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"/var/lib/mesh/mssql/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:/var/lib/mssql/grants:ro",
|
||||
"${dir:state}/sa.secret:/run/secrets/sa:ro",
|
||||
"${dir:state}/reader.secret:/run/secrets/reader:ro"
|
||||
"${dir:state}/sa.secret:/run/secrets/sa:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_PROVISION_MSSQL": "mssql://sa@mssql:1433/master",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "/run/secrets/sa",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "/var/lib/mssql/grants/mesh.json",
|
||||
"MESH_MSSQL_READER_PASSWORD_FILE": "/run/secrets/reader"
|
||||
"MESH_RECEIVES": "/var/lib/mssql/grants/mesh.json"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
|
||||
@@ -1,13 +1,9 @@
|
||||
{
|
||||
"name": "@novox/module-mssql",
|
||||
"version": "0.1.0",
|
||||
"description": "mssql \u2014 provides the mesh mssql-database interface. Its client, provisioner, tools and events live here (novox/hq ADR 0039).",
|
||||
"description": "mssql — provides the mesh mssql-database interface. Its client, provisioner, tools and events live here (novox/hq ADR 0039).",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "tsc client.ts index.ts tools/index.ts provisioner/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
|
||||
"test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
|
||||
},
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.1"
|
||||
},
|
||||
|
||||
@@ -1,96 +0,0 @@
|
||||
// What holds mssql_query to being read-only (novox/hq issue 193): a caller's statement runs as the
|
||||
// reader login and never as the administrator, with sqlcmd's variable substitution off, on one line
|
||||
// that follows the module's own — a line break is refused before sqlcmd starts — and with no
|
||||
// transaction wrapped around it as text. Without the reader's password the statement is refused.
|
||||
//
|
||||
// sqlcmd is a fake on PATH that records each call's login, flags and text. That the reader cannot
|
||||
// write is the server's to enforce and was proven against a real server; this holds the module to
|
||||
// asking for it. Run against the compiled module (npm test builds first), the way the runtime loads it.
|
||||
|
||||
import { test, before, after } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { MssqlClient, READER } from "../dist/client.js";
|
||||
|
||||
let dir: string;
|
||||
let log: string;
|
||||
const originalPath = process.env.PATH;
|
||||
|
||||
before(async () => {
|
||||
dir = await mkdtemp(join(tmpdir(), "mssql-reader-"));
|
||||
log = join(dir, "calls.jsonl");
|
||||
await writeFile(join(dir, "sqlcmd"), `#!/usr/bin/env node
|
||||
const fs = require("node:fs");
|
||||
const args = process.argv.slice(2);
|
||||
const at = (flag) => args[args.indexOf(flag) + 1];
|
||||
fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({
|
||||
user: at("-U"), database: at("-d"), sql: at("-Q"), noVariables: args.includes("-x"),
|
||||
password: process.env.SQLCMDPASSWORD,
|
||||
}) + "\\n");
|
||||
const sql = at("-Q");
|
||||
if (/FROM sys.server_principals/.test(sql)) process.stdout.write("");
|
||||
else if (/FOR JSON/.test(sql)) process.stdout.write('[{"name":"alpha","n":1}]\\n');
|
||||
`);
|
||||
await chmod(join(dir, "sqlcmd"), 0o755);
|
||||
process.env.PATH = `${dir}:${originalPath}`;
|
||||
});
|
||||
|
||||
after(async () => {
|
||||
process.env.PATH = originalPath;
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
async function calls(): Promise<Record<string, unknown>[]> {
|
||||
const text = await readFile(log, "utf8").catch(() => "");
|
||||
await writeFile(log, "");
|
||||
return text.split("\n").filter(Boolean).map((line) => JSON.parse(line));
|
||||
}
|
||||
|
||||
const conn = { host: "127.0.0.1", port: 1433, user: "sa", password: "admin-secret" };
|
||||
|
||||
test("a caller's statement runs as the reader, without variables, on the module's first line", async () => {
|
||||
const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
|
||||
const result = await client.readOnlyQuery("inventory", "SELECT '$(SQLCMDPASSWORD)' AS p");
|
||||
|
||||
const asked = (await calls()).at(-1)!;
|
||||
assert.equal(asked.user, READER, "the statement never runs as the administrator");
|
||||
assert.equal(asked.password, "reader-secret");
|
||||
assert.equal(asked.noVariables, true, "no $(NAME) is substituted in a caller's text");
|
||||
const [first] = String(asked.sql).split("\n");
|
||||
assert.ok(first.startsWith("SET NOCOUNT ON; SELECT '$(SQLCMDPASSWORD)'"), "the caller's text never begins a line");
|
||||
assert.doesNotMatch(String(asked.sql), /BEGIN TRANSACTION|ROLLBACK/, "no transaction wrapped around it as text");
|
||||
assert.deepEqual(result.rows, [{ name: "alpha", n: 1 }]);
|
||||
assert.equal(result.command, "SELECT");
|
||||
});
|
||||
|
||||
test("a line break in a caller's statement is refused before sqlcmd starts", async () => {
|
||||
const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
|
||||
for (const sql of ["SELECT 1\n:!! id", "SELECT 1\r\n:!! id", "SELECT 1\r:!! id"]) {
|
||||
await assert.rejects(client.readOnlyQuery("inventory", sql), /must be one line/);
|
||||
}
|
||||
assert.deepEqual(await calls(), []);
|
||||
});
|
||||
|
||||
test("the reader is made as the administrator, kept out of sysadmin, and granted only reading", async () => {
|
||||
const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
|
||||
await client.readOnlyQuery("inventory", "SELECT 1 AS x");
|
||||
await client.readOnlyQuery("inventory", "SELECT 2 AS x");
|
||||
|
||||
const made = await calls();
|
||||
const asAdmin = made.filter((c) => c.user === "sa").map((c) => String(c.sql));
|
||||
assert.ok(asAdmin.some((s) => s.startsWith(`CREATE LOGIN [${READER}]`)));
|
||||
assert.ok(asAdmin.some((s) => /ALTER SERVER ROLE sysadmin DROP MEMBER/.test(s)));
|
||||
assert.ok(asAdmin.includes(`GRANT CONNECT ANY DATABASE TO [${READER}]`));
|
||||
assert.ok(asAdmin.includes(`GRANT SELECT ALL USER SECURABLES TO [${READER}]`));
|
||||
assert.equal(asAdmin.filter((s) => s.startsWith("CREATE LOGIN")).length, 1, "made once, not per call");
|
||||
assert.equal(made.filter((c) => c.user === READER).length, 2);
|
||||
});
|
||||
|
||||
test("without the reader's password the statement is refused, and nothing runs as the administrator", async () => {
|
||||
const client = new MssqlClient(conn);
|
||||
await assert.rejects(client.readOnlyQuery("inventory", "SELECT 1"), /refused rather than run as the administrator/);
|
||||
assert.deepEqual(await calls(), []);
|
||||
});
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user