Files
Homelab-manager/server/src/routes/settings.ts
T
bobbanandClaude Sonnet 5.5 3b31b16796 Service-level targets with error budgets, and quarterly and annual reports
Monitoring -> Service levels: a target (99.9 %) on an endpoint check, a server or an
integration, measured over calendar months. Shows the figure, downtime used, the
error budget left, and how the last six months went. 80 % of the budget used is a
warning and an overspent budget a critical alert. Endpoints are measured day by day,
servers and integrations to the minute from the audit log.

The report page gains Quarter and Year (same figures, with a Service levels section),
and two settings send the quarterly and annual report after the month that ends them.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 22:20:07 +02:00

376 lines
16 KiB
TypeScript

import { Router } from "express";
import { z } from "zod";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { getSettings, updateSettings } from "../services/settingsStore.js";
import { describeSettingsChanges } from "../services/settingsDiff.js";
import { scheduleSecretExpiryCheck } from "../services/secretExpiryScheduler.js";
import { scheduleTailscaleKeyExpiryCheck } from "../services/tailscaleKeyExpiryScheduler.js";
import { scheduleDockerUpdateCheck } from "../services/dockerUpdateScheduler.js";
import { scheduleProxmoxBackupCheck } from "../services/proxmoxBackupScheduler.js";
import { schedulePbsVerificationCheck } from "../services/pbsVerificationScheduler.js";
import { scheduleLogRetentionPurge } from "../services/logRetentionScheduler.js";
import { purgeOldLogs } from "../services/logRetention.js";
import { scheduleQuietHoursFlush } from "../services/quietHoursScheduler.js";
import { scheduleWeeklyDigest } from "../services/weeklyDigestScheduler.js";
import { scheduleMonthlyReport } from "../services/monthlyReportScheduler.js";
import { buildDigest, sendDigest } from "../services/weeklyDigest.js";
import { enabledChannelCount } from "../services/notify.js";
import { CATEGORIES, CHANNEL_IDS } from "../services/notifyRouting.js";
import { InvalidTagError, normalizeTags } from "../services/serverTags.js";
import { testGotify, testNtfy, testSmtp, testWebhook, flushQuietHoursQueue } from "../services/notify.js";
import { listQueuedNotifications } from "../services/notificationQueue.js";
import { buildExportPayload, encryptExport, decryptExport, applyImportPayload, type EncryptedExportFile } from "../services/configBackup.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const settingsRouter = Router();
settingsRouter.use(requireAuth);
settingsRouter.get("/", requireRole("admin"), asyncHandler(async (_req, res) => {
res.json({ settings: await getSettings() });
}));
// Non-secret subset any signed-in user can read, so badge colors can be applied
// throughout the app without exposing Gotify/SMTP/webhook credentials.
settingsRouter.get("/provider-colors", asyncHandler(async (_req, res) => {
const { providerColors } = await getSettings();
res.json({ providerColors });
}));
settingsRouter.get("/integration-colors", asyncHandler(async (_req, res) => {
const { integrationColors } = await getSettings();
res.json({ integrationColors });
}));
// Display prefs (date/time format) affect every page, so any signed-in user
// can read them — same non-secret rationale as the badge-color endpoints.
settingsRouter.get("/display", asyncHandler(async (_req, res) => {
const { display } = await getSettings();
res.json({ display });
}));
const channelEnum = z.enum(CHANNEL_IDS);
// Routing rules: which channels hear which notifications. A rule with no channels means "tell nobody" (the Alerts page still shows it).
const routingSchema = z.object({
rules: z
.array(
z.object({
id: z.string().trim().min(1).max(40),
name: z.string().trim().min(1).max(60),
enabled: z.boolean(),
categories: z.array(z.enum(CATEGORIES)).max(10),
minSeverity: z.enum(["warning", "critical"]).nullable(),
tags: z.array(z.string().trim().min(1).max(30)).max(10),
channels: z.array(channelEnum).max(5),
}),
)
.max(30),
});
// Escalation: a few steps in time order. Each must say who to tell — a channel, or an address.
const escalationSchema = z
.object({
enabled: z.boolean(),
steps: z
.array(
z.object({
afterMinutes: z.number().int().min(5).max(10080),
minSeverity: z.enum(["warning", "critical"]),
channels: z.array(channelEnum).max(5),
extraEmail: z.string().trim().max(200).refine((v) => v === "" || /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v), "That isn't an email address"),
evenInQuietHours: z.boolean(),
}),
)
.max(3),
})
.superRefine((v, ctx) => {
v.steps.forEach((s, i) => {
if (s.channels.length === 0 && s.extraEmail === "") ctx.addIssue({ code: "custom", path: ["steps", i], message: "Choose a channel to tell, or an address to email." });
if (i > 0 && s.afterMinutes <= v.steps[i - 1].afterMinutes) ctx.addIssue({ code: "custom", path: ["steps", i, "afterMinutes"], message: "Each step must come later than the one before." });
});
});
const updateSchema = z.object({
routing: routingSchema.optional(),
escalation: escalationSchema.optional(),
gotify: z.object({ enabled: z.boolean(), url: z.string(), token: z.string(), priority: z.number() }).partial().optional(),
ntfy: z.object({ enabled: z.boolean(), url: z.string(), topic: z.string(), token: z.string(), priority: z.number() }).partial().optional(),
smtp: z
.object({
enabled: z.boolean(),
host: z.string(),
port: z.number(),
secure: z.boolean(),
username: z.string(),
password: z.string(),
from: z.string(),
to: z.string(),
})
.partial()
.optional(),
webhook: z.object({ enabled: z.boolean(), url: z.string(), secret: z.string() }).partial().optional(),
webPush: z.object({ enabled: z.boolean(), contact: z.string().trim().max(200) }).partial().optional(),
notifications: z
.object({
dnsAdd: z.boolean(),
dnsUpdate: z.boolean(),
dnsDelete: z.boolean(),
secretCheck: z.boolean(),
tailscaleKeyCheck: z.boolean(),
dockerUpdateCheck: z.boolean(),
proxmoxBackupCheck: z.boolean(),
pbsVerificationCheck: z.boolean(),
healthAlerts: z.boolean(),
automationAlerts: z.boolean(),
updateRunResults: z.boolean(),
domainExpiryCheck: z.boolean(),
secretCheckTime: z.string().regex(/^\d{2}:\d{2}$/),
timezone: z.string(),
integrationFailureAlerts: z.boolean(),
integrationFailureThreshold: z.number().int().min(1).max(20),
})
.partial()
.optional(),
providerColors: z.record(z.string()).optional(),
integrationColors: z.record(z.string()).optional(),
display: z
.object({ dateFormat: z.enum(["ymd", "dmy", "mdy"]), timeFormat: z.enum(["24h", "12h"]), pageSize: z.number().int().min(5).max(500) })
.partial()
.optional(),
logRetention: z
.object({ enabled: z.boolean(), retentionDays: z.number().int().min(1).max(3650), intervalHours: z.number().int().min(1).max(720) })
.partial()
.optional(),
healthChecks: z
.object({ serverOfflineMinutes: z.number().int().min(15).max(10080), diskUsagePercent: z.number().int().min(50).max(99), domainWarnDays: z.number().int().min(1).max(365), diskForecastDays: z.number().int().min(0).max(90), backupStaleHours: z.number().int().min(0).max(2160), restoreTestDays: z.number().int().min(0).max(730), newPortAlerts: z.boolean(), flapRaises: z.number().int().min(0).max(20), deviceOfflineMinutes: z.number().int().min(5).max(1440), osSupportWarnDays: z.number().int().min(0).max(365), baselineAlerts: z.boolean() })
.partial()
.optional(),
quietHours: z
.object({ enabled: z.boolean(), start: z.string().regex(/^\d{2}:\d{2}$/), end: z.string().regex(/^\d{2}:\d{2}$/) })
.partial()
.optional(),
signIn: z
.object({
roleFromGroups: z.boolean(),
groupsClaim: z.string().regex(/^[A-Za-z0-9_:.\-/]{1,60}$/, "Use the claim's name, like groups"),
adminGroups: z.array(z.string().trim().min(1).max(100)).max(20),
operatorGroups: z.array(z.string().trim().min(1).max(100)).max(20),
otherwise: z.enum(["viewer", "keep"]),
})
.partial()
.optional(),
profilePictures: z.object({ gravatar: z.boolean(), identityProvider: z.boolean() }).partial().optional(),
alertActions: z.object({ enabled: z.boolean() }).partial().optional(),
digest: z
.object({ enabled: z.boolean(), day: z.number().int().min(0).max(6), time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/) })
.partial()
.optional(),
monthlyReport: z
.object({ enabled: z.boolean(), quarterly: z.boolean(), annual: z.boolean(), day: z.number().int().min(1).max(28), time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/) })
.partial()
.optional(),
});
settingsRouter.put("/", requireRole("admin"), asyncHandler(async (req, res) => {
const parsed = updateSchema.safeParse(req.body);
if (!parsed.success) {
return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
}
// Tags in routing rules are written the way server tags are, so they match.
try {
if (parsed.data.routing) for (const rule of parsed.data.routing.rules) rule.tags = normalizeTags(rule.tags);
} catch (err) {
if (err instanceof InvalidTagError) return res.status(400).json({ error: "invalid_tag", message: err.message });
throw err;
}
const before = await getSettings();
const updated = await updateSettings(parsed.data);
if (parsed.data.notifications) {
await scheduleSecretExpiryCheck();
await scheduleTailscaleKeyExpiryCheck();
await scheduleDockerUpdateCheck();
await scheduleProxmoxBackupCheck();
await schedulePbsVerificationCheck();
}
if (parsed.data.logRetention) {
await scheduleLogRetentionPurge();
}
if (parsed.data.quietHours || parsed.data.notifications) {
await scheduleQuietHoursFlush();
}
if (parsed.data.digest || parsed.data.notifications) {
await scheduleWeeklyDigest();
}
if (parsed.data.monthlyReport || parsed.data.notifications) {
await scheduleMonthlyReport();
}
await recordAudit({
actor: req.currentUser!,
category: "settings",
action: "update",
targetType: "settings",
detail: { sections: Object.keys(parsed.data), changes: describeSettingsChanges(before, parsed.data) },
});
res.json({ settings: updated });
}));
settingsRouter.post("/test-gotify", requireRole("admin"), asyncHandler(async (req, res) => {
const schema = z.object({ url: z.string().min(1), token: z.string().min(1), priority: z.number().optional() });
const parsed = schema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
try {
await testGotify(parsed.data);
res.json({ ok: true });
} catch (err) {
res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
}
}));
settingsRouter.post("/test-ntfy", requireRole("admin"), asyncHandler(async (req, res) => {
const schema = z.object({ url: z.string().min(1), topic: z.string().min(1), token: z.string().optional(), priority: z.number().optional() });
const parsed = schema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
try {
await testNtfy(parsed.data);
res.json({ ok: true });
} catch (err) {
res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
}
}));
settingsRouter.post("/test-smtp", requireRole("admin"), asyncHandler(async (req, res) => {
const schema = z.object({
host: z.string().min(1),
port: z.number().optional(),
secure: z.boolean().optional(),
username: z.string().optional(),
password: z.string().optional(),
from: z.string().min(1),
to: z.string().min(1),
});
const parsed = schema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
try {
await testSmtp(parsed.data);
res.json({ ok: true });
} catch (err) {
res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
}
}));
settingsRouter.post("/test-webhook", requireRole("admin"), asyncHandler(async (req, res) => {
const schema = z.object({ url: z.string().min(1), secret: z.string().optional() });
const parsed = schema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
try {
await testWebhook(parsed.data);
res.json({ ok: true });
} catch (err) {
res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
}
}));
settingsRouter.post("/purge-logs", requireRole("admin"), asyncHandler(async (req, res) => {
const { logRetention } = await getSettings();
const result = await purgeOldLogs(logRetention.retentionDays);
await recordAudit({
actor: req.currentUser!,
category: "settings",
action: "purge_logs",
detail: { retentionDays: logRetention.retentionDays, ...result },
});
res.json(result);
}));
// What the weekly digest would say right now, so it can be read before it is switched on.
settingsRouter.get("/digest/preview", requireRole("admin"), asyncHandler(async (_req, res) => {
const digest = await buildDigest();
res.json({ title: digest.title, message: digest.message, quiet: digest.quiet, channels: await enabledChannelCount() });
}));
// Sends it now, through whatever channels are switched on, at whatever time it is.
settingsRouter.post("/digest/send", requireRole("admin"), asyncHandler(async (req, res) => {
const channels = await enabledChannelCount();
if (channels === 0) {
return res.status(400).json({ error: "no_channel", message: "No notification channel is switched on, so there is nowhere to send it. Set one up above first." });
}
const digest = await sendDigest({ immediately: true });
await recordAudit({ actor: req.currentUser!, category: "settings", action: "send_digest", detail: { channels, quiet: digest.quiet } });
res.json({ sent: true, channels });
}));
settingsRouter.get("/quiet-hours-queue", requireRole("admin"), asyncHandler(async (_req, res) => {
const items = await listQueuedNotifications();
res.json({ count: items.length, items });
}));
settingsRouter.post("/flush-quiet-hours", requireRole("admin"), asyncHandler(async (req, res) => {
const flushed = await flushQuietHoursQueue();
await recordAudit({ actor: req.currentUser!, category: "settings", action: "flush_quiet_hours", detail: { flushed } });
res.json({ flushed });
}));
const exportSchema = z.object({ passphrase: z.string().min(8) });
settingsRouter.post("/export", requireRole("admin"), asyncHandler(async (req, res) => {
const parsed = exportSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
const payload = await buildExportPayload();
const file = encryptExport(payload, parsed.data.passphrase);
await recordAudit({
actor: req.currentUser!,
category: "settings",
action: "export_config",
detail: { integrations: payload.integrations.length, dnsProviders: payload.dnsProviders.length },
});
res.json(file);
}));
const encryptedFileSchema = z.object({
app: z.literal("homelab-manager-backup"),
version: z.literal(1),
salt: z.string().min(1),
iv: z.string().min(1),
authTag: z.string().min(1),
ciphertext: z.string().min(1),
});
const importSchema = z.object({ passphrase: z.string().min(1), file: encryptedFileSchema });
settingsRouter.post("/import", requireRole("admin"), asyncHandler(async (req, res) => {
const parsed = importSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
let payload;
try {
payload = decryptExport(parsed.data.file as EncryptedExportFile, parsed.data.passphrase);
} catch {
return res.status(400).json({ error: "decrypt_failed", message: "Wrong passphrase, or the file is corrupted." });
}
if (!payload || typeof payload !== "object" || !Array.isArray(payload.integrations) || !Array.isArray(payload.dnsProviders) || !payload.settings) {
return res.status(400).json({ error: "invalid_payload", message: "Decrypted file doesn't look like a Homelab Manager backup." });
}
const result = await applyImportPayload(payload);
await recordAudit({
actor: req.currentUser!,
category: "settings",
action: "import_config",
detail: result,
});
res.json(result);
}));