A year of history, one chart, and a read API with personal tokens
History: server load, memory and disks are also kept as hourly (four months) and daily (over two years) averages with lowest and highest; endpoint answers as hourly (four months) beside the daily figures. Charts ask for 24 hours to a year and are drawn from whichever is fine enough. A disk that two weeks call flat is looked at again over ninety days for the forecast. Built once from what is kept. One chart: TimeChart replaces the sparkline and the multi-line chart: hover and arrow-key readout, a lowest/highest band, gaps shown as gaps, the same ranges everywhere and the choice remembered. Used for server trends, comparing servers, a check's availability and answer times (Endpoints > History) and a server's availability. Read API: /api/v1 (servers, metrics, alerts, incidents, inventory, network, endpoints and their history, maintenance) with personal read-only tokens made under the user menu: shown once, hashed, 30/90/365 days or none, ten at most, removed with their owner. GET only. Documented in API.md. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
5e26e77340
commit
68b41b5586
47 files changed
+12360
-247
No files matched your search
@@ -0,0 +1,279 @@
|
||||
/**
|
||||
* The read API and personal tokens: who may make a token, that the secret is shown once and only its hash kept, what a token can read (and that it can only
|
||||
* read), and when it stops working.
|
||||
*
|
||||
* Run with: npm test --workspace server
|
||||
*/
|
||||
import { test, describe, before, after } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, rmSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import type { AddressInfo } from "node:net";
|
||||
import type { Server } from "node:http";
|
||||
|
||||
const dir = mkdtempSync(join(tmpdir(), "hm-readapi-"));
|
||||
process.env.DATABASE_PATH = join(dir, "test.sqlite");
|
||||
process.env.SESSION_DIR = join(dir, "sessions");
|
||||
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
|
||||
process.env.HEALTH_STARTUP_GRACE_MS = "0";
|
||||
process.env.APP_BASE_URL = "https://hm.example.lan";
|
||||
|
||||
const express = (await import("express")).default;
|
||||
const { db } = await import("../src/db/client.js");
|
||||
const { users, servers, assets, apiTokens, endpointChecks, endpointResults, alertIncidents, maintenanceWindows, auditLog } = await import("../src/db/schema.js");
|
||||
const { runMigrations } = await import("../src/db/migrate.js");
|
||||
const { createApp } = await import("../src/app.js");
|
||||
const { apiTokensRouter } = await import("../src/routes/apiTokens.js");
|
||||
const { setAck } = await import("../src/services/alertAcks.js");
|
||||
const { invalidateAlertsCache } = await import("../src/services/alerts.js");
|
||||
const { startOrExtendWindow } = await import("../src/services/maintenance.js");
|
||||
const { eq } = await import("drizzle-orm");
|
||||
|
||||
await runMigrations();
|
||||
|
||||
const HOUR = 3600_000;
|
||||
let app: Server;
|
||||
let tokensApp: Server;
|
||||
let base = "";
|
||||
let tokensBase = "";
|
||||
let who = "ada";
|
||||
const ids: Record<string, number> = {};
|
||||
|
||||
const api = (path: string, secret: string | null, init: RequestInit = {}) =>
|
||||
fetch(`${base}/api/v1${path}`, { ...init, headers: { ...(secret ? { authorization: `Bearer ${secret}` } : {}), ...(init.headers ?? {}) } });
|
||||
const mine = (path: string, init: RequestInit = {}) => fetch(`${tokensBase}${path}`, { ...init, headers: { "content-type": "application/json", ...(init.headers ?? {}) } });
|
||||
const make = async (label: string, extra: Record<string, unknown> = {}) => {
|
||||
const res = await mine("", { method: "POST", body: JSON.stringify({ label, ...extra }) });
|
||||
return { status: res.status, body: (await res.json()) as any };
|
||||
};
|
||||
|
||||
before(async () => {
|
||||
const rows = await db
|
||||
.insert(users)
|
||||
.values([
|
||||
{ oidcSub: "ada", name: "Ada", role: "admin" },
|
||||
{ oidcSub: "vic", name: "Vic", email: "vic@example.lan", role: "viewer" },
|
||||
])
|
||||
.returning({ id: users.id, oidcSub: users.oidcSub });
|
||||
for (const r of rows) ids[r.oidcSub] = r.id;
|
||||
|
||||
// two servers (one reporting, one gone quiet), an alert on the quiet one, a piece of hardware, a check, an incident and a maintenance window
|
||||
ids.web = (await db.insert(servers).values({ name: "web", apiTokenHash: "SECRET-HASH-WEB", apiTokenPrefix: "w", tags: JSON.stringify(["lab"]), ipAddresses: JSON.stringify(["10.0.0.5"]), lastSeenAt: new Date().toISOString(), cpuLoadPercent: 12, memTotalBytes: 1000, memUsedBytes: 400, disks: JSON.stringify([{ mount: "/", sizeBytes: 100, usedBytes: 40 }]) }).returning({ id: servers.id }))[0].id;
|
||||
ids.db = (await db.insert(servers).values({ name: "db", apiTokenHash: "SECRET-HASH-DB", apiTokenPrefix: "d", lastSeenAt: new Date(Date.now() - 6 * HOUR).toISOString() }).returning({ id: servers.id }))[0].id;
|
||||
await db.insert(assets).values({ name: "Rack switch", kind: "network", location: "Rack A", purchasePrice: 120, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
|
||||
ids.check = (await db.insert(endpointChecks).values({ name: "Site", kind: "tcp", target: "127.0.0.1", port: 1, lastOk: true, lastCheckedAt: new Date().toISOString(), lastResponseMs: 12 }).returning({ id: endpointChecks.id }))[0].id;
|
||||
await db.insert(endpointResults).values({ checkId: ids.check, at: new Date().toISOString(), ok: true, ms: 12, message: "open" });
|
||||
await db.insert(alertIncidents).values({ alertKey: "offline:offline:server:1", severity: "critical", peakSeverity: "critical", category: "offline", source: "Server", message: "old", openedAt: new Date(Date.now() - 9 * HOUR).toISOString(), resolvedAt: new Date(Date.now() - 8 * HOUR).toISOString(), lastSeenAt: new Date().toISOString() });
|
||||
await startOrExtendWindow("server", ids.web, 60, "Patching", "Ada");
|
||||
await setAck({ alertId: `offline:offline:server:${ids.db}`, note: "On it", assigneeId: ids.ada, hours: 4, actor: "Ada" });
|
||||
invalidateAlertsCache();
|
||||
|
||||
app = await new Promise<Server>((resolve) => {
|
||||
const s = createApp().listen(0, "127.0.0.1", () => resolve(s));
|
||||
});
|
||||
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}`;
|
||||
const a = express();
|
||||
a.use(express.json());
|
||||
a.use((req, _res, next) => {
|
||||
(req as unknown as { session: unknown }).session = { user: { sub: who } };
|
||||
next();
|
||||
});
|
||||
a.use("/", apiTokensRouter);
|
||||
tokensApp = await new Promise<Server>((resolve) => {
|
||||
const s = a.listen(0, "127.0.0.1", () => resolve(s));
|
||||
});
|
||||
tokensBase = `http://127.0.0.1:${(tokensApp.address() as AddressInfo).port}`;
|
||||
});
|
||||
after(() => {
|
||||
app.close();
|
||||
tokensApp.close();
|
||||
try {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
} catch {
|
||||
// Windows may still hold the database file
|
||||
}
|
||||
});
|
||||
|
||||
describe("making and keeping tokens", () => {
|
||||
let secret = "";
|
||||
let tokenId = 0;
|
||||
|
||||
test("anyone signed in makes their own; the secret is in the answer once, and only a hash is kept", async () => {
|
||||
who = "vic";
|
||||
const made = await make("Home Assistant", { expiresInDays: 90 });
|
||||
assert.equal(made.status, 201);
|
||||
secret = made.body.secret;
|
||||
tokenId = made.body.token.id;
|
||||
assert.match(secret, /^hlm_p_[A-Za-z0-9_-]{20,}$/);
|
||||
assert.ok(made.body.token.expiresAt, "it ends");
|
||||
const stored = (await db.select().from(apiTokens).where(eq(apiTokens.id, tokenId)))[0];
|
||||
assert.notEqual(stored.tokenHash, secret);
|
||||
assert.equal(stored.tokenHash.length, 64);
|
||||
assert.equal(stored.userId, ids.vic);
|
||||
const list = await (await mine("")).json();
|
||||
assert.deepEqual(list.tokens.map((t: any) => t.label), ["Home Assistant"]);
|
||||
assert.ok(!JSON.stringify(list).includes(secret) && !JSON.stringify(list).includes(stored.tokenHash), "the list never has the secret or the hash");
|
||||
});
|
||||
|
||||
test("a token needs a name, and the end is 30, 90 or 365 days or none", async () => {
|
||||
assert.equal((await make("")).status, 400);
|
||||
assert.equal((await make("x", { expiresInDays: 7 })).status, 400);
|
||||
const forever = await make("No end");
|
||||
assert.equal(forever.status, 201);
|
||||
assert.equal(forever.body.token.expiresAt, null);
|
||||
await mine(`/${forever.body.token.id}`, { method: "DELETE" });
|
||||
});
|
||||
|
||||
test("a person has at most ten", async () => {
|
||||
who = "ada";
|
||||
for (let i = 0; i < 10; i++) assert.equal((await make(`t${i}`)).status, 201);
|
||||
const eleventh = await make("one too many");
|
||||
assert.equal(eleventh.status, 400);
|
||||
assert.match(eleventh.body.message, /already 10/);
|
||||
for (const t of (await (await mine("")).json()).tokens) await mine(`/${t.id}`, { method: "DELETE" });
|
||||
});
|
||||
|
||||
test("somebody else's token is not yours to see or remove", async () => {
|
||||
who = "ada";
|
||||
assert.equal(((await (await mine("")).json()) as any).tokens.length, 0, "Ada sees none of Vic's");
|
||||
assert.equal((await mine(`/${tokenId}`, { method: "DELETE" })).status, 404);
|
||||
assert.equal((await api("/me", secret)).status, 200, "and it still works");
|
||||
});
|
||||
|
||||
test("removing your own stops it at once", async () => {
|
||||
who = "vic";
|
||||
assert.equal((await api("/me", secret)).status, 200);
|
||||
assert.equal((await mine(`/${tokenId}`, { method: "DELETE" })).status, 204);
|
||||
assert.equal((await api("/me", secret)).status, 401);
|
||||
const entries = (await db.select().from(auditLog)).filter((e) => e.category === "api_token");
|
||||
assert.ok(entries.some((e) => e.action === "create") && entries.some((e) => e.action === "delete"), "making and removing a token is written down");
|
||||
assert.ok(entries.every((e) => !JSON.stringify(e).includes("hlm_p_")), "and the secret is not");
|
||||
});
|
||||
});
|
||||
|
||||
describe("what a token can read", () => {
|
||||
let secret = "";
|
||||
|
||||
before(async () => {
|
||||
who = "vic";
|
||||
secret = (await make("Reader")).body.secret;
|
||||
});
|
||||
|
||||
test("no token, a wrong one, and one in the address are all the same 401", async () => {
|
||||
for (const res of [await api("/servers", null), await api("/servers", "hlm_p_wrongwrongwrongwrongwrong"), await fetch(`${base}/api/v1/servers?token=${secret}`)]) {
|
||||
assert.equal(res.status, 401);
|
||||
assert.equal(res.headers.get("www-authenticate"), 'Bearer realm="homelab-manager"');
|
||||
assert.equal(((await res.json()) as any).error, "unauthorized");
|
||||
}
|
||||
});
|
||||
|
||||
test("it only reads: any other verb is refused, even with a good token", async () => {
|
||||
for (const method of ["POST", "PUT", "PATCH", "DELETE"]) {
|
||||
const res = await api("/servers", secret, { method });
|
||||
assert.equal(res.status, 405, method);
|
||||
assert.equal(res.headers.get("allow"), "GET, HEAD");
|
||||
}
|
||||
});
|
||||
|
||||
test("who the token is", async () => {
|
||||
const body = (await (await api("/me", secret)).json()) as any;
|
||||
assert.deepEqual([body.user.name, body.user.role, body.token.label], ["Vic", "viewer", "Reader"]);
|
||||
});
|
||||
|
||||
test("servers: a stable shape, no token hashes, the state worked out, filtered by tag and status", async () => {
|
||||
const res = await api("/servers", secret);
|
||||
assert.equal(res.headers.get("cache-control"), "no-store");
|
||||
const text = await res.text();
|
||||
assert.ok(!text.includes("SECRET-HASH") && !text.includes("apiToken"), "nothing of the servers' own tokens");
|
||||
const body = JSON.parse(text) as any;
|
||||
const web = body.servers.find((s: any) => s.name === "web");
|
||||
assert.deepEqual([web.status, web.tags, web.ipAddresses, web.cpu.loadPercent, web.disks[0].usedPercent, web.url], ["online", ["lab"], ["10.0.0.5"], 12, 40, `https://hm.example.lan/servers/${ids.web}`]);
|
||||
assert.equal(body.servers.find((s: any) => s.name === "db").status, "offline");
|
||||
assert.deepEqual(((await (await api("/servers?tag=lab", secret)).json()) as any).servers.map((s: any) => s.name), ["web"]);
|
||||
assert.deepEqual(((await (await api("/servers?status=offline", secret)).json()) as any).servers.map((s: any) => s.name), ["db"]);
|
||||
assert.equal((await api(`/servers/${ids.web}`, secret)).status, 200);
|
||||
assert.equal((await api("/servers/99999", secret)).status, 404);
|
||||
assert.equal((await api("/servers/abc", secret)).status, 400);
|
||||
});
|
||||
|
||||
test("a server's metrics, for up to a year", async () => {
|
||||
const body = (await (await api(`/servers/${ids.web}/metrics?days=9999`, secret)).json()) as any;
|
||||
assert.equal(body.days, 365);
|
||||
assert.ok(Array.isArray(body.series));
|
||||
});
|
||||
|
||||
test("alerts: what is wrong, with whether somebody is on it, filterable; addresses are whole", async () => {
|
||||
const body = (await (await api("/alerts", secret)).json()) as any;
|
||||
const offline = body.alerts.find((a: any) => a.id === `offline:offline:server:${ids.db}`);
|
||||
assert.ok(offline, "the quiet server is raised");
|
||||
assert.deepEqual([offline.severity, offline.acknowledgement.by, offline.acknowledgement.assignee, offline.acknowledgement.note], ["critical", "Ada", "Ada", "On it"]);
|
||||
assert.equal(offline.url, `https://hm.example.lan/servers/${ids.db}`);
|
||||
assert.equal(body.needingAttention.acknowledged, 1);
|
||||
assert.equal(((await (await api("/alerts?acknowledged=false", secret)).json()) as any).alerts.some((a: any) => a.id === offline.id), false);
|
||||
assert.equal(((await (await api("/alerts?severity=info", secret)).json()) as any).alerts.length, 0);
|
||||
});
|
||||
|
||||
test("incidents, inventory, network, endpoints and maintenance", async () => {
|
||||
const incidents = (await (await api("/incidents?status=resolved", secret)).json()) as any;
|
||||
assert.equal(incidents.incidents.length, 1);
|
||||
assert.equal(((await (await api(`/incidents/${incidents.incidents[0].id}`, secret)).json()) as any).incident?.id ?? incidents.incidents[0].id, incidents.incidents[0].id);
|
||||
const open = ((await (await api("/incidents?status=open", secret)).json()) as any).incidents;
|
||||
assert.deepEqual(open.map((i: any) => i.alertKey), [`offline:offline:server:${ids.db}`], "the quiet server's alert is an incident that is still open");
|
||||
|
||||
const inventory = (await (await api("/inventory", secret)).json()) as any;
|
||||
assert.deepEqual([inventory.assets[0].name, inventory.assets[0].location, inventory.assets[0].purchasePrice], ["Rack switch", "Rack A", 120]);
|
||||
|
||||
const network = (await (await api("/network", secret)).json()) as any;
|
||||
assert.deepEqual(Object.keys(network).sort(), ["devices", "networks", "serverLinks", "ssids"]);
|
||||
|
||||
const endpoints = (await (await api("/endpoints", secret)).json()) as any;
|
||||
assert.deepEqual([endpoints.endpoints[0].name, endpoints.endpoints[0].status, endpoints.endpoints[0].lastResponseMs], ["Site", "up", 12]);
|
||||
const history = (await (await api(`/endpoints/${ids.check}/history?days=1`, secret)).json()) as any;
|
||||
assert.deepEqual([history.check.name, history.source, history.checks], ["Site", "results", 1]);
|
||||
assert.equal((await api("/endpoints/99999/history", secret)).status, 404);
|
||||
|
||||
const maintenance = (await (await api("/maintenance", secret)).json()) as any;
|
||||
assert.deepEqual([maintenance.active.length, maintenance.active[0].target.name, maintenance.active[0].reason], [1, "web", "Patching"]);
|
||||
});
|
||||
|
||||
test("an address that is not there says so, and the index lists them", async () => {
|
||||
const res = await api("/nothing", secret);
|
||||
assert.equal(res.status, 404);
|
||||
const index = (await (await api("/", secret)).json()) as any;
|
||||
assert.ok(index.endpoints.some((e: string) => e.includes("/api/v1/alerts")));
|
||||
});
|
||||
});
|
||||
|
||||
describe("when a token stops working", () => {
|
||||
test("it ends on the day it was made to; a removed person's tokens go with them", async () => {
|
||||
who = "ada";
|
||||
const { body } = await make("Short");
|
||||
const secret = body.secret;
|
||||
assert.equal((await api("/me", secret)).status, 200);
|
||||
// the end comes: move it into the past
|
||||
await db.update(apiTokens).set({ expiresAt: new Date(Date.now() - 1000).toISOString() }).where(eq(apiTokens.id, body.token.id));
|
||||
assert.equal((await api("/me", secret)).status, 401, "expired");
|
||||
const listed = ((await (await mine("")).json()) as any).tokens.find((t: any) => t.id === body.token.id);
|
||||
assert.equal(listed.expired, true, "and the list says so");
|
||||
|
||||
const gone = (await db.insert(users).values({ oidcSub: "temp", name: "Temp", role: "viewer" }).returning({ id: users.id }))[0].id;
|
||||
const { createApiToken } = await import("../src/services/apiTokens.js");
|
||||
const t = await createApiToken({ userId: gone, label: "Leaver", expiresInDays: null });
|
||||
assert.equal((await api("/me", t.token)).status, 200);
|
||||
await db.delete(users).where(eq(users.id, gone));
|
||||
assert.equal((await api("/me", t.token)).status, 401, "the person is gone, so is the token");
|
||||
assert.equal((await db.select().from(apiTokens).where(eq(apiTokens.userId, gone))).length, 0);
|
||||
});
|
||||
|
||||
test("use is noted, but not more than once a minute", async () => {
|
||||
who = "ada";
|
||||
const { body } = await make("Used");
|
||||
assert.equal((await db.select().from(apiTokens).where(eq(apiTokens.id, body.token.id)))[0].lastUsedAt, null);
|
||||
await api("/me", body.secret);
|
||||
const first = (await db.select().from(apiTokens).where(eq(apiTokens.id, body.token.id)))[0].lastUsedAt;
|
||||
assert.ok(first);
|
||||
await api("/me", body.secret);
|
||||
assert.equal((await db.select().from(apiTokens).where(eq(apiTokens.id, body.token.id)))[0].lastUsedAt, first);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user