Keep server data in an encrypted database, and harden every part

Storage. The server keeps its data in SQLite (a file in the data
directory, the default) or PostgreSQL (database, KEEPORG_DATABASE_URL or
-database). Every row, the KDBX versions included, is sealed with
AES-256-GCM under a key derived from the master key and named by an HMAC.
The master key is required to start and a different one is refused. A data
directory from 0.10 or earlier is imported on first start. Several servers
may share one PostgreSQL database. Go goes to 1.26 for the pure-Go
drivers (modernc.org/sqlite, jackc/pgx).

Hardening, after an audit of the server, both clients and the deployment:
- Single sign-on approves a device only after an explicit Approve in the
  browser that started it, bound by a cookie and PKCE; identities are never
  linked by username, by verified email only when allowed, never to admins.
- Sign-in attempts are limited per address and per account, passwords are
  checked outside the store lock with uniform timing, one-time codes work
  once, and starting two-factor needs the password.
- Merge vaults bound KDF parameters, payload size and XML shape, check
  pushes before storing them, and run at most two merges at once. A version
  is written in the same transaction as its metadata.
- Tokens in URLs only on the event stream, which ends on revocation; CSP,
  frame-ancestors, no-store and HSTS; sign-in CSRF; 404 for databases
  without access; new trusted_proxies.
- Clients open only the server's approval page, keep case-variant and
  retired file names apart, never overwrite a save made during a pull,
  require https except locally, send the stream token in a header, bound
  their reads and escape notifications and terminal output.
- The .deb creates the master key, systemd is sandboxed further, nginx sets
  modern TLS and HSTS, and CI deploys from main only.

Server 0.12.0, desktop 0.6.0, Android 0.4.0 (versionCode 4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cmd/keeporg/agent.go

@@ -259,6 +259,9 @@ func (a *agent) signIn(ctx context.Context, open func(string)) error {
 	if err != nil {
 		return err
 	}
+	if err := client.CheckVerificationURL(cfg.ServerURL, start.VerificationURL); err != nil {
+		return err
+	}
 	a.setPending(start.UserCode)
 	defer a.setPending("")
 	open(start.VerificationURL)

cmd/keeporg/agent_test.go

@@ -159,3 +159,11 @@ func TestMirrorSettingsChanged(t *testing.T) {
 		t.Error("a new mirror directory did not restart the mirror")
 	}
 }
+
+func TestTermSafeStripsControlCharacters(t *testing.T) {
+	var b strings.Builder
+	termSafe{&b}.Write([]byte("Team\x1b]0;pwned\x07 Vault\t1\n\x9b2J"))
+	if got := b.String(); got != "Team]0;pwned Vault\t1\n2J" {
+		t.Fatalf("got %q", got)
+	}
+}

cmd/keeporg/autostart_darwin.go

@@ -3,6 +3,8 @@
 package main
 
 import (
+	"bytes"
+	"encoding/xml"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -50,9 +52,17 @@ func setStartAtLogin(enable bool) error {
 	<string>Interactive</string>
 </dict>
 </plist>
-`, AppID, exe)
+`, xmlEscape(AppID), xmlEscape(exe))
 	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
 		return err
 	}
 	return os.WriteFile(path, []byte(plist), 0o644)
 }
+
+// xmlEscape makes a string safe inside a plist element; a path with "&" or
+// "<" would otherwise produce a LaunchAgent that never loads.
+func xmlEscape(s string) string {
+	var b bytes.Buffer
+	_ = xml.EscapeText(&b, []byte(s))
+	return b.String()
+}

cmd/keeporg/autostart_xdg.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 )
 
 // autostartPath is the XDG autostart entry every freedesktop session reads.
@@ -39,13 +40,37 @@ func setStartAtLogin(enable bool) error {
 Type=Application
 Name=KeepOrg
 Comment=KeePass database synchronization
-Exec="%s" tray
+Exec=%s tray
 Icon=keeporg
 Terminal=false
 X-GNOME-Autostart-enabled=true
-`, exe)
+`, desktopExecArg(exe))
 	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
 		return err
 	}
 	return os.WriteFile(path, []byte(entry), 0o644)
 }
+
+// desktopExecArg quotes a path for a desktop entry's Exec key: inside double
+// quotes, ", `, $ and \ are escaped with a backslash, % is doubled as a field
+// code would be, and then the whole value is escaped again as a string, which
+// doubles every backslash.
+func desktopExecArg(path string) string {
+	var b strings.Builder
+	b.WriteByte('"')
+	for _, r := range path {
+		switch r {
+		case '"', '`', '$':
+			b.WriteString(`\\`) // \ escaped once more as a string
+			b.WriteRune(r)
+		case '\\':
+			b.WriteString(`\\\\`)
+		case '%':
+			b.WriteString("%%")
+		default:
+			b.WriteRune(r)
+		}
+	}
+	b.WriteByte('"')
+	return b.String()
+}

