Inspect on a real Immich got data only from /server/about and /server/storage; the other four answered with a bare message, most likely a key without the permissions. The inspector now keeps the short message of any answer with HTTP 400 and up (never for a good answer) and shows it on the page and in the copied report. The permission list now includes server.versionCheck, and the docs say which endpoints have been seen live. Tests added. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
265 lines
16 KiB
TypeScript
265 lines
16 KiB
TypeScript
/**
|
|
* 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("<!DOCTYPE html><html><body>Not found</body></html>"), "an HTML page");
|
|
assert.equal(insp.looksLike(" \n<html lang=en>"), "an HTML page");
|
|
assert.equal(insp.looksLike('<?xml version="1.0"?><a/>'), "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("<html>nope</html>");
|
|
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<void>((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<void>((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<Server>((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<void>((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);
|
|
});
|
|
});
|