Files
Homelab-manager/server/src/services/settingsStore.ts
T
bobbanandClaude Sonnet 5.5 396e074108 UniFi integration: network devices, Wi-Fi and networks, as part of the dependency map
A UniFi controller (API key on Network 9+, or a read-only local login on any
version) is read every five minutes. Its switches, access points and gateways
are kept with state, IP, uptime, firmware and uplink; its networks and Wi-Fi
names beside them (passphrases are never read). Nothing is written to the
controller.

Network > Network devices lists them. Devices are a new node type in the
dependency map: uplinks become dependencies by themselves, others can be
written by hand. A device offline past a limit is an offline alert, folds what
depends on it, can be silenced with maintenance and have runbooks.

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

467 lines
19 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;
/** A restore test older than this many days (or none at all) is a problem for a guest that has backups; 0 = never (a failed test always is). */
restoreTestDays: number;
/** A server that starts listening on a TCP port it did not at first, and that is not noted on its Ports card, is a warning (services/newPorts.ts). */
newPortAlerts: boolean;
/** An alert raised this many times within an hour is "flapping": one message says so and its further raised/cleared messages are held until it has been quiet for an hour. 0 turns it off. */
flapRaises: number;
/** A network device (switch, access point, gateway) that a UniFi controller has not seen online for this many minutes is raised as offline. */
deviceOfflineMinutes: number;
}
/** The monthly report: last month's availability, incidents, updates and renewals, in one message on a day of the month. Off until switched on. */
export interface MonthlyReportSettings {
enabled: boolean;
/** Day of the month, 1–28 (every month has it), in notifications.timezone. */
day: number;
/** "HH:MM", in notifications.timezone. */
time: string;
}
/** 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";
}
/**
* Where people's profile pictures may come from. Both are off until an administrator turns them on, because each means this server asks an
* outside address for a picture (Gravatar is told a hash of the person's email). The browser never does: pictures are fetched and kept by the server.
*/
export interface ProfilePictureSettings {
/** gravatar.com, by a hash of the person's email address. */
gravatar: boolean;
/** The picture the identity provider (Authentik) names for the person in its "picture" claim. */
identityProvider: boolean;
}
/** 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 → Notifications → 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;
monthlyReport: MonthlyReportSettings;
signIn: SignInSettings;
profilePictures: ProfilePictureSettings;
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" },
monthlyReport: { enabled: false, day: 1, time: "08:00" },
inventory: { currency: "", pricePerKwh: null },
agents: { autoUpdate: false },
selfBackup: { enabled: true, time: "03:30", keep: 14 },
profilePictures: { gravatar: false, identityProvider: false },
signIn: { roleFromGroups: false, groupsClaim: "groups", adminGroups: [], operatorGroups: [], otherwise: "viewer" },
healthChecks: { serverOfflineMinutes: 60, diskUsagePercent: 90, domainWarnDays: 30, diskForecastDays: 14, backupStaleHours: 48, restoreTestDays: 0, newPortAlerts: true, flapRaises: 3, deviceOfflineMinutes: 10 },
// 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)` } });
}