Add credentials file support for Dolt server passwords (#2854)

* feat: add credentials file support for Dolt server passwords

Add INI-style credentials file (~/.config/beads/credentials) as a
fallback for Dolt server passwords, keyed by [host:port] section.
This lets users working with multiple servers avoid juggling env vars
per project.

Lookup order: BEADS_DOLT_PASSWORD env var > credentials file > empty.
Path overridable via BEADS_CREDENTIALS_FILE env var.
Warns on overly permissive file permissions (unix only, mirrors ssh).

* docs: document credentials file in DOLT.md

Add credentials file section to the Dolt backend docs covering file
format, default location, permission warnings, and password resolution
order. Update the config reference and env var table to reference the
new feature.

* fix: use resolved runtime port for credentials file lookup

The credential file lookup in GetDoltServerPassword() used the port
from metadata.json, but the actual connection port comes from
doltserver.DefaultConfig() which has its own priority chain (port file >
config.yaml > metadata.json). When these diverge — e.g., IAP tunnel on
3308 vs local Dolt on 3307 — the credentials file lookup used the wrong
[host:port] section.

Add GetDoltServerPasswordForPort() that accepts an explicit port, and
use it in main.go where the resolved runtime port is already known.
Existing GetDoltServerPassword() delegates to the new method for
backward compatibility.

* fix: use mysql.Config.FormatDSN for proper password escaping

Passwords with special characters (& < > / % etc.) were inserted raw
into the DSN string, breaking go-sql-driver/mysql parsing. Passwords
like "zId&z,L9P4X,%k4n4rylGV<Ibos9<)/p" would cause "Access denied"
errors even though the password was correct.

Switch from manual fmt.Sprintf DSN construction to mysql.Config's
FormatDSN(), which handles escaping correctly. This also consolidates
timeout and TLS configuration into the typed Config struct instead of
string concatenation.

* test: add DSN special character password roundtrip tests

Covers passwords with &, <, >, /, ?, %, @, :, and () — all of which
broke the old fmt.Sprintf DSN construction. Verifies that FormatDSN
produces a parseable DSN and the password survives the roundtrip.
This commit is contained in:
Sam 2026-04-02 23:35:56 -04:00 • committed by GitHub
commit 7e4da9ab20
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 529 additions and 26 deletions

View file

@ -720,7 +720,9 @@ var rootCmd = &cobra.Command{
// config.yaml). Port 0 is fine here — auto-start will resolve it.
doltCfg.ServerPort = doltserver.DefaultConfig(beadsDir).Port
doltCfg.ServerUser = cfg.GetDoltServerUser()
doltCfg.ServerPassword = cfg.GetDoltServerPassword()
// Use the resolved port for credential lookup — metadata.json port
// and runtime port can diverge (e.g., tunnel on 3308 vs local on 3307).
doltCfg.ServerPassword = cfg.GetDoltServerPasswordForPort(doltCfg.ServerPort)
doltCfg.ServerTLS = cfg.GetDoltServerTLS()
} else if cfgErr == nil {
// Load returned (nil, nil) — no config file found.

View file

@ -335,7 +335,7 @@ dolt:
host: 127.0.0.1
port: 3307
user: root
# Password via BEADS_DOLT_PASSWORD env var
# Password: env var or credentials file (see below)
# Shared server mode (GH#2377): all projects share a single Dolt server
# at ~/.beads/shared-server/. Each project uses its own database (prefix-based).
@ -350,7 +350,8 @@ dolt:
| Variable | Purpose |
|----------|---------|
| `BEADS_DOLT_PASSWORD` | Server mode password |
| `BEADS_DOLT_PASSWORD` | Server mode password (highest priority) |
| `BEADS_CREDENTIALS_FILE` | Path to credentials file (overrides default location) |
| `BEADS_DOLT_SERVER_MODE` | Enable server mode (set to "1") |
| `BEADS_DOLT_SERVER_HOST` | Server host (default: 127.0.0.1) |
| `BEADS_DOLT_SERVER_PORT` | Server port (default: 3307, or 3308 in shared mode) |
@ -361,6 +362,49 @@ dolt:
| `DOLT_REMOTE_PASSWORD` | Push/pull auth password |
| `BD_DOLT_AUTO_COMMIT` | Override auto-commit setting |
### Credentials File
For multi-server setups, you can store passwords in an INI-style credentials file
instead of juggling environment variables per project. Passwords are looked up by
`[host:port]` section, so each project automatically gets the right password based
on its configured server.
**Password resolution order:**
1. `BEADS_DOLT_PASSWORD` env var (highest priority, existing behavior)
2. Credentials file lookup by `[host:port]` (using the resolved runtime port)
3. Empty string (no password)
**Port resolution note:** The `[host:port]` used for credential lookup matches the
resolved runtime port (from the port file, env var, or config — in that priority
order), not necessarily the port stored in `metadata.json`. This matters when using
IAP tunnels: if your tunnel maps remote:3307 to localhost:3308, store your password
under `[127.0.0.1:3308]` and the credentials file will match the actual connection.
**Default location:** `~/.config/beads/credentials` (Linux/macOS), `%APPDATA%\beads\credentials` (Windows)
**Override location:** Set `BEADS_CREDENTIALS_FILE` env var.
**File format:**
```ini
# ~/.config/beads/credentials
[127.0.0.1:3307]
password=localDevPassword
[beads.company.com:3307]
password=teamServerPassword
[10.0.1.50:3308]
password=officePassword
```
**Permissions:** On Linux/macOS, a warning is printed to stderr if the file is
readable by group or others (mirrors ssh behavior). Set permissions with:
```bash
chmod 600 ~/.config/beads/credentials
```
## Dolt Version Control
Dolt maintains its own version history, separate from Git:

View file

@ -318,9 +318,35 @@ func (c *Config) GetDoltDatabase() string {
}
// GetDoltServerPassword returns the Dolt server password.
// Checks BEADS_DOLT_PASSWORD env var (password should never be stored in config files).
// Checks in order:
// 1. BEADS_DOLT_PASSWORD env var (highest priority, existing behavior)
// 2. Credentials file lookup by [host:port] section
// (path from BEADS_CREDENTIALS_FILE env var, or ~/.config/beads/credentials)
// 3. Empty string (no password)
//
// Note: uses the port from configfile (metadata.json / env var), which may differ
// from the resolved runtime port (doltserver port file). If you have the resolved
// port, prefer GetDoltServerPasswordForPort for correct credentials file lookup.
func (c *Config) GetDoltServerPassword() string {
return os.Getenv("BEADS_DOLT_PASSWORD")
return c.GetDoltServerPasswordForPort(c.GetDoltServerPort())
}
// GetDoltServerPasswordForPort returns the Dolt server password using an explicit
// port for the credentials file lookup. Use this when the resolved runtime port
// (from doltserver.DefaultConfig) differs from the configfile port (metadata.json).
//
// This avoids a mismatch where metadata.json says port 3308 (tunnel) but the
// doltserver port file says 3307 (local), causing the credentials file lookup
// to use the wrong [host:port] section.
func (c *Config) GetDoltServerPasswordForPort(port int) string {
if p := os.Getenv("BEADS_DOLT_PASSWORD"); p != "" {
return p
}
host := c.GetDoltServerHost()
if p := LookupCredentialsPassword(host, port); p != "" {
return p
}
return ""
}
// GetDoltServerTLS returns whether TLS is enabled for server connections.

View file

@ -0,0 +1,102 @@
package configfile
import (
"bufio"
"fmt"
"os"
"path/filepath"
"runtime"
"strings"
)
// DefaultCredentialsPath returns the platform-appropriate default credentials file path.
// Linux/macOS: ~/.config/beads/credentials
// Windows: %APPDATA%\beads\credentials
func DefaultCredentialsPath() string {
if runtime.GOOS == "windows" {
if appdata := os.Getenv("APPDATA"); appdata != "" {
return filepath.Join(appdata, "beads", "credentials")
}
}
home, err := os.UserHomeDir()
if err != nil {
return ""
}
return filepath.Join(home, ".config", "beads", "credentials")
}
// LookupCredentialsPassword reads a password from an INI-style credentials file,
// keyed by [host:port] section. Returns empty string if not found or on any error.
//
// File format:
//
// [127.0.0.1:3307]
// password=localDevPassword
//
// [beads.company.com:3307]
// password=teamServerPassword
//
// The file path is determined by:
// 1. BEADS_CREDENTIALS_FILE env var (if set)
// 2. Default platform path (see DefaultCredentialsPath)
func LookupCredentialsPassword(host string, port int) string {
credFile := os.Getenv("BEADS_CREDENTIALS_FILE")
if credFile == "" {
credFile = DefaultCredentialsPath()
}
if credFile == "" {
return ""
}
return readPasswordFromFile(credFile, fmt.Sprintf("%s:%d", host, port))
}
// readPasswordFromFile parses an INI-style credentials file and returns the
// password for the given [host:port] section. Returns empty string on any error.
func readPasswordFromFile(path string, sectionKey string) string {
f, err := os.Open(path) //nolint:gosec // path comes from env var or os.UserHomeDir, not user input
if err != nil {
return ""
}
defer f.Close()
// Warn if file has overly permissive permissions (unix only)
warnIfInsecurePermissions(path)
scanner := bufio.NewScanner(f)
inSection := false
for scanner.Scan() {
line := strings.TrimSpace(scanner.Text())
// Strip inline comments
if idx := strings.Index(line, "#"); idx >= 0 {
line = strings.TrimSpace(line[:idx])
}
if line == "" {
continue
}
// Section header: [host:port]
if strings.HasPrefix(line, "[") && strings.HasSuffix(line, "]") {
section := line[1 : len(line)-1]
if section == sectionKey {
inSection = true
} else if inSection {
// We've left our section without finding a password
break
}
continue
}
// Key=value within our section
if inSection {
key, value, found := strings.Cut(line, "=")
if found && strings.TrimSpace(key) == "password" {
return strings.TrimSpace(value)
}
}
}
return ""
}

View file

@ -0,0 +1,252 @@
package configfile
import (
"os"
"path/filepath"
"testing"
)
func TestLookupCredentialsPassword(t *testing.T) {
// Create a temp credentials file
tmpDir := t.TempDir()
credFile := filepath.Join(tmpDir, "credentials")
content := `# Test credentials file
[127.0.0.1:3307]
password=localPass
[beads.company.com:3307]
password=companyPass
[10.0.1.50:3308]
password=officePass
`
if err := os.WriteFile(credFile, []byte(content), 0600); err != nil {
t.Fatalf("failed to write credentials file: %v", err)
}
// Point BEADS_CREDENTIALS_FILE at our temp file
t.Setenv("BEADS_CREDENTIALS_FILE", credFile)
tests := []struct {
name string
host string
port int
wantPass string
}{
{
name: "local server",
host: "127.0.0.1",
port: 3307,
wantPass: "localPass",
},
{
name: "company server",
host: "beads.company.com",
port: 3307,
wantPass: "companyPass",
},
{
name: "office server different port",
host: "10.0.1.50",
port: 3308,
wantPass: "officePass",
},
{
name: "unknown server returns empty",
host: "unknown.host",
port: 3307,
wantPass: "",
},
{
name: "right host wrong port returns empty",
host: "127.0.0.1",
port: 9999,
wantPass: "",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := LookupCredentialsPassword(tt.host, tt.port)
if got != tt.wantPass {
t.Errorf("LookupCredentialsPassword(%q, %d) = %q, want %q",
tt.host, tt.port, got, tt.wantPass)
}
})
}
}
func TestLookupCredentialsPassword_MissingFile(t *testing.T) {
t.Setenv("BEADS_CREDENTIALS_FILE", "/nonexistent/path/credentials")
got := LookupCredentialsPassword("127.0.0.1", 3307)
if got != "" {
t.Errorf("expected empty string for missing file, got %q", got)
}
}
func TestLookupCredentialsPassword_EnvVarTakesPrecedence(t *testing.T) {
// Create a credentials file with one password
tmpDir := t.TempDir()
credFile := filepath.Join(tmpDir, "credentials")
if err := os.WriteFile(credFile, []byte("[127.0.0.1:3307]\npassword=filePass\n"), 0600); err != nil {
t.Fatalf("failed to write credentials file: %v", err)
}
t.Setenv("BEADS_CREDENTIALS_FILE", credFile)
// Set BEADS_DOLT_PASSWORD env var — should win
t.Setenv("BEADS_DOLT_PASSWORD", "envPass")
cfg := DefaultConfig()
got := cfg.GetDoltServerPassword()
if got != "envPass" {
t.Errorf("GetDoltServerPassword() = %q, want %q (env var should take precedence)", got, "envPass")
}
}
func TestLookupCredentialsPassword_FallsBackToFile(t *testing.T) {
// Create a credentials file
tmpDir := t.TempDir()
credFile := filepath.Join(tmpDir, "credentials")
if err := os.WriteFile(credFile, []byte("[127.0.0.1:3307]\npassword=filePass\n"), 0600); err != nil {
t.Fatalf("failed to write credentials file: %v", err)
}
t.Setenv("BEADS_CREDENTIALS_FILE", credFile)
// Clear BEADS_DOLT_PASSWORD so file lookup kicks in
t.Setenv("BEADS_DOLT_PASSWORD", "")
cfg := DefaultConfig()
got := cfg.GetDoltServerPassword()
if got != "filePass" {
t.Errorf("GetDoltServerPassword() = %q, want %q (should fall back to credentials file)", got, "filePass")
}
}
func TestLookupCredentialsPassword_MultipleServers(t *testing.T) {
// Verify different projects connecting to different servers get the right password
tmpDir := t.TempDir()
credFile := filepath.Join(tmpDir, "credentials")
content := `[127.0.0.1:3307]
password=personalDevPass
[beads.work.internal:3307]
password=workServerPass
`
if err := os.WriteFile(credFile, []byte(content), 0600); err != nil {
t.Fatalf("failed to write credentials file: %v", err)
}
t.Setenv("BEADS_CREDENTIALS_FILE", credFile)
t.Setenv("BEADS_DOLT_PASSWORD", "")
// Personal project uses localhost
personal := DefaultConfig()
personal.DoltServerHost = "127.0.0.1"
personal.DoltServerPort = 3307
got := personal.GetDoltServerPassword()
if got != "personalDevPass" {
t.Errorf("personal project password = %q, want %q", got, "personalDevPass")
}
// Work project uses corporate server
work := DefaultConfig()
work.DoltServerHost = "beads.work.internal"
work.DoltServerPort = 3307
got = work.GetDoltServerPassword()
if got != "workServerPass" {
t.Errorf("work project password = %q, want %q", got, "workServerPass")
}
}
func TestGetDoltServerPasswordForPort_OverridesConfigPort(t *testing.T) {
// Simulates the tunnel scenario: metadata.json has port 3308 (tunnel)
// but the doltserver port file resolves to 3307 (local). The credentials
// file has the password under [127.0.0.1:3307]. GetDoltServerPassword()
// would look up [127.0.0.1:3308] and miss. GetDoltServerPasswordForPort(3307)
// should find it.
tmpDir := t.TempDir()
credFile := filepath.Join(tmpDir, "credentials")
content := `[127.0.0.1:3307]
password=localPass
[127.0.0.1:3308]
password=tunnelPass
`
if err := os.WriteFile(credFile, []byte(content), 0600); err != nil {
t.Fatalf("failed to write credentials file: %v", err)
}
t.Setenv("BEADS_CREDENTIALS_FILE", credFile)
t.Setenv("BEADS_DOLT_PASSWORD", "")
cfg := DefaultConfig()
cfg.DoltServerHost = "127.0.0.1"
cfg.DoltServerPort = 3308 // metadata.json says tunnel port
// GetDoltServerPassword uses config port (3308) → tunnelPass
got := cfg.GetDoltServerPassword()
if got != "tunnelPass" {
t.Errorf("GetDoltServerPassword() = %q, want %q", got, "tunnelPass")
}
// GetDoltServerPasswordForPort with resolved runtime port (3307) → localPass
got = cfg.GetDoltServerPasswordForPort(3307)
if got != "localPass" {
t.Errorf("GetDoltServerPasswordForPort(3307) = %q, want %q", got, "localPass")
}
// GetDoltServerPasswordForPort with tunnel port (3308) → tunnelPass
got = cfg.GetDoltServerPasswordForPort(3308)
if got != "tunnelPass" {
t.Errorf("GetDoltServerPasswordForPort(3308) = %q, want %q", got, "tunnelPass")
}
}
func TestReadPasswordFromFile_InlineComments(t *testing.T) {
tmpDir := t.TempDir()
credFile := filepath.Join(tmpDir, "credentials")
content := `# Full line comment
[127.0.0.1:3307]
password=myPass # this is an inline comment
`
if err := os.WriteFile(credFile, []byte(content), 0600); err != nil {
t.Fatalf("failed to write credentials file: %v", err)
}
got := readPasswordFromFile(credFile, "127.0.0.1:3307")
if got != "myPass" {
t.Errorf("readPasswordFromFile() = %q, want %q (should strip inline comments)", got, "myPass")
}
}
func TestReadPasswordFromFile_WhitespaceHandling(t *testing.T) {
tmpDir := t.TempDir()
credFile := filepath.Join(tmpDir, "credentials")
content := `[ 127.0.0.1:3307 ]
password = spaced
[10.0.0.1:3307]
password = padded
`
if err := os.WriteFile(credFile, []byte(content), 0600); err != nil {
t.Fatalf("failed to write credentials file: %v", err)
}
// Section keys are not trimmed internally — the brackets are stripped but
// inner whitespace is part of the key. Standard INI behavior.
got := readPasswordFromFile(credFile, "10.0.0.1:3307")
if got != "padded" {
t.Errorf("readPasswordFromFile() = %q, want %q", got, "padded")
}
}
func TestDefaultCredentialsPath(t *testing.T) {
path := DefaultCredentialsPath()
if path == "" {
t.Skip("could not determine home directory")
}
// Should end with the expected suffix
if !filepath.IsAbs(path) {
t.Errorf("DefaultCredentialsPath() = %q, want absolute path", path)
}
}

View file

@ -0,0 +1,22 @@
//go:build !windows
package configfile
import (
"fmt"
"os"
)
// warnIfInsecurePermissions checks if the credentials file is readable by
// group or others, and prints a warning to stderr if so. Mirrors ssh behavior.
func warnIfInsecurePermissions(path string) {
info, err := os.Stat(path)
if err != nil {
return
}
perm := info.Mode().Perm()
if perm&0077 != 0 {
fmt.Fprintf(os.Stderr, "WARNING: credentials file %s has overly permissive permissions (%04o).\n", path, perm)
fmt.Fprintf(os.Stderr, "Consider running: chmod 600 %s\n", path)
}
}

View file

@ -0,0 +1,7 @@
//go:build windows
package configfile
// warnIfInsecurePermissions is a no-op on Windows.
// Windows ACLs don't map to unix permission bits.
func warnIfInsecurePermissions(path string) {}

View file

@ -1051,31 +1051,27 @@ func isLocalHost(host string) bool {
// buildServerDSN constructs a MySQL DSN for connecting to a Dolt server.
// If database is empty, connects without selecting a database (for init operations).
func buildServerDSN(cfg *Config, database string) string {
var userPart string
if cfg.ServerPassword != "" {
userPart = fmt.Sprintf("%s:%s", cfg.ServerUser, cfg.ServerPassword)
} else {
userPart = cfg.ServerUser
// go-sql-driver/mysql DSN format: user:password@tcp(host:port)/db?params
// The password must not contain unescaped special characters that collide
// with DSN delimiters (@ : / ?). Use go-sql-driver's Config.FormatDSN()
// which handles escaping correctly.
dsnCfg := mysql.Config{
User: cfg.ServerUser,
Passwd: cfg.ServerPassword,
Net: "tcp",
Addr: fmt.Sprintf("%s:%d", cfg.ServerHost, cfg.ServerPort),
DBName: database,
ParseTime: true,
Timeout: 5 * time.Second,
ReadTimeout: 10 * time.Second,
WriteTimeout: 10 * time.Second,
AllowNativePasswords: true,
}
var dbPart string
if database != "" {
dbPart = "/" + database
} else {
dbPart = "/"
}
// Timeouts prevent agents from blocking forever when Dolt server hangs.
// timeout=5s: TCP connect timeout
// readTimeout=10s: I/O read timeout (covers hung queries)
// writeTimeout=10s: I/O write timeout
params := "parseTime=true&timeout=5s&readTimeout=10s&writeTimeout=10s"
if cfg.ServerTLS {
params += "&tls=true"
dsnCfg.TLSConfig = "true"
}
return fmt.Sprintf("%s@tcp(%s:%d)%s?%s",
userPart, cfg.ServerHost, cfg.ServerPort, dbPart, params)
return dsnCfg.FormatDSN()
}
// execWithLongTimeout opens a one-shot database connection with readTimeout=5m

View file

@ -379,6 +379,58 @@ func TestExecWithLongTimeoutDSNRewrite(t *testing.T) {
}
}
// TestBuildServerDSN_SpecialCharacterPassword verifies that passwords with
// characters that collide with DSN delimiters (@ : / ? & < > etc.) are
// properly escaped by FormatDSN. This was a real bug — passwords from Secret
// Manager like "zId&z,L9P4X,%k4n4rylGV<Ibos9<)/p" caused Access Denied.
func TestBuildServerDSN_SpecialCharacterPassword(t *testing.T) {
tests := []struct {
name string
password string
}{
{"ampersand and angle brackets", "zId&z,L9P4X,%k4n4rylGV<Ibos9<)/p"},
{"at sign and colon", "p@ss:word"},
{"slash and question mark", "pass/word?maybe"},
{"percent encoding chars", "100%done&dusted"},
{"empty password", ""},
{"alphanumeric only", "SimplePassword123"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
cfg := &Config{
ServerUser: "testuser",
ServerPassword: tt.password,
ServerHost: "127.0.0.1",
ServerPort: 3308,
Database: "testdb",
}
applyConfigDefaults(cfg)
dsn := buildServerDSN(cfg, cfg.Database)
// The DSN must be parseable by go-sql-driver
parsed, err := mysql.ParseDSN(dsn)
if err != nil {
t.Fatalf("buildServerDSN produced unparseable DSN: %v\n DSN: %s", err, dsn)
}
// The parsed password must match the original exactly
if parsed.Passwd != tt.password {
t.Errorf("password roundtrip failed: got %q, want %q", parsed.Passwd, tt.password)
}
if parsed.User != "testuser" {
t.Errorf("user roundtrip failed: got %q, want %q", parsed.User, "testuser")
}
if parsed.DBName != "testdb" {
t.Errorf("database roundtrip failed: got %q, want %q", parsed.DBName, "testdb")
}
})
}
}
func TestShouldStopAutoStartedServerOnClose(t *testing.T) {
origTestMode := os.Getenv("BEADS_TEST_MODE")
defer func() {