Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
fae7089448 | ||
|
|
f246410f24 | ||
|
|
86dfa9ae2e |
No files matched your search
+4
-3
@@ -5,9 +5,10 @@ APP_BASE_URL=https://homelab.example.lan
|
|||||||
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||||
SESSION_SECRET=change-me-to-a-random-64-char-hex-string
|
SESSION_SECRET=change-me-to-a-random-64-char-hex-string
|
||||||
|
|
||||||
# 32-byte (64 hex char) key used to encrypt stored integration API tokens at
|
# 32-byte (64 hex char) key used to encrypt stored integration API tokens, and the
|
||||||
# rest (AES-256-GCM). Generate the same way as SESSION_SECRET. Losing/changing
|
# notification channels' credentials (Gotify/ntfy tokens, SMTP password, webhook
|
||||||
# this key makes previously-stored integration credentials unreadable.
|
# secret), at rest (AES-256-GCM). Generate the same way as SESSION_SECRET.
|
||||||
|
# Losing/changing this key makes those stored credentials unreadable.
|
||||||
CREDENTIALS_ENCRYPTION_KEY=change-me-to-a-random-64-char-hex-string
|
CREDENTIALS_ENCRYPTION_KEY=change-me-to-a-random-64-char-hex-string
|
||||||
|
|
||||||
# Port docker-compose publishes on the host (container always listens on 3000).
|
# Port docker-compose publishes on the host (container always listens on 3000).
|
||||||
|
|||||||
+553
@@ -0,0 +1,553 @@
|
|||||||
|
# Database schema
|
||||||
|
|
||||||
|
Homelab Manager keeps its data in one SQLite file, accessed through
|
||||||
|
[drizzle-orm](https://orm.drizzle.team) and the libSQL client. The schema is
|
||||||
|
defined in one place — [`server/src/db/schema.ts`](server/src/db/schema.ts) —
|
||||||
|
and this document describes it. It was checked against a fresh database built
|
||||||
|
from the migrations, so the tables, columns, foreign keys and indexes below are
|
||||||
|
what the app actually creates.
|
||||||
|
|
||||||
|
- [The basics](#the-basics)
|
||||||
|
- [How the tables relate](#how-the-tables-relate)
|
||||||
|
- [Tables](#tables)
|
||||||
|
- [What's stored inside the JSON columns](#whats-stored-inside-the-json-columns)
|
||||||
|
- [Settings keys](#settings-keys)
|
||||||
|
- [What happens on delete](#what-happens-on-delete)
|
||||||
|
- [The Proxmox link's foreign key](#the-proxmox-links-foreign-key)
|
||||||
|
- [Retention and backups](#retention-and-backups)
|
||||||
|
- [Changing the schema](#changing-the-schema)
|
||||||
|
|
||||||
|
## The basics
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
|
||||||
|
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
|
||||||
|
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0014`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
|
||||||
|
| **Tables** | 21 application tables, plus drizzle's own `__drizzle_migrations`. |
|
||||||
|
|
||||||
|
**Not in the database:**
|
||||||
|
|
||||||
|
- **Login sessions** are files in `SESSION_DIR` (default `../data/sessions`), not rows.
|
||||||
|
- **The encryption key** for integration credentials (`CREDENTIALS_ENCRYPTION_KEY`) and the session secret live in the environment, never in the file.
|
||||||
|
- **Agent tokens** are never stored: only a SHA-256 hash and a short prefix of each (`servers.api_token_hash`, `api_token_prefix`). The token itself is shown once, when the server is registered.
|
||||||
|
|
||||||
|
### Conventions
|
||||||
|
|
||||||
|
- **Primary keys** are `INTEGER PRIMARY KEY AUTOINCREMENT` named `id` — except `settings`, which uses its text `key`.
|
||||||
|
- **Booleans** are `INTEGER` 0/1 (shown as `bool` below).
|
||||||
|
- **Timestamps are text, in two formats**, so read them with care:
|
||||||
|
- Columns the database fills in itself (`created_at`, and most `updated_at`) use SQLite's `current_timestamp`: `2026-10-03 14:05:09`, **UTC, with no zone marker**. Treat it as UTC, not local time.
|
||||||
|
- Columns the app fills in (`last_seen_at`, `last_login_at`, `synced_at`, `last_checked_at`, …) use ISO 8601: `2026-10-03T14:05:09.123Z`.
|
||||||
|
- Dates without a time (`secrets.expiry_date`, `domains.expires_at`) are `YYYY-MM-DD`.
|
||||||
|
- **JSON columns** are `TEXT` holding JSON; see [what's inside](#whats-stored-inside-the-json-columns).
|
||||||
|
- **Enumerations** (roles, types) are plain text — SQLite doesn't enforce the allowed values; the app does.
|
||||||
|
- **Indexes:** besides primary keys, the only indexes are the unique ones listed per table. There are no secondary indexes; the data sets here (hundreds to a few thousand rows) don't need them.
|
||||||
|
|
||||||
|
## How the tables relate
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
erDiagram
|
||||||
|
users ||--o{ audit_log : "actor (set null)"
|
||||||
|
integration_credentials ||--o{ integrations : "credential (set null)"
|
||||||
|
integration_credentials ||--o{ dns_providers : "credential (set null)"
|
||||||
|
dns_providers ||--o{ dns_zones_cache : "cascade"
|
||||||
|
dns_providers ||--o{ dns_records_cache : "cascade"
|
||||||
|
servers ||--o{ scheduled_tasks : "cascade"
|
||||||
|
servers ||--o{ server_links : "cascade"
|
||||||
|
servers ||--o{ server_ports : "cascade"
|
||||||
|
servers ||--o{ port_forwards : "optional (set null)"
|
||||||
|
integrations ||--o{ servers : "proxmox link (app clears it)"
|
||||||
|
```
|
||||||
|
|
||||||
|
Eight tables stand alone, with no foreign keys: `settings`, `secrets`,
|
||||||
|
`ipam_entries`, `domains`, `diag_log`, `notification_queue`,
|
||||||
|
`consistency_ignores`, `tag_definitions`. `maintenance_windows` also has no
|
||||||
|
foreign key — see [soft references](#soft-references-not-foreign-keys).
|
||||||
|
|
||||||
|
## Tables
|
||||||
|
|
||||||
|
Grouped by what they're for. "Null" in the notes means the column allows NULL;
|
||||||
|
everything not marked **NOT NULL** may be empty.
|
||||||
|
|
||||||
|
### People and activity
|
||||||
|
|
||||||
|
#### `users`
|
||||||
|
|
||||||
|
Everyone who has signed in through Authentik. The first one becomes admin.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `oidc_sub` | text NOT NULL, **unique** | The user's stable ID from Authentik (`sub` claim). This is what a session is matched against. |
|
||||||
|
| `email`, `name` | text | From the sign-in; may be empty. |
|
||||||
|
| `role` | text NOT NULL, default `viewer` | `admin` \| `operator` \| `viewer`. |
|
||||||
|
| `created_at` | text NOT NULL | SQLite UTC. |
|
||||||
|
| `last_login_at` | text | ISO. |
|
||||||
|
|
||||||
|
#### `audit_log`
|
||||||
|
|
||||||
|
Who changed what. Written by the app on every change (see
|
||||||
|
[ROLES.md](ROLES.md) for who can read it).
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
|
||||||
|
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
|
||||||
|
| `category` | text NOT NULL | Free text. In use: `server`, `integration`, `dns`, `settings`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`. |
|
||||||
|
| `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. |
|
||||||
|
| `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. |
|
||||||
|
| `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. |
|
||||||
|
| `created_at` | text NOT NULL | SQLite UTC. |
|
||||||
|
|
||||||
|
#### `diag_log`
|
||||||
|
|
||||||
|
One row per outbound call to an integration or DNS provider — the source of
|
||||||
|
the Diagnostic Log page and of the "integration down" alert.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `source` | text NOT NULL | The integration/provider type, e.g. `proxmox`, `cloudflare`. |
|
||||||
|
| `operation` | text NOT NULL | The adapter method, e.g. `listZones`. |
|
||||||
|
| `ok` | bool NOT NULL | |
|
||||||
|
| `latency_ms` | integer NOT NULL | |
|
||||||
|
| `error` | text | Message when `ok` is false. |
|
||||||
|
| `created_at` | text NOT NULL | SQLite UTC. |
|
||||||
|
|
||||||
|
#### `notification_queue`
|
||||||
|
|
||||||
|
Notifications held back during quiet hours, delivered as one digest and then
|
||||||
|
cleared.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `title`, `message` | text NOT NULL | |
|
||||||
|
| `created_at` | text NOT NULL | SQLite UTC. |
|
||||||
|
|
||||||
|
#### `maintenance_windows`
|
||||||
|
|
||||||
|
While a window is open, alerts about its target are silenced. An end time is
|
||||||
|
required, so a forgotten window can't silence real problems forever.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `target_type` | text NOT NULL | `server` \| `integration` \| `dns_provider`. |
|
||||||
|
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; a window whose target was deleted is simply ignored. |
|
||||||
|
| `reason` | text | |
|
||||||
|
| `started_at`, `ends_at` | text NOT NULL | ISO. |
|
||||||
|
| `created_by` | text | Name of the person who opened it. |
|
||||||
|
|
||||||
|
### Servers
|
||||||
|
|
||||||
|
#### `servers`
|
||||||
|
|
||||||
|
A machine that reports in through the agent (or is registered by hand), plus
|
||||||
|
what it last reported.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `name` | text NOT NULL | Not unique. |
|
||||||
|
| `hostname` | text | |
|
||||||
|
| `os_type` | text NOT NULL, default `linux` | |
|
||||||
|
| `description` | text | |
|
||||||
|
| `api_token_hash` | text NOT NULL | SHA-256 of the agent's token. |
|
||||||
|
| `api_token_prefix` | text NOT NULL | First characters of the token, to tell tokens apart in the UI. |
|
||||||
|
| `created_at` | text NOT NULL | SQLite UTC. |
|
||||||
|
| `last_seen_at` | text | ISO; when the agent last reported. Drives "server offline". |
|
||||||
|
| `ip_addresses` | text | JSON `string[]`. Agent-reported. |
|
||||||
|
| `cpu_model` | text | Agent-reported. |
|
||||||
|
| `cpu_cores` | integer | |
|
||||||
|
| `cpu_load_percent` | real | Load average ÷ cores × 100 — an approximation, not instantaneous usage. |
|
||||||
|
| `mem_total_bytes`, `mem_used_bytes` | integer | |
|
||||||
|
| `disks` | text | JSON, see below. Agent-reported. |
|
||||||
|
| `listening_ports` | text | JSON, see below. What the agent sees bound on the host. |
|
||||||
|
| `last_port_scan` | text | JSON summary of the latest network scan *from this app*. |
|
||||||
|
| `tags` | text | JSON `string[]` of normalised tag names. |
|
||||||
|
| `proxmox_integration_id` | integer → `integrations.id` | The database has no `ON DELETE` rule here; the app clears the link itself — see [below](#the-proxmox-links-foreign-key). |
|
||||||
|
| `proxmox_node` | text | |
|
||||||
|
| `proxmox_guest_type` | text | `qemu` \| `lxc`. |
|
||||||
|
| `proxmox_vmid` | integer | The four `proxmox_*` columns are set together or cleared together (enforced by the API), by an admin — never by the agent. |
|
||||||
|
| `hide_proxmox_link` | bool NOT NULL, default 0 | Hides the "Proxmox link" card for servers that aren't Proxmox guests. Ignored while the server is actually linked. |
|
||||||
|
|
||||||
|
#### `scheduled_tasks`
|
||||||
|
|
||||||
|
Cron jobs, systemd timers and Windows tasks the agent found on a server, plus
|
||||||
|
tasks added by hand.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
|
||||||
|
| `schedule_type` | text NOT NULL | `cron` \| `systemd_timer` \| `windows_task` from agents; manual tasks may use others (`docker`, `backup`, `update`, `n8n_workflow`, `manual`). |
|
||||||
|
| `origin` | text NOT NULL, default `agent` | `agent` \| `manual`. Manual rows are never touched by agent sync. |
|
||||||
|
| `name` | text NOT NULL | |
|
||||||
|
| `command`, `schedule_expression`, `source` | text | |
|
||||||
|
| `enabled` | bool NOT NULL, default 1 | |
|
||||||
|
| `next_run_at` | text | |
|
||||||
|
| `raw_metadata` | text | JSON as the agent reported it. |
|
||||||
|
| `is_stale` | bool NOT NULL, default 0 | Set when the agent stops reporting the task. |
|
||||||
|
| `first_seen_at`, `last_seen_at` | text NOT NULL | SQLite UTC at first insert; later updates are written by the app. |
|
||||||
|
|
||||||
|
#### `server_links`
|
||||||
|
|
||||||
|
Admin-page bookmarks for a server (Dockge, Webmin, Cockpit, …). Shown on the
|
||||||
|
server's page and summarised under Operations → Admin Links.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
|
||||||
|
| `label`, `url` | text NOT NULL | |
|
||||||
|
| `created_at` | text NOT NULL | SQLite UTC. |
|
||||||
|
|
||||||
|
#### `server_ports`
|
||||||
|
|
||||||
|
A port on one server that's been seen open by a scan, or that someone wrote a
|
||||||
|
note about. Rows exist only while they carry information. What the *agent*
|
||||||
|
sees is stored on the server row instead (`servers.listening_ports`).
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
|
||||||
|
| `port` | integer NOT NULL | |
|
||||||
|
| `protocol` | text NOT NULL, default `tcp` | `tcp` \| `udp`. |
|
||||||
|
| `label`, `comment` | text | |
|
||||||
|
| `open` | bool NOT NULL, default 0 | True when the last scan connected to it. |
|
||||||
|
| `last_seen_open_at` | text | |
|
||||||
|
| `updated_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
Unique index **`server_ports_unique`** on (`server_id`, `port`, `protocol`).
|
||||||
|
|
||||||
|
#### `port_forwards`
|
||||||
|
|
||||||
|
Manually recorded port openings on something this app doesn't monitor — a
|
||||||
|
router's port forward, an edge firewall rule, a cloud security group. It
|
||||||
|
records them; it can't check or change them.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `label` | text NOT NULL | |
|
||||||
|
| `external_port` | integer NOT NULL | |
|
||||||
|
| `protocol` | text NOT NULL, default `tcp` | `tcp` \| `udp`. |
|
||||||
|
| `server_id` | integer → `servers.id`, **set null** | Optional: the tracked server it points at. |
|
||||||
|
| `destination` | text | Anything else — a bare IP, an untracked device — or detail alongside `server_id`. |
|
||||||
|
| `internal_port` | integer | When NAT changes the port. |
|
||||||
|
| `source` | text | Free text: where the rule lives ("Home router", "OPNsense WAN rule"). |
|
||||||
|
| `comment` | text | |
|
||||||
|
| `created_at`, `updated_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
### Integrations and credentials
|
||||||
|
|
||||||
|
#### `integrations`
|
||||||
|
|
||||||
|
A connected system: Proxmox, Synology, Semaphore, Tailscale, Gitea, Dockhand,
|
||||||
|
Uptime Kuma, phpIPAM, Proxmox Backup Server, osTicket.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `type` | text NOT NULL | `proxmox` \| `synology` \| `semaphore` \| `tailscale` \| `gitea` \| `dockhand` \| `uptimekuma` \| `phpipam` \| `pbs` \| `osticket`. |
|
||||||
|
| `name` | text NOT NULL | |
|
||||||
|
| `base_url` | text NOT NULL | For osTicket (a direct database connection) this holds the database host. |
|
||||||
|
| `credential_id` | integer → `integration_credentials.id`, **set null** | |
|
||||||
|
| `config` | text | JSON of the *non-secret* settings, see below. |
|
||||||
|
| `enabled` | bool NOT NULL, default 1 | |
|
||||||
|
| `created_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
#### `integration_credentials`
|
||||||
|
|
||||||
|
The secret half of an integration or DNS provider, encrypted at rest.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `name` | text NOT NULL | `"<type>:<name>"`, for recognising a row when looking at the file. |
|
||||||
|
| `encrypted_secret` | text NOT NULL | `iv:authTag:ciphertext`, each in hex — AES-256-GCM with `CREDENTIALS_ENCRYPTION_KEY`. The plaintext is a JSON object of the secret fields (an API token, a password). Without the same key it can't be read. |
|
||||||
|
| `created_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
The notification channels' credentials aren't in this table; they're encrypted in place in `settings` — see [Retention and backups](#retention-and-backups).
|
||||||
|
|
||||||
|
### DNS
|
||||||
|
|
||||||
|
#### `dns_providers`
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `provider_type` | text NOT NULL | `cloudflare` \| `loopia` \| `pihole` \| `azure` \| `cpanel` \| `technitium`. |
|
||||||
|
| `name` | text NOT NULL | |
|
||||||
|
| `credential_id` | integer → `integration_credentials.id`, **set null** | |
|
||||||
|
| `config` | text | JSON, non-secret provider config (base URL, zone list, …). |
|
||||||
|
| `enabled` | bool NOT NULL, default 1 | |
|
||||||
|
| `created_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
#### `dns_zones_cache` and `dns_records_cache`
|
||||||
|
|
||||||
|
Local copies of what the providers returned at the last sync, so pages load
|
||||||
|
without calling every provider. The providers remain the source of truth.
|
||||||
|
|
||||||
|
`dns_zones_cache`
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
|
||||||
|
| `zone_id` | text NOT NULL | The provider's own identifier for the zone. |
|
||||||
|
| `zone_name` | text NOT NULL | |
|
||||||
|
| `synced_at` | text | ISO. |
|
||||||
|
|
||||||
|
Unique index **`dns_zones_cache_provider_zone_idx`** on (`provider_id`, `zone_id`).
|
||||||
|
|
||||||
|
`dns_records_cache`
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
|
||||||
|
| `zone_id` | text NOT NULL | The provider's zone identifier — matches `dns_zones_cache.zone_id` for the same provider, but is **not a foreign key**. |
|
||||||
|
| `record_id` | text NOT NULL | The provider's own record identifier. |
|
||||||
|
| `type` | text NOT NULL | `A`, `AAAA`, `CNAME`, `TXT`, `MX`, … |
|
||||||
|
| `name`, `content` | text NOT NULL | |
|
||||||
|
| `ttl`, `priority` | integer | |
|
||||||
|
| `proxied` | bool | Cloudflare only. |
|
||||||
|
|
||||||
|
### Address and name tracking
|
||||||
|
|
||||||
|
#### `ipam_entries`
|
||||||
|
|
||||||
|
IP addresses with a label and notes, entered by hand or synced.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `ip_address` | text NOT NULL, **unique** | |
|
||||||
|
| `label`, `vendor`, `location`, `notes` | text | |
|
||||||
|
| `source` | text | Null = typed in by hand; otherwise the sync that created it: `tailscale`, `proxmox` or `phpipam`. A sync only updates rows it created itself and never overwrites a manual one. |
|
||||||
|
| `created_at`, `updated_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
#### `domains`
|
||||||
|
|
||||||
|
Registered domains whose expiry is tracked.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `name` | text NOT NULL, **unique** | The registrable domain, lowercase ASCII. |
|
||||||
|
| `origin` | text NOT NULL, default `manual` | `manual` (typed in) or `zone` (created from a synced DNS zone, removed again when the zone goes away). |
|
||||||
|
| `expires_at` | text | `YYYY-MM-DD`, as the registry reports it. Null for registries that don't publish one. |
|
||||||
|
| `registrar` | text | |
|
||||||
|
| `lookup_source` | text | `rdap` \| `whois`. |
|
||||||
|
| `last_checked_at` | text | Last attempt. |
|
||||||
|
| `last_checked_ok_at` | text | Last *successful* attempt. |
|
||||||
|
| `last_check_error` | text | |
|
||||||
|
| `created_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
#### `secrets`
|
||||||
|
|
||||||
|
The expiry tracker for API tokens, certificates, passwords and the like. It
|
||||||
|
tracks *when* something expires; it does not store the secret itself.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `name` | text NOT NULL | |
|
||||||
|
| `type` | text NOT NULL, default `generic` | `api_token` \| `ssl_certificate` \| `password` \| `generic`. |
|
||||||
|
| `description`, `notes` | text | |
|
||||||
|
| `expiry_date` | text NOT NULL | `YYYY-MM-DD`. For a certificate with a host to check, overwritten from the live certificate. |
|
||||||
|
| `warn_days` | integer NOT NULL, default 30 | How long before expiry to start reminding. |
|
||||||
|
| `check_host`, `check_port` | text / integer | Certificates only: read the expiry from the live certificate at this host:port. |
|
||||||
|
| `last_checked_at`, `last_check_error` | text | Result of the last live check. |
|
||||||
|
| `created_at`, `updated_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
### Housekeeping
|
||||||
|
|
||||||
|
#### `settings`
|
||||||
|
|
||||||
|
Key/value store for app settings. One row per settings section (the value is
|
||||||
|
JSON) plus a few internal bookkeeping rows. Details under
|
||||||
|
[Settings keys](#settings-keys).
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `key` | text PK | |
|
||||||
|
| `value` | text NOT NULL | JSON (or a plain date/time for internal flags). |
|
||||||
|
| `updated_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
#### `tag_definitions`
|
||||||
|
|
||||||
|
Tags themselves live on the servers that carry them (`servers.tags`). A row
|
||||||
|
here adds what a server can't: a tag that exists before anything uses it, and a
|
||||||
|
chosen colour. A tag with no row is simply one in use with an automatic colour.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `name` | text NOT NULL, **unique** | Normalised. |
|
||||||
|
| `color` | text | `#rrggbb`, or null for automatic. |
|
||||||
|
| `created_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
#### `consistency_ignores`
|
||||||
|
|
||||||
|
Consistency findings someone looked at and decided are fine.
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `id` | integer PK | |
|
||||||
|
| `key` | text NOT NULL, **unique** | The finding's stable key, so it stays ignored across runs. |
|
||||||
|
| `title` | text NOT NULL | What the finding said when it was ignored, so the list still reads sensibly after it's gone. |
|
||||||
|
| `reason`, `created_by` | text | |
|
||||||
|
| `created_at` | text NOT NULL | |
|
||||||
|
|
||||||
|
## What's stored inside the JSON columns
|
||||||
|
|
||||||
|
| Column | Shape |
|
||||||
|
|---|---|
|
||||||
|
| `servers.ip_addresses` | `["10.0.0.5", "fd00::5"]` |
|
||||||
|
| `servers.disks` | `[{ "mount": "/", "sizeBytes": 32000000000, "usedBytes": 9000000000 }]` |
|
||||||
|
| `servers.listening_ports` | `[{ "protocol": "tcp", "port": 22, "address": "0.0.0.0", "process": "sshd" }]` |
|
||||||
|
| `servers.last_port_scan` | `{ "at": "<ISO>", "address": "10.0.0.5", "from": 1, "to": 1024, "open": 3, "refused": 1010, "filtered": 11, "responded": true }` |
|
||||||
|
| `servers.tags` | `["prod", "media"]` |
|
||||||
|
| `audit_log.detail` | Free-form per action — e.g. `{ "name": "pve1" }`, or for settings `{ "sections": [...], "changes": { "<section>": { "<field>": { "from": …, "to": … } } } }`. For the notification channels (Gotify, ntfy, SMTP, webhook) only the field *names* that changed are recorded, never values. |
|
||||||
|
| `integrations.config` | The non-secret fields for that integration type (table below). |
|
||||||
|
| `dns_providers.config` | Non-secret provider settings (base URL, zone list, …). |
|
||||||
|
|
||||||
|
**`integrations.config` by type** (the secret fields go to `integration_credentials` instead):
|
||||||
|
|
||||||
|
| Type | In `config` | Encrypted separately |
|
||||||
|
|---|---|---|
|
||||||
|
| `proxmox` | `url`, `tokenId`, `insecure` | `tokenSecret` |
|
||||||
|
| `pbs` | `url`, `tokenId`, `insecure` | `tokenSecret` |
|
||||||
|
| `synology` | `url`, `username`, `insecure` | `password` |
|
||||||
|
| `semaphore`, `gitea`, `dockhand` | `url` | `token` |
|
||||||
|
| `tailscale` | `tailnet` | `apiKey` |
|
||||||
|
| `uptimekuma` | `url`, `username` | `password` (an API key, or the password on old installs) |
|
||||||
|
| `phpipam` | `url`, `appId`, `insecure` | `token` |
|
||||||
|
| `osticket` | `host`, `port`, `database`, `username`, `tablePrefix` | `password` |
|
||||||
|
|
||||||
|
## Settings keys
|
||||||
|
|
||||||
|
Each section is one row in `settings`, with a JSON object as its value. Fields
|
||||||
|
that were never changed aren't stored; the app fills in defaults when reading.
|
||||||
|
|
||||||
|
| Key | Holds |
|
||||||
|
|---|---|
|
||||||
|
| `gotify`, `ntfy`, `smtp`, `webhook` | The four notification channels: enabled, address, and credentials (token / password / secret). The credential fields are stored encrypted (prefix `enc:v1:`) — see [Retention and backups](#retention-and-backups). |
|
||||||
|
| `notifications` | Which events notify (`dnsAdd`, `healthAlerts`, …), the daily-reminder time (`secretCheckTime`, default `08:00`) and `timezone` (default `UTC`), and the integration-failure threshold (default 3). |
|
||||||
|
| `quietHours` | `enabled`, `start`, `end`. |
|
||||||
|
| `healthChecks` | `serverOfflineMinutes` (60), `diskUsagePercent` (90), `domainWarnDays` (30). |
|
||||||
|
| `logRetention` | `enabled`, `retentionDays` (90), `intervalHours` (24). |
|
||||||
|
| `display` | `dateFormat`, `timeFormat`, `pageSize`. |
|
||||||
|
| `providerColors`, `integrationColors` | Badge colours, by provider / integration type. |
|
||||||
|
| `consistency` | `excludedRanges` — addresses the Consistency and IP Addresses pages ignore. Default `["172.16.0.0/12"]` (Docker's networks). |
|
||||||
|
| `nameGenerator` | `themes` — the Generator's server-name lists: `[{ "id", "label", "names": [...], "lastImport"? }]`. Edited under Settings → Names. |
|
||||||
|
|
||||||
|
Rows whose key starts with **`_internal:`** are scheduler bookkeeping, not
|
||||||
|
settings, and aren't part of the app's settings object:
|
||||||
|
|
||||||
|
| Key | Value |
|
||||||
|
|---|---|
|
||||||
|
| `_internal:secretCheckLastRunDate`, `tailscaleKeyCheckLastRunDate`, `dockerUpdateCheckLastRunDate`, `proxmoxBackupCheckLastRunDate`, `pbsVerificationCheckLastRunDate` | The date a daily check last ran, so a restart doesn't repeat it (or skip it). |
|
||||||
|
| `_internal:logRetentionLastRunAt` | When the log purge last ran. |
|
||||||
|
| `_internal:healthActiveConditions`, `_internal:automationActiveConditions` | JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart. |
|
||||||
|
|
||||||
|
## What happens on delete
|
||||||
|
|
||||||
|
| Deleting… | Effect |
|
||||||
|
|---|---|
|
||||||
|
| a **server** | Its `scheduled_tasks`, `server_links` and `server_ports` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. |
|
||||||
|
| a **DNS provider** | Its cached zones and records are deleted. |
|
||||||
|
| an **integration** or **DNS provider** | The credential row it used is deleted by the app (not by the database). |
|
||||||
|
| an **integration credential** | The integration / provider using it keeps existing, with `credential_id` cleared. |
|
||||||
|
| a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. |
|
||||||
|
| a **Proxmox integration** that servers are linked to | Those servers keep existing and lose their Proxmox link (all four `proxmox_*` columns). The app does this before deleting; the database alone would refuse — see the next section. |
|
||||||
|
|
||||||
|
### Soft references (not foreign keys)
|
||||||
|
|
||||||
|
These point at other rows by ID or name without the database enforcing it, so
|
||||||
|
a stale value is possible and the app treats it as "nothing there":
|
||||||
|
|
||||||
|
- `maintenance_windows.target_id` (→ a server, integration or DNS provider, by `target_type`)
|
||||||
|
- `audit_log.target_id`
|
||||||
|
- `dns_records_cache.zone_id` (→ `dns_zones_cache.zone_id`, same provider)
|
||||||
|
- `servers.tags` (→ `tag_definitions.name`)
|
||||||
|
- `consistency_ignores.key`
|
||||||
|
|
||||||
|
## The Proxmox link's foreign key
|
||||||
|
|
||||||
|
`servers.proxmox_integration_id` is meant to clear itself when its integration
|
||||||
|
is deleted: `schema.ts` says `onDelete: "set null"`. The database doesn't do
|
||||||
|
that. Migration `0001` added the column as a plain
|
||||||
|
`REFERENCES integrations(id)`, and SQLite can't change a foreign key afterwards
|
||||||
|
without rebuilding the table, so the rule *in the database* is **no action**:
|
||||||
|
with foreign keys on, deleting an integration that a server points at is refused
|
||||||
|
with `FOREIGN KEY constraint failed`.
|
||||||
|
|
||||||
|
The app works around it rather than rebuilding the table. The delete route in
|
||||||
|
[`server/src/routes/integrations.ts`](server/src/routes/integrations.ts) first
|
||||||
|
clears the four `proxmox_*` columns on every server linked to that integration,
|
||||||
|
then deletes it, and the audit entry records how many servers were unlinked
|
||||||
|
(`unlinkedServers`). Deleting an integration therefore works whether or not
|
||||||
|
servers are linked to it. Anything that deletes integrations some other way —
|
||||||
|
a hand-written SQL statement, say — has to do the same first.
|
||||||
|
|
||||||
|
## Retention and backups
|
||||||
|
|
||||||
|
**Retention.** Only the two logs are trimmed: `audit_log` and `diag_log` entries
|
||||||
|
older than `logRetention.retentionDays` are deleted by the purge job (off by
|
||||||
|
default), and `notification_queue` is emptied each time the quiet-hours digest is
|
||||||
|
sent. Everything else stays until someone deletes it.
|
||||||
|
|
||||||
|
**Credentials at rest.** Integration and DNS provider credentials are
|
||||||
|
encrypted in `integration_credentials` (above). The notification channels'
|
||||||
|
credentials — the Gotify and ntfy tokens, the SMTP password and the webhook
|
||||||
|
secret — are in the `settings` rows, and are encrypted in place with the same key:
|
||||||
|
each is stored as `enc:v1:` followed by the same `iv:authTag:ciphertext` form, and the
|
||||||
|
rest of the row (URLs, topics, priorities) stays readable. The app decrypts them when
|
||||||
|
settings are read and encrypts them when they're written, so nothing else sees the
|
||||||
|
difference.
|
||||||
|
|
||||||
|
- A value saved by an older version (plain text) still works, and is encrypted the
|
||||||
|
next time the server starts.
|
||||||
|
- Without `CREDENTIALS_ENCRYPTION_KEY`, new notification credentials can only be
|
||||||
|
stored as plain text, and the server warns about it at startup. They are encrypted
|
||||||
|
at the next start once the key is set.
|
||||||
|
- If the key is changed or lost, the stored credentials can't be read: they show as
|
||||||
|
empty, and the server logs which ones. Enter them again under Settings →
|
||||||
|
Notifications. Editing a *different* field of the same channel meanwhile doesn't
|
||||||
|
overwrite the old ciphertext, so putting the right key back restores them.
|
||||||
|
|
||||||
|
Everything else in the file — IP addresses, hostnames, secret *names* and expiry
|
||||||
|
dates, the audit log — is readable by anyone who can read the file, so treat the
|
||||||
|
file and its backups as sensitive anyway.
|
||||||
|
|
||||||
|
**Backups.**
|
||||||
|
- **Settings → Backup** exports the settings, the integrations and the DNS
|
||||||
|
providers (with their credentials decrypted, then wrapped in a file encrypted
|
||||||
|
with a passphrase you choose). Importing merges the settings over the current ones, and adds
|
||||||
|
integrations and providers that don't exist yet (matched by type and name) — it never
|
||||||
|
overwrites an existing integration. It does **not** include servers, tasks,
|
||||||
|
secrets, IP addresses, domains, ports, tags, maintenance windows or logs.
|
||||||
|
- **A full backup** is a copy of the SQLite file, together with the value of
|
||||||
|
`CREDENTIALS_ENCRYPTION_KEY` — without that key the stored integration
|
||||||
|
credentials can't be decrypted. Copy the file while the app is stopped, or use
|
||||||
|
SQLite's `.backup` command, so you don't capture it mid-write.
|
||||||
|
|
||||||
|
## Changing the schema
|
||||||
|
|
||||||
|
1. Edit [`server/src/db/schema.ts`](server/src/db/schema.ts).
|
||||||
|
2. From the repo root run `npm run db:generate`; it writes a new numbered SQL
|
||||||
|
file to `server/drizzle/` (and updates `server/drizzle/meta/`).
|
||||||
|
3. Read the generated SQL. SQLite can add a column but can't change or drop a
|
||||||
|
foreign key, so some changes become a table rebuild — which is also why the
|
||||||
|
[Proxmox link](#the-proxmox-links-foreign-key) described above is the way it is.
|
||||||
|
4. Start the server (or run `npm run db:migrate`); the migration is applied and
|
||||||
|
recorded in `__drizzle_migrations`.
|
||||||
|
5. Commit the schema, the SQL file and the `meta/` changes together, and update
|
||||||
|
this document.
|
||||||
@@ -327,6 +327,11 @@ needs the site to be served over HTTPS (browsers only offer install on secure
|
|||||||
origins; `localhost` also counts). The bundled service worker deliberately
|
origins; `localhost` also counts). The bundled service worker deliberately
|
||||||
caches nothing, so an installed copy always shows the current build.
|
caches nothing, so an installed copy always shows the current build.
|
||||||
|
|
||||||
|
**More documentation**: [ROLES.md](ROLES.md) — who can see and do what;
|
||||||
|
[NOTIFICATIONS.md](NOTIFICATIONS.md) — every notification the app sends and when;
|
||||||
|
[INTEGRATIONS.md](INTEGRATIONS.md) — the credentials each integration needs;
|
||||||
|
[DATABASE.md](DATABASE.md) — the database tables, columns and relationships.
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
- Node.js 20+
|
- Node.js 20+
|
||||||
|
|||||||
@@ -224,7 +224,9 @@ export const servers = sqliteTable("servers", {
|
|||||||
lastPortScan: text("last_port_scan"), // JSON string: summary of the most recent network scan from this app
|
lastPortScan: text("last_port_scan"), // JSON string: summary of the most recent network scan from this app
|
||||||
tags: text("tags"), // JSON string: string[] — free-form labels for grouping and filtering, normalized by services/serverTags
|
tags: text("tags"), // JSON string: string[] — free-form labels for grouping and filtering, normalized by services/serverTags
|
||||||
|
|
||||||
// Optional link to a Proxmox VM/LXC — set by an admin, not the agent.
|
// Optional link to a Proxmox VM/LXC — set by an admin, not the agent. The "set null" below is what this file asks for,
|
||||||
|
// but migration 0001 created the column without it, so the database itself has no ON DELETE rule here: deleting an
|
||||||
|
// integration clears these columns in routes/integrations.ts instead. (See DATABASE.md.)
|
||||||
proxmoxIntegrationId: integer("proxmox_integration_id").references(() => integrations.id, {
|
proxmoxIntegrationId: integer("proxmox_integration_id").references(() => integrations.id, {
|
||||||
onDelete: "set null",
|
onDelete: "set null",
|
||||||
}),
|
}),
|
||||||
|
|||||||
+2
-1
@@ -29,7 +29,8 @@ export function warnIfAuthNotConfigured() {
|
|||||||
if (!env.credentialsEncryptionEnabled) {
|
if (!env.credentialsEncryptionEnabled) {
|
||||||
console.warn(
|
console.warn(
|
||||||
"CREDENTIALS_ENCRYPTION_KEY is not set to a 64-character hex string. " +
|
"CREDENTIALS_ENCRYPTION_KEY is not set to a 64-character hex string. " +
|
||||||
"Saving integration credentials (Proxmox/Synology/etc API tokens) will fail until it is configured.",
|
"Saving integration credentials (Proxmox/Synology/etc API tokens) will fail until it is configured, and the " +
|
||||||
|
"notification channels' credentials (Gotify/ntfy tokens, SMTP password, webhook secret) are stored unencrypted.",
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -8,6 +8,7 @@ import { mkdirSync, existsSync } from "node:fs";
|
|||||||
import { env, warnIfAuthNotConfigured } from "./env.js";
|
import { env, warnIfAuthNotConfigured } from "./env.js";
|
||||||
import { resolveDataPath } from "./paths.js";
|
import { resolveDataPath } from "./paths.js";
|
||||||
import { runMigrations } from "./db/migrate.js";
|
import { runMigrations } from "./db/migrate.js";
|
||||||
|
import { encryptStoredSettingsSecrets } from "./services/settingsStore.js";
|
||||||
import { authRouter } from "./auth/router.js";
|
import { authRouter } from "./auth/router.js";
|
||||||
import { meRouter } from "./routes/me.js";
|
import { meRouter } from "./routes/me.js";
|
||||||
import { usersRouter } from "./routes/users.js";
|
import { usersRouter } from "./routes/users.js";
|
||||||
@@ -42,6 +43,10 @@ import { initHealthScheduler } from "./services/healthScheduler.js";
|
|||||||
|
|
||||||
warnIfAuthNotConfigured();
|
warnIfAuthNotConfigured();
|
||||||
await runMigrations();
|
await runMigrations();
|
||||||
|
{
|
||||||
|
const converted = await encryptStoredSettingsSecrets();
|
||||||
|
if (converted > 0) console.log(`Encrypted the stored credentials of ${converted} notification channel${converted === 1 ? "" : "s"}.`);
|
||||||
|
}
|
||||||
await initSecretExpiryScheduler();
|
await initSecretExpiryScheduler();
|
||||||
await initTailscaleKeyExpiryScheduler();
|
await initTailscaleKeyExpiryScheduler();
|
||||||
await initLogRetentionScheduler();
|
await initLogRetentionScheduler();
|
||||||
|
|||||||
@@ -272,6 +272,14 @@ integrationsRouter.delete("/:id", requireRole("admin"), asyncHandler(async (req,
|
|||||||
return res.status(404).json({ error: "not_found" });
|
return res.status(404).json({ error: "not_found" });
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// servers.proxmox_integration_id was meant to clear itself, but the database only has a plain REFERENCES on it (see
|
||||||
|
// DATABASE.md), so a linked server would block the delete. Clear the whole link here — the four columns go together.
|
||||||
|
const unlinked = await db
|
||||||
|
.update(servers)
|
||||||
|
.set({ proxmoxIntegrationId: null, proxmoxNode: null, proxmoxGuestType: null, proxmoxVmid: null })
|
||||||
|
.where(eq(servers.proxmoxIntegrationId, id))
|
||||||
|
.returning({ id: servers.id });
|
||||||
|
|
||||||
await db.delete(integrations).where(eq(integrations.id, id));
|
await db.delete(integrations).where(eq(integrations.id, id));
|
||||||
if (existing.credentialId) {
|
if (existing.credentialId) {
|
||||||
await db.delete(integrationCredentials).where(eq(integrationCredentials.id, existing.credentialId));
|
await db.delete(integrationCredentials).where(eq(integrationCredentials.id, existing.credentialId));
|
||||||
@@ -283,7 +291,7 @@ integrationsRouter.delete("/:id", requireRole("admin"), asyncHandler(async (req,
|
|||||||
action: "delete",
|
action: "delete",
|
||||||
targetType: "integration",
|
targetType: "integration",
|
||||||
targetId: id,
|
targetId: id,
|
||||||
detail: { name: existing.name },
|
detail: { name: existing.name, ...(unlinked.length > 0 ? { unlinkedServers: unlinked.length } : {}) },
|
||||||
});
|
});
|
||||||
|
|
||||||
res.status(204).end();
|
res.status(204).end();
|
||||||
|
|||||||
@@ -2,6 +2,8 @@ import { sql } from "drizzle-orm";
|
|||||||
import { db } from "../db/client.js";
|
import { db } from "../db/client.js";
|
||||||
import { settings } from "../db/schema.js";
|
import { settings } from "../db/schema.js";
|
||||||
import { defaultThemes, type NameTheme } from "./nameThemes.js";
|
import { defaultThemes, type NameTheme } from "./nameThemes.js";
|
||||||
|
import { env } from "../env.js";
|
||||||
|
import { decryptSecret, encryptSecret } from "../crypto.js";
|
||||||
|
|
||||||
export interface GotifySettings {
|
export interface GotifySettings {
|
||||||
enabled: boolean;
|
enabled: boolean;
|
||||||
@@ -157,6 +159,102 @@ const DEFAULTS: AppSettings = {
|
|||||||
|
|
||||||
const KEYS = Object.keys(DEFAULTS) as (keyof AppSettings)[];
|
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> {
|
export async function getSettings(): Promise<AppSettings> {
|
||||||
const rows = await db.select().from(settings);
|
const rows = await db.select().from(settings);
|
||||||
const byKey = new Map(rows.map((r) => [r.key, r.value]));
|
const byKey = new Map(rows.map((r) => [r.key, r.value]));
|
||||||
@@ -172,7 +270,10 @@ export async function getSettings(): Promise<AppSettings> {
|
|||||||
parsed = {};
|
parsed = {};
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
(result[key] as Record<string, unknown>) = { ...(DEFAULTS[key] as object), ...parsed };
|
(result[key] as Record<string, unknown>) = {
|
||||||
|
...(DEFAULTS[key] as object),
|
||||||
|
...transformSecrets(key, parsed, (field, v) => openValue(key, field, v)),
|
||||||
|
};
|
||||||
}
|
}
|
||||||
return result;
|
return result;
|
||||||
}
|
}
|
||||||
@@ -184,8 +285,9 @@ export async function updateSettings(partial: AppSettingsPatch): Promise<AppSett
|
|||||||
|
|
||||||
for (const key of Object.keys(partial) as (keyof AppSettings)[]) {
|
for (const key of Object.keys(partial) as (keyof AppSettings)[]) {
|
||||||
if (!KEYS.includes(key)) continue;
|
if (!KEYS.includes(key)) continue;
|
||||||
const merged = { ...(current[key] as object), ...(partial[key] as object) };
|
const patch = partial[key] as Record<string, unknown>;
|
||||||
const value = JSON.stringify(merged);
|
const merged = { ...(current[key] as object), ...patch } as Record<string, unknown>;
|
||||||
|
const value = JSON.stringify(await sealSection(key, merged, patch));
|
||||||
await db
|
await db
|
||||||
.insert(settings)
|
.insert(settings)
|
||||||
.values({ key, value })
|
.values({ key, value })
|
||||||
|
|||||||
@@ -195,8 +195,11 @@ export default function Privacy() {
|
|||||||
<td>Until deleted.</td>
|
<td>Until deleted.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>Integration and DNS credentials</td>
|
<td>Integration, DNS and notification credentials</td>
|
||||||
<td>API tokens and passwords, encrypted (AES-256-GCM) with a key held in the server's environment, not in the database.</td>
|
<td>
|
||||||
|
API tokens and passwords — including the Gotify/ntfy tokens, SMTP password and webhook secret — encrypted (AES-256-GCM) with a key held in
|
||||||
|
the server's environment, not in the database. (If that key isn't set, notification credentials are kept unencrypted and the server says so at startup.)
|
||||||
|
</td>
|
||||||
<td>Until deleted. Settings → Backup exports include them, encrypted with a passphrase you choose.</td>
|
<td>Until deleted. Settings → Backup exports include them, encrypted with a passphrase you choose.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|||||||
Reference in new issue
Block a user