Add runbooks, backup coverage, inventory, roles from groups, Prometheus metrics and event webhooks

- Runbooks: notes per server/integration, shown next to matching alerts
- Backup coverage page across Proxmox and PBS, with a digest section
- Hardware inventory with warranty, power and running cost
- Authentik group to role mapping with preview and safeguards
- /metrics (bearer token) and signed outgoing event webhooks
- Docs: README, DATABASE, NOTIFICATIONS, ROLES and new API.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-17 20:41:00 +02:00
1 parent c36e2092c5
commit c17e9aa140
55 files changed
+7177 -27

No files matched your search

+105
View File
@@ -0,0 +1,105 @@
/**
* Event webhooks: tell another system when something happens. Each webhook is a URL with the events it wants; when one happens it is
* sent a JSON message, signed with the webhook's secret so the receiver can tell it came from here. This is separate from the chat-style
* webhook under Settings → Notifications, which carries the same sentence a person would read.
*
* alert.opened / alert.resolved a problem began or ended — on the same terms as a notification (a problem under maintenance,
* or folded under another, isn't announced until it stands alone)
* maintenance.started / .ended a maintenance window began or finished, however it was made
*
* Delivery is best-effort and never holds anything up: one try, one more if that fails, then the result is noted on the webhook (shown in
* Settings) and forgotten.
*/
import { createHmac, randomUUID } from "node:crypto";
import { eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { eventWebhooks, webhookEvents, type WebhookEvent } from "../db/schema.js";
import { decryptSecret, encryptSecret } from "../crypto.js";
import { env } from "../env.js";
export type EventWebhookRow = typeof eventWebhooks.$inferSelect;
const ENCRYPTED_PREFIX = "enc:v1:";
const TIMEOUT_MS = 5000;
const RETRY_AFTER_MS = 2000;
/** The stored form of a secret: encrypted when an encryption key is set, as the notification channels' secrets are. */
export function sealSecret(plain: string): string {
return env.credentialsEncryptionEnabled ? ENCRYPTED_PREFIX + encryptSecret(plain) : plain;
}
function openSecret(stored: string | null): string | null {
if (!stored) return null;
if (!stored.startsWith(ENCRYPTED_PREFIX)) return stored;
try {
return decryptSecret(stored.slice(ENCRYPTED_PREFIX.length));
} catch {
return null;
}
}
export function parseEvents(stored: string): WebhookEvent[] {
try {
const v = JSON.parse(stored);
return Array.isArray(v) ? v.filter((e): e is WebhookEvent => (webhookEvents as readonly string[]).includes(e)) : [];
} catch {
return [];
}
}
/** The signature a receiver should compute over the exact body it got: HMAC-SHA256 with the secret, as hex, prefixed "sha256=". */
export function signBody(secret: string, body: string): string {
return `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
}
export interface Delivery {
ok: boolean;
/** "200", or what went wrong. */
result: string;
}
async function post(row: EventWebhookRow, event: string, body: string, deliveryId: string): Promise<Delivery> {
const secret = openSecret(row.secret);
const headers: Record<string, string> = {
"Content-Type": "application/json",
"User-Agent": "HomelabManager-Webhook",
"X-HLM-Event": event,
"X-HLM-Delivery": deliveryId,
};
if (secret) headers["X-HLM-Signature"] = signBody(secret, body);
try {
const res = await fetch(row.url, { method: "POST", headers, body, signal: AbortSignal.timeout(TIMEOUT_MS), redirect: "manual" });
return { ok: res.status >= 200 && res.status < 300, result: String(res.status) };
} catch (err) {
const name = err instanceof Error ? err.name : "";
return { ok: false, result: name === "TimeoutError" ? "timed out" : err instanceof Error ? err.message.slice(0, 120) : "failed" };
}
}
/** One message to one webhook, retried once if it didn't go through. The outcome is written on the webhook. */
export async function deliver(row: EventWebhookRow, event: string, data: unknown, options: { retryAfterMs?: number } = {}): Promise<Delivery> {
const deliveryId = randomUUID();
const body = JSON.stringify({ event, id: deliveryId, createdAt: new Date().toISOString(), source: "homelab-manager", data });
let outcome = await post(row, event, body, deliveryId);
if (!outcome.ok) {
await new Promise((r) => setTimeout(r, options.retryAfterMs ?? RETRY_AFTER_MS));
outcome = await post(row, event, body, deliveryId);
}
try {
await db.update(eventWebhooks).set({ lastAttemptAt: new Date().toISOString(), lastResult: outcome.result }).where(eq(eventWebhooks.id, row.id));
} catch (err) {
console.error("[webhooks] couldn't note the result:", err);
}
return outcome;
}
/**
* Sends an event to every enabled webhook that wants it. Returns at once — delivery carries on in the background and can never delay or
* fail what caused the event.
*/
export function emitEvent(event: WebhookEvent, data: unknown): void {
void (async () => {
const rows = await db.select().from(eventWebhooks).where(eq(eventWebhooks.enabled, true));
await Promise.all(rows.filter((r) => parseEvents(r.events).includes(event)).map((r) => deliver(r, event, data)));
})().catch((err) => console.error("[webhooks] couldn't send an event:", err));
}