/** * The integration inspector: what an answer looks like (names and kinds, never values), where what a reader made of it is empty, the requests written down while a read runs, and the route that * runs one for an administrator. * * Run with: npm test --workspace server */ import { test, describe, before, after } from "node:test"; import assert from "node:assert/strict"; import { createServer as createHttpServer, type Server } from "node:http"; import { mkdtempSync, readFileSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import type { AddressInfo } from "node:net"; const dir = mkdtempSync(join(tmpdir(), "hm-inspect-")); process.env.DATABASE_PATH = join(dir, "test.sqlite"); process.env.SESSION_DIR = join(dir, "sessions"); process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32); const express = (await import("express")).default; const { db } = await import("../src/db/client.js"); const { users, integrations, auditLog } = await import("../src/db/schema.js"); const { runMigrations } = await import("../src/db/migrate.js"); const insp = await import("../src/integrations/inspector.js"); const { requestJson } = await import("../src/integrations/httpJson.js"); const { integrationsRouter } = await import("../src/routes/integrations.js"); const { eq } = await import("drizzle-orm"); await runMigrations(); describe("what an answer looks like", () => { test("keys and the kinds of what they hold — and never a value", () => { const s = insp.shapeOf({ id: 7, name: "super-secret-name", ok: true, nothing: null, tags: ["a", "b"], nested: { when: "2026-01-01", n: 1.5 } }); assert.equal(s, "{ id: number, name: string, ok: boolean, nothing: null, tags: array(2) of string, nested: { when: string, n: number } }"); assert.doesNotMatch(s, /super-secret|2026|7\b/); }); test("a list of objects shows the keys of them all, and marks a key that only some have", () => { const s = insp.shapeOf([{ id: 1, name: "a" }, { id: 2, name: "b", extra: 1 }, { id: 3, name: "c" }]); assert.equal(s, "array(3) of { id: number, name: string, extra?: number }"); assert.equal(insp.shapeOf([]), "array(0)"); assert.equal(insp.shapeOf([1, "x", null]), "array(3) of number | string | null"); assert.equal(insp.shapeOf("text"), "string"); }); test("it goes three levels down and no further, caps the keys and the length", () => { assert.equal(insp.shapeOf({ a: { b: { c: { d: { e: 1 } } } } }), "{ a: { b: { c: object } } }"); const many = Object.fromEntries(Array.from({ length: 40 }, (_, i) => [`k${i}`, i])); assert.match(insp.shapeOf(many), /, … \}$/); assert.ok(insp.shapeOf(Object.fromEntries(Array.from({ length: 30 }, (_, i) => [`key${i}_${"x".repeat(80)}`, "v"]))).length <= 1810); }); test("a path is reported with the names of its query, not what they were set to", () => { assert.equal(insp.pathForReport(new URL("http://x/api/v3/queue?page=1&pageSize=100&apikey=SECRET")), "/api/v3/queue?page&pageSize&apikey"); assert.equal(insp.pathForReport(new URL("http://x/api/health")), "/api/health"); }); }); describe("where it is empty", () => { test("null, empty text, empty lists — and a field null in every item of a list", () => { const e = insp.emptyFields({ version: null, name: "", queue: { total: 0, items: [] }, servers: [{ id: 1, usage: null, name: "a" }, { id: 2, usage: null, name: "b" }], fine: "yes" }); assert.deepEqual(e.map((x) => [x.path, x.what]), [["version", "null"], ["name", "text"], ["queue.items", "list"], ["servers[].usage", "every-item"]]); }); test("a field that is null in some items only is not reported; numbers such as 0 are not empty", () => { assert.deepEqual(insp.emptyFields({ servers: [{ usage: null }, { usage: 5 }], count: 0, ok: false }), []); }); test("a result that is itself empty, and a limit", () => { assert.deepEqual(insp.emptyFields(null), [{ path: "(the result)", what: "null" }]); assert.equal(insp.emptyFields(Object.fromEntries(Array.from({ length: 80 }, (_, i) => [`f${i}`, null])), 10).length, 10); }); }); describe("the reason in a refusal", () => { test("a short message from an error answer is kept; nothing from a good answer, and nothing that is not text", () => { assert.equal(insp.replyOf({ message: "Missing required permission: server.statistics", statusCode: 403 }), "Missing required permission: server.statistics"); assert.equal(insp.replyOf({ error: "invalid_token", error_description: "x" }), "invalid_token"); assert.equal(insp.replyOf({ message: ["name must be a string", "age must be a number"] }), "name must be a string; age must be a number"); assert.equal(insp.replyOf({ message: "a".repeat(500) })?.length, 160); assert.equal(insp.replyOf({ data: [1] }), undefined); assert.equal(insp.replyOf([{ message: "x" }]), undefined); assert.equal(insp.replyOf(null), undefined); }); }); describe("what an answer that is not JSON looks like", () => { test("a web page, markup, metrics text, plain text or nothing — from its first characters only", () => { assert.equal(insp.looksLike("Not found"), "an HTML page"); assert.equal(insp.looksLike(" \n"), "an HTML page"); assert.equal(insp.looksLike(''), "XML or markup"); assert.equal(insp.looksLike("# HELP up whether it is up\nup 1"), "metrics text (Prometheus format)"); assert.equal(insp.looksLike("Not Found"), "plain text"); assert.equal(insp.looksLike(" "), undefined); }); }); describe("the requests written down while a read runs", () => { let http: Server; let url = ""; before(async () => { http = createHttpServer((req, res) => { res.setHeader("content-type", "application/json"); if (req.url?.startsWith("/json")) return void res.end(JSON.stringify({ items: [{ id: 1, secret: "hidden-value" }], total: 1 })); if (req.url?.startsWith("/html")) return void res.end("nope"); if (req.url?.startsWith("/denied")) return void ((res.statusCode = 403), res.end(JSON.stringify({ message: "Missing required permission: server.statistics" }))); res.statusCode = 404; res.end("{}"); }); await new Promise((r) => http.listen(0, "127.0.0.1", r)); url = `http://127.0.0.1:${(http.address() as AddressInfo).port}`; }); after(() => http.close()); test("each request: method, path (no values), status, time, size and the shape of the answer; a failed one too", async () => { const { calls, value, error } = await insp.inspectCalls(async () => { await requestJson(`${url}/json?token=hidden&page=2`); await requestJson(`${url}/html`); await requestJson(`${url}/missing`); await requestJson("http://127.0.0.1:1/refused").catch(() => undefined); return "done"; }); assert.deepEqual([value, error], ["done", null]); assert.deepEqual(calls.map((c) => [c.method, c.path, c.status]), [["GET", "/json?token&page", 200], ["GET", "/html", 200], ["GET", "/missing", 404], ["GET", "/refused", 0]]); assert.equal(calls[0].shape, "{ items: array(1) of { id: number, secret: string }, total: number }"); assert.equal(calls[1].shape, null, "not JSON"); assert.deepEqual([calls[0].contentType, calls[0].looks], ["application/json", undefined]); assert.deepEqual([calls[1].contentType, calls[1].looks], ["application/json", "an HTML page"], "what the text looks like, not what it says"); assert.doesNotMatch(JSON.stringify(calls), /nope/); assert.equal(calls[0].reply, undefined, "nothing is said of a good answer"); const denied = (await insp.inspectCalls(async () => requestJson(`${url}/denied`))).calls[0]; assert.deepEqual([denied.status, denied.reply], [403, "Missing required permission: server.statistics"]); assert.ok(calls[0].bytes > 10 && calls[0].ms >= 0); assert.ok(calls[3].error); assert.doesNotMatch(JSON.stringify(calls), /hidden-value|hidden/); }); test("a read that throws is reported with what it asked before it did; and nothing is written down outside an inspection", async () => { const { calls, value, error } = await insp.inspectCalls(async () => { await requestJson(`${url}/json`); throw new Error("the reader gave up"); }); assert.deepEqual([calls.length, value, error], [1, undefined, "the reader gave up"]); assert.equal(insp.isInspecting(), false); await requestJson(`${url}/json`); const second = await insp.inspectCalls(async () => 1); assert.deepEqual(second.calls, [], "the earlier request was not kept"); }); test("two inspections at once keep their own requests", async () => { const [a, b] = await Promise.all([insp.inspectCalls(async () => requestJson(`${url}/json?a=1`)), insp.inspectCalls(async () => requestJson(`${url}/html?b=1`))]); assert.deepEqual([a.calls.map((c) => c.path), b.calls.map((c) => c.path)], [["/json?a"], ["/html?b"]]); }); }); describe("the route", () => { let grafana: Server; let app: Server; let base = ""; let grafanaId = 0; let tailscaleId = 0; let offId = 0; const call = (sub: string, id: number) => fetch(`${base}/${id}/inspect`, { method: "POST", headers: { "content-type": "application/json", "x-sub": sub } }); before(async () => { await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }, { oidcSub: "admin", name: "Ada", role: "admin" }]); grafana = createHttpServer((req, res) => { res.setHeader("content-type", "application/json"); const u = new URL(req.url ?? "", "http://x"); if (u.pathname === "/api/health") return void res.end(JSON.stringify({ database: "ok", version: "11.2.0" })); if (u.pathname === "/api/prometheus/grafana/api/v1/rules") return void res.end(JSON.stringify({ status: "success", data: { groups: [{ name: "g", file: "f", rules: [{ name: "r", state: "inactive", health: "ok" }] }] } })); if (u.pathname === "/api/datasources") return void res.end(JSON.stringify([])); res.statusCode = 404; res.end("{}"); }); await new Promise((r) => grafana.listen(0, "127.0.0.1", r)); const gurl = `http://127.0.0.1:${(grafana.address() as AddressInfo).port}`; grafanaId = (await db.insert(integrations).values({ type: "grafana", name: "Dashboards", baseUrl: gurl, config: JSON.stringify({ url: gurl, token: "glsa_x" }) }).returning({ id: integrations.id }))[0].id; tailscaleId = (await db.insert(integrations).values({ type: "tailscale", name: "Tailnet", baseUrl: "http://x", config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id; offId = (await db.insert(integrations).values({ type: "grafana", name: "Off", baseUrl: gurl, enabled: false, config: JSON.stringify({ url: gurl, token: "t" }) }).returning({ id: integrations.id }))[0].id; const a = express(); a.use(express.json()); a.use((req, _res, next) => { (req as unknown as { session: unknown }).session = { user: { sub: String(req.headers["x-sub"]) } }; next(); }); a.use("/api/integrations", integrationsRouter); app = await new Promise((resolve) => { const s = a.listen(0, "127.0.0.1", () => resolve(s)); }); base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/integrations`; }); after(() => { app.close(); grafana.close(); try { rmSync(dir, { recursive: true, force: true }); } catch { // Windows keeps the database file locked until the process exits. } }); test("an administrator gets what it asked, what came back (as shapes) and where the result is empty; the token is nowhere in it", async () => { const res = await call("admin", grafanaId); assert.equal(res.status, 200); const text = await res.text(); assert.doesNotMatch(text, /glsa_x/); const body = JSON.parse(text) as { ok: boolean; type: string; calls: { path: string; status: number; shape: string | null }[]; resultShape: string; empty: { path: string; what: string }[] }; assert.deepEqual([body.ok, body.type], [true, "grafana"]); assert.ok(body.calls.some((c) => c.path === "/api/health" && c.status === 200 && c.shape === "{ database: string, version: string }")); assert.ok(body.calls.some((c) => c.path === "/api/prometheus/grafana/api/v1/rules")); assert.match(body.resultShape, /^\{ version: string, rules: \{ total: number, items: array\(0\) \}, datasources: array\(0\) \}$/); assert.ok(body.empty.some((e) => e.path === "rules.items" && e.what === "list")); assert.ok(body.empty.some((e) => e.path === "datasources" && e.what === "list")); }); test("a failed read is reported with what it asked, not as an error of the route", async () => { await db.update(integrations).set({ config: JSON.stringify({ url: "http://127.0.0.1:1", token: "t" }) }).where(eq(integrations.id, grafanaId)); const body = (await (await call("admin", grafanaId)).json()) as { ok: boolean; error: string; calls: { status: number; error?: string }[]; resultShape: string | null }; assert.deepEqual([body.ok, body.resultShape, body.calls.some((c) => c.status === 0)], [false, null, true]); assert.ok(body.error); }); test("only an administrator; a kind with no reader, a switched-off integration and an unknown one are refused; each inspection is in the audit log", async () => { assert.equal((await call("viewer", grafanaId)).status, 403); assert.equal((await call("admin", tailscaleId)).status, 400); assert.equal(((await (await call("admin", tailscaleId)).json()) as { error: string }).error, "not_inspectable"); assert.equal(((await (await call("admin", offId)).json()) as { error: string }).error, "integration_disabled"); assert.equal((await call("admin", 99999)).status, 404); const entries = (await db.select().from(auditLog)).filter((e) => e.action === "inspect"); assert.equal(entries.length, 2, "the two that ran"); assert.deepEqual(entries.map((e) => [e.category, e.targetType]), [["integration", "integration"], ["integration", "integration"]]); }); test("n8n and Home Assistant can be inspected too, and the web page offers the button for both", async () => { const other = createHttpServer((req, res) => { res.setHeader("content-type", "application/json"); const u = new URL(req.url ?? "", "http://x"); if (u.pathname === "/api/v1/workflows") return void res.end(JSON.stringify({ data: [{ id: "1", name: "Backup", active: true }], nextCursor: null })); if (u.pathname === "/api/v1/executions") return void res.end(JSON.stringify({ data: [{ workflowId: "1", status: "success", stoppedAt: "2026-01-01T00:00:00Z" }] })); if (u.pathname === "/api/states") return void res.end(JSON.stringify([{ entity_id: "sensor.t", state: "21.5", attributes: { friendly_name: "Temp", unit_of_measurement: "°C" }, last_changed: "2026-01-01T00:00:00Z" }])); res.statusCode = 404; res.end("{}"); }); await new Promise((r) => other.listen(0, "127.0.0.1", r)); try { const url = `http://127.0.0.1:${(other.address() as AddressInfo).port}`; const n8nId = (await db.insert(integrations).values({ type: "n8n", name: "Flows", baseUrl: url, config: JSON.stringify({ url, apiKey: "n8n_secret" }) }).returning({ id: integrations.id }))[0].id; const haId = (await db.insert(integrations).values({ type: "homeassistant", name: "Home", baseUrl: url, config: JSON.stringify({ url, token: "ha_secret" }) }).returning({ id: integrations.id }))[0].id; for (const [id, path] of [[n8nId, "/api/v1/workflows"], [haId, "/api/states"]] as const) { const text = await (await call("admin", id)).text(); assert.doesNotMatch(text, /n8n_secret|ha_secret/); const body = JSON.parse(text) as { ok: boolean; calls: { path: string; status: number }[] }; assert.equal(body.ok, true, text); assert.ok(body.calls.some((c) => c.path.startsWith(path) && c.status === 200), path); } } finally { other.close(); } const types = readFileSync(new URL("../../web/src/utils/integrationTypes.ts", import.meta.url), "utf8"); const list = types.match(/INSPECTABLE[^=]*=\s*\[([^\]]*)\]/)?.[1] ?? ""; for (const kind of ["n8n", "homeassistant"]) assert.ok(list.includes(`"${kind}"`), kind); }); });