- 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>
435 lines
17 KiB
TypeScript
435 lines
17 KiB
TypeScript
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)` } });
|
||
}
|