Files
Homelab-manager/server/src/routes/settings.ts
T
bobbanandClaude Sonnet 5.5 73a06ebe63 Flapping alerts, a noise report and bulk actions with undo
Flapping: an alert raised three times within an hour is announced once as
flapping, its further raise/clear messages are held until it has been calm
for an hour, and one message then says whether it is still active. Event
webhooks still hear everything. The state survives restarts.

Alerts > Noise lists the alerts that keep coming back (7-180 days): how often,
how long, most in an hour, and a hint on what helps.

Bulk actions on Alerts (acknowledge, remove acknowledgement, silence), Servers
(tag, silence, runs on) and Inventory (location and dates, print labels). Each
reports what it left alone and why, and has an Undo on the toast.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-19 23:55:09 +02:00

375 lines
15 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) })
.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(),
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(), 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);
}));