From 18880a82860fb2ed4599926d19a5cb2877501b9b Mon Sep 17 00:00:00 2001 From: mixeme Date: Sun, 9 Aug 2026 00:49:43 +0300 Subject: [PATCH] docs: spell out .spbk and .spde extensions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SelfPost backup / SelfPost domain export — in the guide, security notes, architecture, and Backup/Export panel copy. Co-Authored-By: Composer Co-authored-by: Cursor --- CHANGELOG.md | 3 +++ docs/architecture.md | 8 ++++---- docs/guide.md | 7 +++++-- docs/security.md | 7 ++++--- internal/web/templates/backup.html | 10 ++++++---- internal/web/templates/domain_detail.html | 2 +- internal/web/templates/encrypt_fields.html | 7 ++++--- 7 files changed, 27 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db64c0a..18f9b51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -51,6 +51,9 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version ### Changed +- Document what `.spbk` and `.spde` stand for (SelfPost backup / SelfPost domain + export) in the operator guide, security notes, architecture, and the Backup / + Export panel copy. - Docs aligned with the code: setup URL is `/setup/` (README and guide; local trial rewrites the printed `https:///…` link to `http://127.0.0.1:8080/…`); domain import uses the file extension / magic diff --git a/docs/architecture.md b/docs/architecture.md index 353b039..afa414f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -290,10 +290,10 @@ restore. Stopped-container `tar` of `./data` is safe (see guide). ([internal/secretfile](../internal/secretfile/secretfile.go)): password → scrypt → AES-256-GCM over 64 KiB chunks, each authenticated with the header, its counter and an end-of-stream flag (so truncation and reordering fail to -open). Full backup `.tar.gz` → `.spbk`, domain export `.json` → `.spde`; the -plain forms remain the default. Domain import detects the envelope by magic -bytes; an encrypted full backup is converted back with `selfpost-backup --decrypt` before restore. +open). Full backup `.tar.gz` → `.spbk` (SelfPost backup), domain export +`.json` → `.spde` (SelfPost domain export); the plain forms remain the +default. Domain import detects the envelope by magic bytes; an encrypted full +backup is converted back with `selfpost-backup -decrypt` before restore. --- diff --git a/docs/guide.md b/docs/guide.md index 1228062..d06b043 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -332,8 +332,11 @@ file that comes down is an encrypted envelope instead of the plain archive: | Artefact | Plain | Encrypted | |----------|-------|-----------| -| Full backup | `.tar.gz` | `.spbk` | -| Domain export | `.json` | `.spde` | +| Full backup | `.tar.gz` | `.spbk` (**S**elf**P**ost **b**ac**k**up) | +| Domain export | `.json` | `.spde` (**S**elf**P**ost **d**omain **e**xport) | + +The suffixes are for the operator only — the server detects an encrypted file +by its magic bytes (`SELFPOST1`), not by the extension. The key is derived from the password with scrypt and the contents are sealed with AES-256-GCM, in chunks, so a truncated or altered file fails to open rather diff --git a/docs/security.md b/docs/security.md index e94b15e..e5e964a 100644 --- a/docs/security.md +++ b/docs/security.md @@ -80,9 +80,10 @@ Hardening сверх обязательного (security-заголовки, п аутентифицирован заголовком, номером и флагом конца потока — обрезанный или подменённый файл не открывается вместо тихого восстановления «хвоста». Формат и обёртка: [internal/secretfile](../internal/secretfile/secretfile.go). -- Расширения: `.spbk` (полный бэкап), `.spde` (экспорт домена); незашифрованные - остаются `.tar.gz` / `.json`. Импорт домена определяет шифрование по magic - файла, а не по расширению. +- Расширения: `.spbk` (**S**elf**P**ost **b**ac**k**up — полный бэкап), + `.spde` (**S**elf**P**ost **d**omain **e**xport — экспорт домена); + незашифрованные остаются `.tar.gz` / `.json`. Импорт домена определяет + шифрование по magic файла, а не по расширению. - Пароль нигде не сохраняется: восстановить файл без него нельзя. Пароль в CLI — только через `SELFPOST_BACKUP_PASSWORD` или `-password-file`, никогда аргументом (список процессов читается любым процессом контейнера). diff --git a/internal/web/templates/backup.html b/internal/web/templates/backup.html index aee9bc8..bf9352a 100644 --- a/internal/web/templates/backup.html +++ b/internal/web/templates/backup.html @@ -11,7 +11,8 @@

The backup file is a secret (it contains private keys and credentials). Store and transfer it securely and delete it once the restore succeeds. Encrypting it below is the simplest way to do that: - the download is then a .spbk file that only the password opens.

+ the download is then a .spbk file (SelfPost backup) that only + the password opens.

{{if .BackupErr}}

{{.BackupErr}}

{{end}}
{{template "encryptfields" .}} @@ -22,9 +23,10 @@

Import a domain

Move a single domain here from another SelfPost instance using - a domain export file (from that domain's page). Its DKIM key and application - passwords come across, so the published DNS record needs no change. The export - file is a secret, like a full backup.

+ a domain export file (from that domain's page) — plain .json or + encrypted .spde (SelfPost domain export). Its DKIM key and + application passwords come across, so the published DNS record needs no + change. The export file is a secret, like a full backup.

{{if .ImportErr}}

{{.ImportErr}}

{{end}} diff --git a/internal/web/templates/domain_detail.html b/internal/web/templates/domain_detail.html index 545f29f..93a7c0a 100644 --- a/internal/web/templates/domain_detail.html +++ b/internal/web/templates/domain_detail.html @@ -299,7 +299,7 @@

The export file is a secret — it contains the private DKIM key and application passwords. Transfer it securely and delete it after the import, or encrypt it below and move a .spde file - instead; the import form asks for the password.

+ (SelfPost domain export) instead; the import form asks for the password.

{{if .ExportErr}}

{{.ExportErr}}

{{end}} {{template "encryptfields" .}} diff --git a/internal/web/templates/encrypt_fields.html b/internal/web/templates/encrypt_fields.html index 3340201..afb7ac1 100644 --- a/internal/web/templates/encrypt_fields.html +++ b/internal/web/templates/encrypt_fields.html @@ -1,9 +1,10 @@ {{/* Password fields shared by the full-backup and domain-export forms. The checkbox is the switch: unticked, the download keeps its historic plain form (.tar.gz / .json); ticked, the file is sealed in a password-encrypted - envelope (.spbk / .spde). The fields start hidden and are revealed by - panel.js — with JavaScript blocked they are simply always visible, and the - server still decides from the checkbox alone. */}} + envelope (.spbk = SelfPost backup, .spde = SelfPost domain export). The + fields start hidden and are revealed by panel.js — with JavaScript blocked + they are simply always visible, and the server still decides from the + checkbox alone. */}} {{define "encryptfields"}}