cmd/keeporg/autostart_xdg_test.go

@@ -0,0 +1,13 @@
+//go:build linux || freebsd || openbsd || netbsd || dragonfly
+
+package main
+
+import "testing"
+
+func TestDesktopExecArgEscapes(t *testing.T) {
+	got := desktopExecArg(`/opt/a "b" $c\d 100%`)
+	want := `"/opt/a \\"b\\" \\$c\\\\d 100%%"`
+	if got != want {
+		t.Fatalf("got %s, want %s", got, want)
+	}
+}

cmd/keeporg/commands.go

@@ -122,6 +122,9 @@ func browserLogin(ctx context.Context, api *client.API, label string) (*client.S
 	if err != nil {
 		return nil, err
 	}
+	if err := client.CheckVerificationURL(api.BaseURL, start.VerificationURL); err != nil {
+		return nil, err
+	}
 	fmt.Printf("Open this page and approve the code %s:\n\n  %s\n\n",
 		start.UserCode, start.VerificationURL)
 	openBrowser(start.VerificationURL)
@@ -240,7 +243,7 @@ func cmdStatus(ctx context.Context, args []string) error {
 	if err != nil {
 		return err
 	}
-	w := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)
+	w := tabwriter.NewWriter(stdout, 0, 2, 2, ' ', 0)
 	fmt.Fprintln(w, "DATABASE\tACCESS\tSTRATEGY\tVERSION\tUPDATED BY\tUPDATED")
 	for _, d := range dbs {
 		when := "never"
@@ -253,7 +256,7 @@ func cmdStatus(ctx context.Context, args []string) error {
 }
 
 func printStatus(st []client.Status) {
-	w := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)
+	w := tabwriter.NewWriter(stdout, 0, 2, 2, ' ', 0)
 	fmt.Fprintln(w, "DATABASE\tFILE\tVERSION\tSTATE\tNOTE")
 	for _, s := range st {
 		fmt.Fprintf(w, "%s\t%s\t%d\t%s\t%s\n", s.Name, s.File, s.Version, s.State, s.Message)
@@ -302,7 +305,19 @@ func cmdTOTP(ctx context.Context, args []string) error {
 	if err != nil {
 		return err
 	}
-	sec, uri, err := api.EnrollTOTP(ctx)
+	password, err := readPassword("Account password: ")
+	if err != nil {
+		return err
+	}
+	sec, uri, err := api.EnrollTOTP(ctx, password, "")
+	if client.Code(err) == "reauth_required" {
+		// A factor is on already; replacing it needs its current code.
+		code, cerr := prompt("Current one-time code: ")
+		if cerr != nil {
+			return cerr
+		}
+		sec, uri, err = api.EnrollTOTP(ctx, password, code)
+	}
 	if err != nil {
 		return err
 	}
@@ -353,7 +368,7 @@ func cmdGroups(ctx context.Context, args []string) error {
 	if err != nil {
 		return err
 	}
-	w := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)
+	w := tabwriter.NewWriter(stdout, 0, 2, 2, ' ', 0)
 	fmt.Fprintln(w, "ID\tNAME\tPARENT\tMEMBERS\tYOU ADMINISTER")
 	for _, g := range groups {
 		fmt.Fprintf(w, "%s\t%s\t%s\t%d\t%v\n", g.ID, g.Name, g.ParentID, g.Members, g.Admin)
@@ -592,7 +607,7 @@ func cmdInvite(ctx context.Context, args []string) error {
 		if err != nil {
 			return err
 		}
-		w := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)
+		w := tabwriter.NewWriter(stdout, 0, 2, 2, ' ', 0)
 		fmt.Fprintln(w, "URL\tGROUP\tROLE\tUSES\tEXPIRES")
 		for _, i := range invites {
 			fmt.Fprintf(w, "%s\t%s\t%s\t%d/%d\t%s\n", i.URL, i.GroupID, i.Role, i.Uses, i.MaxUses,
@@ -621,7 +636,7 @@ func cmdUsers(ctx context.Context, args []string) error {
 	if err != nil {
 		return err
 	}
-	w := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)
+	w := tabwriter.NewWriter(stdout, 0, 2, 2, ' ', 0)
 	fmt.Fprintln(w, "ID\tUSERNAME\tEMAIL\tADMIN\t2FA")
 	for _, u := range users {
 		fmt.Fprintf(w, "%s\t%s\t%s\t%v\t%v\n", u.ID, u.Username, u.Email, u.ServerAdmin, u.TOTPEnabled)

cmd/keeporg/desktop.go

@@ -2,8 +2,13 @@ package main
 
 import (
 	"fmt"
+	"html"
+	"io"
+	"os"
 	"os/exec"
 	"runtime"
+	"strings"
+	"unicode/utf8"
 )
 
 // homepage is where About points.
@@ -47,7 +52,10 @@ func notify(title, message string) {
 			fmt.Sprintf("display notification %q with title %q", message, title)).Start()
 	case "windows":
 	default:
-		_ = exec.Command("notify-send", "--app-name=KeepOrg", "--icon=keeporg", title, message).Start()
+		// "--" so a database named "-u critical" is a title, not an option;
+		// the body is markup to notification daemons, so it is escaped.
+		_ = exec.Command("notify-send", "--app-name=KeepOrg", "--icon=keeporg", "--",
+			html.EscapeString(title), html.EscapeString(message)).Start()
 	}
 }
 
@@ -56,3 +64,29 @@ func aboutText(configPath string) string {
 	return fmt.Sprintf("KeepOrg %s\n\nKeePass database synchronization.\n\nConfiguration: %s\n%s",
 		Version, configPath, homepage)
 }
+
+// termSafe passes text through to a terminal without its control
+// characters. Names, labels and URLs printed by the CLI come from the server,
+// and escape sequences in them could rewrite what the terminal shows.
+type termSafe struct{ w io.Writer }
+
+func (t termSafe) Write(p []byte) (int, error) {
+	clean := strings.Map(func(r rune) rune {
+		if r == '\n' || r == '\t' {
+			return r
+		}
+		// A lone byte 0x9b is a C1 control to some terminals and invalid
+		// UTF-8 to Go, which reads it as RuneError.
+		if r < 0x20 || (r >= 0x7f && r < 0xa0) || r == utf8.RuneError {
+			return -1
+		}
+		return r
+	}, string(p))
+	if _, err := io.WriteString(t.w, clean); err != nil {
+		return 0, err
+	}
+	return len(p), nil
+}
+
+// stdout is where commands print: standard output, made safe for a terminal.
+var stdout io.Writer = termSafe{os.Stdout}

cmd/keeporgd/main.go

@@ -27,8 +27,17 @@ import (
 	"cc.tiredsysadmin.keeporg/internal/store"
 )
 
-// externalURLEnv sets external_url, between the configuration file and -url.
-const externalURLEnv = "KEEPORG_EXTERNAL_URL"
+// Settings a deployment usually knows only at deploy time can come from the
+// environment as well. Each sits between the configuration file and its flag.
+const (
+	// externalURLEnv sets external_url, overridden by -url.
+	externalURLEnv = "KEEPORG_EXTERNAL_URL"
+	// databaseEnv sets database, overridden by -database. A PostgreSQL URL
+	// carries a password, which is why it belongs in a secret, not a file.
+	databaseEnv = "KEEPORG_DATABASE_URL"
+	// proxiesEnv sets trusted_proxies, comma-separated.
+	proxiesEnv = "KEEPORG_TRUSTED_PROXIES"
+)
 
 // Version is stamped at build time from versions.mk.
 var Version = "dev"
@@ -43,6 +52,8 @@ type fileConfig struct {
 	MaxDBSizeMB     int64             `json:"max_db_size_mb"`
 	TLSCert         string            `json:"tls_cert"`
 	TLSKey          string            `json:"tls_key"`
+	Database        string            `json:"database"`
+	TrustedProxies  []string          `json:"trusted_proxies"`
 	MasterKeyFile   string            `json:"master_key_file"`
 	VaultKDF        vaultKDF          `json:"vault_kdf"`
 	OIDC            server.OIDCConfig `json:"oidc"`
@@ -60,7 +71,7 @@ func (f fileConfig) toConfig() server.Config {
 	c := server.Config{
 		Addr: f.Addr, DataDir: f.DataDir, ExternalURL: f.ExternalURL,
 		TLSCert: f.TLSCert, TLSKey: f.TLSKey, OIDC: f.OIDC,
-		MasterKeyFile: f.MasterKeyFile,
+		Database: f.Database, MasterKeyFile: f.MasterKeyFile, TrustedProxies: f.TrustedProxies,
 	}
 	if f.VaultKDF.MemoryMB > 0 {
 		c.VaultKDF = kdbx.KDFParams{
@@ -87,7 +98,9 @@ func main() {
 		addr       = flag.String("addr", "", "listen address (overrides the config file)")
 		dataDir    = flag.String("data", "", "data directory (overrides the config file)")
 		extURL     = flag.String("url", "", "externally reachable base URL (overrides $"+externalURLEnv+" and the config file)")
-		masterKey  = flag.String("master-key-file", "",
+		database   = flag.String("database", "", "postgres://… or sqlite:<path>; default sqlite:<data>/keeporg.db "+
+			"(overrides $"+databaseEnv+" and the config file)")
+		masterKey = flag.String("master-key-file", "",
 			"file holding the master key that wraps the vault keys, created if "+
 				"absent; $"+secret.MasterKeyEnv+" and $"+secret.MasterKeyFileEnv+
 				" take precedence over it and are never created")
@@ -131,6 +144,15 @@ func main() {
 	if v := strings.TrimSpace(os.Getenv(externalURLEnv)); v != "" {
 		cfg.ExternalURL = v
 	}
+	if v := strings.TrimSpace(os.Getenv(databaseEnv)); v != "" {
+		cfg.Database = v
+	}
+	if v := strings.TrimSpace(os.Getenv(proxiesEnv)); v != "" {
+		cfg.TrustedProxies = strings.Split(v, ",")
+	}
+	if *database != "" {
+		cfg.Database = *database
+	}
 	if *addr != "" {
 		cfg.Addr = *addr
 	}
@@ -164,6 +186,7 @@ func main() {
 	if err != nil {
 		lg.Fatalf("start: %v", err)
 	}
+	defer srv.Close()
 	if err := bootstrap(srv, lg); err != nil {
 		lg.Fatalf("bootstrap: %v", err)
 	}
@@ -181,8 +204,8 @@ func main() {
 
 	go func() {
 		eff := srv.Config()
-		lg.Printf("version %s listening on %s (external %s, data %s)",
-			Version, eff.Addr, eff.ExternalURL, eff.DataDir)
+		lg.Printf("version %s listening on %s (external %s, database %s)",
+			Version, eff.Addr, eff.ExternalURL, srv.DatabaseWhere())
 		var err error
 		if eff.TLSCert != "" && eff.TLSKey != "" {
 			err = hs.ListenAndServeTLS(eff.TLSCert, eff.TLSKey)
@@ -247,23 +270,28 @@ func bootstrap(srv *server.Server, lg *log.Logger) error {
 }
 
 // resetAdministrator gives the server's administrator a new password, for
-// when the one printed at first start was not kept. It writes the state
-// document directly, so the server must be stopped: a running one holds the
-// state in memory and would write over this on its next change.
+// when the one printed at first start was not kept. It writes to the
+// database like any server process would, so a running server picks the
+// change up within seconds and need not be stopped.
 //
 // Any second factor on that account is cleared too. Someone who has lost
 // the password has often lost the authenticator with it, and a recovery
 // that leaves you locked out is not one.
 func resetAdministrator(cfg server.Config, lg *log.Logger) error {
 	cfg.Defaults()
-	path := filepath.Join(cfg.DataDir, "state.json")
-	if _, err := os.Stat(path); err != nil {
-		return fmt.Errorf("no server state at %s: %w", path, err)
+	kr, err := secret.LoadKeyring(cfg.MasterKeyFile)
+	if err != nil {
+		return fmt.Errorf("master key: %w", err)
 	}
-	st, err := store.Open(path)
+	st, db, err := server.OpenStore(cfg, kr)
 	if err != nil {
 		return err
 	}
+	defer db.Close()
+	defer st.Close()
+	if st.Empty() {
+		return fmt.Errorf("the database %s holds no server yet; start keeporgd first", db.Where)
+	}
 
 	password := os.Getenv("KEEPORG_ADMIN_PASSWORD")
 	generated := false
@@ -313,7 +341,6 @@ func resetAdministrator(cfg server.Config, lg *log.Logger) error {
 		lg.Printf("reset %q to the password from KEEPORG_ADMIN_PASSWORD. Any second "+
 			"factor on that account was cleared and its sessions were revoked.", name)
 	}
-	lg.Print("if keeporgd was running while this ran, restart it now so it reloads the change")
 	return nil
 }
 
@@ -356,6 +383,8 @@ func writeExampleConfig(path string) error {
 		ExternalURL:     "https://keeporg.example.com",
 		SessionTTLHours: 24 * 90,
 		MaxDBSizeMB:     32,
+		Database:        "sqlite:/var/lib/keeporg/keeporg.db",
+		TrustedProxies:  []string{"127.0.0.1", "::1"},
 		MasterKeyFile:   "/etc/keeporg/master.key",
 		VaultKDF:        vaultKDF{MemoryMB: 32, Iterations: 2, Lanes: 2},
 		OIDC: server.OIDCConfig{