Files
Homelab-manager/server/src/services/settingsStore.ts
T
bobbanandClaude Sonnet 5.5 43fc5e0272 Notification routing rules, per-browser push wishes, escalation of unacknowledged alerts
- Routing: rules pick channels by kind, severity and server tags (first match wins, none = nobody); mixed batches split per route; recoveries follow their alert; quiet-hours digest keeps each notification's audience
- Push: each subscribed browser can ask for a minimum severity and some kinds
- Escalation: up to three timed steps re-notify alerts nobody has acknowledged, through chosen channels and an optional extra email; an acknowledgement stops them
- Fix ntfy: titles with an em dash made every ntfy send fail (header not Latin-1); now RFC 2047 encoded

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-18 19:44:45 +02:00

435 lines
17 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { sql } from "drizzle-orm";
import { db } from "../db/client.js";
import { settings } from "../db/schema.js";
import { defaultThemes, type NameTheme } from "./nameThemes.js";
import type { EscalationSettings, RoutingSettings } from "./notifyRouting.js";
import { env } from "../env.js";
import { decryptSecret, encryptSecret } from "../crypto.js";
export interface GotifySettings {
enabled: boolean;
url: string;
token: string;
priority: number;
}
export interface NtfySettings {
enabled: boolean;
url: string;
topic: string;
token: string;
priority: number;
}
export interface SmtpSettings {
enabled: boolean;
host: string;
port: number;
secure: boolean;
username: string;
password: string;
from: string;
to: string;
}
export interface WebhookSettings {
enabled: boolean;
url: string;
secret: string;
}
/** Push notifications to phones and browsers that have subscribed (see services/webPush.ts). Who is subscribed is kept apart, per device. */
export interface WebPushSettings {
enabled: boolean;
/** Where a push service can reach whoever runs this: an email address or an https address (VAPID asks for one). Blank is fine. */
contact: string;
}
export type { RoutingSettings, EscalationSettings } from "./notifyRouting.js";
export interface NotificationEvents {
dnsAdd: boolean;
dnsUpdate: boolean;
dnsDelete: boolean;
secretCheck: boolean;
tailscaleKeyCheck: boolean;
dockerUpdateCheck: boolean;
proxmoxBackupCheck: boolean;
/** Daily reminder while a Proxmox Backup Server snapshot has failed verification, or a datastore couldn't be read at all. */
pbsVerificationCheck: boolean;
healthAlerts: boolean;
/** A Semaphore template or Gitea repo whose latest run failed, and when it succeeds again. */
automationAlerts: boolean;
/** How an update run started from the Updates page ended: what is still waiting, whether a restart is due, or why it failed. */
updateRunResults: boolean;
/** Daily reminder while a domain registration is close to expiring or has expired. */
domainExpiryCheck: boolean;
secretCheckTime: string; // "HH:MM" — shared by the secret-expiry, Tailscale key-expiry, Docker update, and Proxmox backup checks
timezone: string;
integrationFailureAlerts: boolean;
/** Consecutive failed calls (from the Diagnostic Log) before an integration/DNS provider is considered down. */
integrationFailureThreshold: number;
}
export type ProviderColors = Record<string, string>;
export type IntegrationColors = Record<string, string>;
export type DateFormat = "ymd" | "dmy" | "mdy";
export type TimeFormat = "24h" | "12h";
export interface DisplaySettings {
dateFormat: DateFormat;
timeFormat: TimeFormat;
/** Rows per page for every paginated table in the app. */
pageSize: number;
}
export interface LogRetentionSettings {
enabled: boolean;
/** Diagnostic log and audit log entries older than this are deleted. */
retentionDays: number;
/** How often the purge job runs, in hours. */
intervalHours: number;
}
export interface QuietHoursSettings {
enabled: boolean;
/** "HH:MM", local to notifications.timezone. Notifications from `start` to `end` are queued, not sent immediately. */
start: string;
/** "HH:MM" — when `start`..`end` wraps past midnight (e.g. 22:00 -> 07:00), the queue is flushed as one digest at this time. */
end: string;
}
export interface HealthCheckSettings {
/** A server whose agent hasn't reported for this long is considered offline (agent default interval is 15 min). */
serverOfflineMinutes: number;
/** Disk / storage / volume usage at or above this percentage is reported. */
diskUsagePercent: number;
/** A domain registration expiring within this many days is reminded about daily (same schedule as secret expiry). */
domainWarnDays: number;
/** An agent-reported disk that is on course to be full within this many days is flagged on the Alerts page. 0 turns it off. */
diskForecastDays: number;
/** A Proxmox guest whose newest backup is older than this many hours is raised as stale. 0 turns it off. */
backupStaleHours: number;
}
/** The weekly digest: one message a week through the notification channels. Off until an admin switches it on under Settings → Notifications. */
export interface DigestSettings {
enabled: boolean;
/** 0 = Sunday … 6 = Saturday, in notifications.timezone. */
day: number;
/** "HH:MM", in notifications.timezone. */
time: string;
}
/** How roles are decided at sign-in: by hand on the Users page (the default), or from the groups the identity provider reports. */
export interface SignInSettings {
roleFromGroups: boolean;
/** The claim that carries the groups; "groups" in Authentik. */
groupsClaim: string;
adminGroups: string[];
operatorGroups: string[];
/** Someone in none of the named groups gets viewer, or keeps what they have. */
otherwise: "viewer" | "keep";
}
/** How the agents out on the servers are kept up to date. Off until an administrator turns it on. */
export interface AgentSettings {
/** An agent that is behind downloads the newer script from this app, checks it and replaces itself. */
autoUpdate: boolean;
}
/** The daily backup of Homelab Manager's own database (see services/selfBackup.ts). On unless an administrator turns it off. */
export interface SelfBackupSettings {
enabled: boolean;
/** "HH:MM", in the notification time zone. */
time: string;
/** How many of the daily backups are kept; the oldest beyond that are deleted. */
keep: number;
}
/** What the inventory needs to work out a running cost. Without a price per kWh it shows draw but no cost. */
export interface InventorySettings {
/** A short name shown after amounts ("SEK", "kr", "$"); may be blank. */
currency: string;
pricePerKwh: number | null;
}
export interface ConsistencySettings {
/** CIDR ranges and single addresses the consistency report ignores entirely — e.g. Docker networks that repeat on many hosts. */
excludedRanges: string[];
}
export interface NameGeneratorSettings {
/** The lists the Generator picks server names from — edited under Settings → Names. */
themes: NameTheme[];
}
export type AlertTicketSeverity = "critical" | "warning" | "info";
/** Opening an osTicket ticket for an alert. Off until an admin sets it up under Settings → Alert tickets. */
export interface AlertTicketSettings {
enabled: boolean;
/** The osTicket integration whose API (address and key) is used. */
integrationId: number | null;
/** Which severities open a ticket. */
severities: AlertTicketSeverity[];
/** Which kinds of alert (the categories on the Alerts page). Empty means every kind. */
categories: string[];
/** Who the tickets appear to be from. osTicket needs both; the email is where staff replies would go. */
requesterName: string;
requesterEmail: string;
/** osTicket help topic and priority ids, if tickets should land somewhere other than its defaults. */
topicId: number | null;
priorityId: number | null;
/** Let osTicket send its own "new ticket" alert to staff, per its own settings. */
notifyStaff: boolean;
/** Problems already present when this is switched on: left alone ("ignore") or given tickets too ("ticket"). */
existingProblems: "ignore" | "ticket";
/** An alert must be there in this many checks in a row (15 minutes apart) before it opens a ticket, so a blip that fixes itself never does. */
confirmChecks: number;
/** More new alerts than this in one check become a single summary ticket instead of one each. */
summaryAbove: number;
/** An alert that clears and comes back within this many minutes is still the same problem, not a new ticket. */
reopenAfterMinutes: number;
}
export interface AppSettings {
gotify: GotifySettings;
ntfy: NtfySettings;
smtp: SmtpSettings;
webhook: WebhookSettings;
webPush: WebPushSettings;
/** Which channels hear which notifications. */
routing: RoutingSettings;
/** Re-notifying about alerts nobody has acknowledged. */
escalation: EscalationSettings;
notifications: NotificationEvents;
providerColors: ProviderColors;
integrationColors: IntegrationColors;
display: DisplaySettings;
logRetention: LogRetentionSettings;
quietHours: QuietHoursSettings;
healthChecks: HealthCheckSettings;
digest: DigestSettings;
signIn: SignInSettings;
inventory: InventorySettings;
selfBackup: SelfBackupSettings;
agents: AgentSettings;
consistency: ConsistencySettings;
nameGenerator: NameGeneratorSettings;
alertTickets: AlertTicketSettings;
}
const DEFAULTS: AppSettings = {
gotify: { enabled: false, url: "", token: "", priority: 5 },
ntfy: { enabled: false, url: "https://ntfy.sh", topic: "", token: "", priority: 3 },
smtp: { enabled: false, host: "", port: 587, secure: false, username: "", password: "", from: "", to: "" },
webhook: { enabled: false, url: "", secret: "" },
webPush: { enabled: false, contact: "" },
routing: { rules: [] },
escalation: { enabled: false, steps: [] },
notifications: {
dnsAdd: true,
dnsUpdate: true,
dnsDelete: true,
secretCheck: true,
tailscaleKeyCheck: true,
dockerUpdateCheck: true,
proxmoxBackupCheck: true,
pbsVerificationCheck: true,
healthAlerts: true,
automationAlerts: true,
updateRunResults: true,
domainExpiryCheck: true,
secretCheckTime: "08:00",
timezone: "UTC",
integrationFailureAlerts: true,
integrationFailureThreshold: 3,
},
providerColors: {},
integrationColors: {},
display: { dateFormat: "ymd", timeFormat: "24h", pageSize: 20 },
logRetention: { enabled: false, retentionDays: 90, intervalHours: 24 },
quietHours: { enabled: false, start: "22:00", end: "07:00" },
digest: { enabled: false, day: 1, time: "08:00" },
inventory: { currency: "", pricePerKwh: null },
agents: { autoUpdate: false },
selfBackup: { enabled: true, time: "03:30", keep: 14 },
signIn: { roleFromGroups: false, groupsClaim: "groups", adminGroups: [], operatorGroups: [], otherwise: "viewer" },
healthChecks: { serverOfflineMinutes: 60, diskUsagePercent: 90, domainWarnDays: 30, diskForecastDays: 14, backupStaleHours: 48 },
// Docker's default bridge (172.17.0.0/16) and the pool it hands custom networks from (172.18–31) live here, and every
// Docker host repeats them. Shown on the Consistency page, where it can be removed if 172.16/12 is used as a real LAN.
consistency: { excludedRanges: ["172.16.0.0/12"] },
nameGenerator: { themes: defaultThemes() },
alertTickets: {
enabled: false,
integrationId: null,
severities: ["critical", "warning"],
categories: [],
requesterName: "Homelab Manager",
requesterEmail: "",
topicId: null,
priorityId: null,
notifyStaff: true,
existingProblems: "ignore",
confirmChecks: 2,
summaryAbove: 5,
reopenAfterMinutes: 60,
},
};
const KEYS = Object.keys(DEFAULTS) as (keyof AppSettings)[];
// ─── Encrypting the notification channels' credentials ─────────────────────────────────────
//
// A Gotify/ntfy token, the SMTP password and the webhook secret are stored encrypted with the same key as integration
// credentials (CREDENTIALS_ENCRYPTION_KEY). Everything above this file sees them as plain text — they're opened when
// settings are read and sealed when they're written — so nothing else needs to know. An encrypted value is marked
// with a prefix, which is how a value saved before this existed (plain text) is told apart and picked up later.
const SECRET_FIELDS: Partial<Record<keyof AppSettings, string[]>> = {
gotify: ["token"],
ntfy: ["token"],
smtp: ["password"],
webhook: ["secret"],
};
const ENCRYPTED_PREFIX = "enc:v1:";
const warnedUnreadable = new Set<string>();
/** Plain text in, the stored form out. Without a key configured the value is stored as it always was. */
function sealValue(plain: unknown): unknown {
if (typeof plain !== "string" || plain === "" || !env.credentialsEncryptionEnabled) return plain;
return ENCRYPTED_PREFIX + encryptSecret(plain);
}
/** The stored form in, plain text out. Anything not marked as encrypted is a legacy plain value and passes through. */
function openValue(section: string, field: string, stored: unknown): unknown {
if (typeof stored !== "string" || !stored.startsWith(ENCRYPTED_PREFIX)) return stored;
try {
return decryptSecret(stored.slice(ENCRYPTED_PREFIX.length));
} catch {
// The key was changed or removed. An empty credential is the honest result; shout once so it isn't a silent mystery.
const name = `${section}.${field}`;
if (!warnedUnreadable.has(name)) {
warnedUnreadable.add(name);
console.warn(`Can't decrypt the stored ${name} — CREDENTIALS_ENCRYPTION_KEY has changed or is missing. Enter it again under Settings → Notifications.`);
}
return "";
}
}
function transformSecrets(section: string, value: Record<string, unknown>, fn: (field: string, v: unknown) => unknown): Record<string, unknown> {
const fields = SECRET_FIELDS[section as keyof AppSettings];
if (!fields) return value;
const out = { ...value };
for (const field of fields) if (field in out) out[field] = fn(field, out[field]);
return out;
}
/**
* The stored form of a section about to be written. A credential this edit sets is sealed. One it doesn't touch keeps
* its stored value as it is when that's already encrypted — even if it can't be read right now (wrong or missing key), so
* an unrelated edit, like a new Gotify address, can't overwrite it with the empty value it reads back as.
*/
async function sealSection(section: string, merged: Record<string, unknown>, patch: Record<string, unknown>): Promise<Record<string, unknown>> {
const fields = SECRET_FIELDS[section as keyof AppSettings];
if (!fields) return merged;
const [row] = await db.select().from(settings).where(sql`${settings.key} = ${section}`).limit(1);
let stored: Record<string, unknown> = {};
try {
stored = row ? JSON.parse(row.value) : {};
} catch {
stored = {};
}
const out = { ...merged };
for (const field of fields) {
const previous = stored[field];
if (field in patch) out[field] = sealValue(patch[field]);
else if (typeof previous === "string" && previous.startsWith(ENCRYPTED_PREFIX)) out[field] = previous;
else out[field] = sealValue(merged[field]);
}
return out;
}
/**
* Encrypts any credential still stored as plain text. Run once at startup, so an existing install is converted by
* upgrading and restarting — no one has to re-save anything. Safe to run every time; it only touches what isn't encrypted.
*/
export async function encryptStoredSettingsSecrets(): Promise<number> {
if (!env.credentialsEncryptionEnabled) return 0;
let converted = 0;
const rows = await db.select().from(settings);
for (const row of rows) {
const fields = SECRET_FIELDS[row.key as keyof AppSettings];
if (!fields) continue;
let parsed: Record<string, unknown>;
try {
parsed = JSON.parse(row.value);
} catch {
continue;
}
const needs = fields.some((f) => typeof parsed[f] === "string" && parsed[f] !== "" && !(parsed[f] as string).startsWith(ENCRYPTED_PREFIX));
if (!needs) continue;
const sealed = transformSecrets(row.key, parsed, (_f, v) => (typeof v === "string" && v !== "" && !v.startsWith(ENCRYPTED_PREFIX) ? sealValue(v) : v));
await db.update(settings).set({ value: JSON.stringify(sealed) }).where(sql`${settings.key} = ${row.key}`);
converted++;
}
return converted;
}
export async function getSettings(): Promise<AppSettings> {
const rows = await db.select().from(settings);
const byKey = new Map(rows.map((r) => [r.key, r.value]));
const result = {} as AppSettings;
for (const key of KEYS) {
const raw = byKey.get(key);
let parsed: Record<string, unknown> = {};
if (raw) {
try {
parsed = JSON.parse(raw);
} catch {
parsed = {};
}
}
(result[key] as Record<string, unknown>) = {
...(DEFAULTS[key] as object),
...transformSecrets(key, parsed, (field, v) => openValue(key, field, v)),
};
}
return result;
}
export type AppSettingsPatch = { [K in keyof AppSettings]?: Partial<AppSettings[K]> };
export async function updateSettings(partial: AppSettingsPatch): Promise<AppSettings> {
const current = await getSettings();
for (const key of Object.keys(partial) as (keyof AppSettings)[]) {
if (!KEYS.includes(key)) continue;
const patch = partial[key] as Record<string, unknown>;
const merged = { ...(current[key] as object), ...patch } as Record<string, unknown>;
const value = JSON.stringify(await sealSection(key, merged, patch));
await db
.insert(settings)
.values({ key, value })
.onConflictDoUpdate({ target: settings.key, set: { value, updatedAt: sql`(current_timestamp)` } });
}
return getSettings();
}
/** Small internal key/value slot for scheduler bookkeeping, outside the AppSettings shape. */
export async function getInternalFlag(key: string): Promise<string | null> {
const [row] = await db.select().from(settings).where(sql`${settings.key} = ${`_internal:${key}`}`).limit(1);
return row?.value ?? null;
}
export async function setInternalFlag(key: string, value: string): Promise<void> {
const fullKey = `_internal:${key}`;
await db
.insert(settings)
.values({ key: fullKey, value })
.onConflictDoUpdate({ target: settings.key, set: { value, updatedAt: sql`(current_timestamp)` } });
}