beads/cmd/bd/federation.go
Julian Knutsen dba70de281
fix(federation): actionable error when peer credentials cannot be decrypted (#6995)
* fix(embeddeddolt): use stored peer credentials for federation sync

bd federation add-peer promises stored credentials are used automatically
when syncing, but the embedded Fetch/PushTo/PullFrom paths read only the
DOLT_REMOTE_USER environment variable, so first sync against any
authenticated Dolt server presented the wrong identity. This is the
peer-path remainder of the class fixed for default remotes in #2543.

withPeerAuth mirrors server mode's withPeerCredentials: peer-store lookup
first, environment fallback for unknown remotes and credential-free peers
(federation sync iterates every dolt remote, so non-peer remotes must
keep their behavior). Stored credentials override the process-wide
DOLT_REMOTE_USER/DOLT_REMOTE_PASSWORD pair as a unit under a
federationEnvMutex, mirroring package dolt: the in-process Dolt engine
reads them from the process environment, so the override is serialized
and both variables are restored (or re-unset) afterward, including on
callback failure. A stored empty field unsets its variable rather than
inheriting an ambient value.

Fixes #5080

Agent-Signature: claude-code-claude-fable-5-unknown-reasoning on behalf of Michael Pursifull

* docs(embeddeddolt): clarify federationEnvMutex is separate from package dolt's lock

Review nit on #5085: the 'mirroring' phrasing read as if the two
packages shared one mutex. State explicitly that they are separate
locks and why per-package serialization suffices.

* fix(federation): actionable error when peer credentials cannot be decrypted

A database pulled to a second machine carries federation_peers rows
its local .beads-credential-key cannot decrypt, and every peer
operation died with a raw cipher error while bd federation status
blamed the network (Unreachable:). The failure semantics were right
(fail closed, matching server mode); the message said nothing about
the machine-local key or the fix.

Add storage.ErrCredentialKeyMismatch plus a shared wording helper
CredentialKeyMismatchError naming the key file as context and the
remediation (re-run bd federation add-peer on this machine). Both
backends wrap their decrypt failures with it: embeddeddolt at its
single decrypt funnel, dolt at its two read paths. GetFederationPeer
wraps now name the peer. bd federation status classifies the sentinel
with errors.Is and prints Local credential error instead of
Unreachable; the --json shape is unchanged and now pinned by test.

When the error fires is unchanged: same call sites, same fail-closed
semantics, no fallback to ambient credentials.

Tests pin the decrypt-failure branch in both backends (embeddeddolt
against a real store with a rotated key, dolt via sqlmock) and the
status classification end to end in the gated CLI harness.

Refs #5080

* fix(embeddeddolt): classify short ciphertext as credential-key mismatch

A stored peer password blob shorter than the GCM nonce returned a bare
'ciphertext too short' error, bypassing CredentialKeyMismatchError, so
federation status read that local corruption as an unreachable peer.
Route the branch through the same sentinel as a failed GCM open; the
remediation (re-add the peer on this machine) is identical.

Adds a short-ciphertext regression at the decrypt funnel.

Refs: gastownhall/beads#5214 (review, gap 1)

* fix(embeddeddolt): bind stored credentials to the remote URL; serialize env fallbacks

Two fixes to the shared withPeerAuth seam from the consolidation review:

- Stored peer credentials are now bound to the peer's canonical remote
  URL, not only to a matching remote name. AddRemoteIfNotExists keeps
  an existing same-name remote regardless of its URL, so a redirected
  remote could receive the stored password. withPeerAuth now verifies
  the live dolt_remotes URL against the peer row before any credential
  is installed, failing closed on divergence and on a missing remote.

- The plain-remote and empty-credential fallback callbacks now run
  under federationEnvMutex too. They previously called remoteAuthUser()
  and the operation itself outside the lock, so a fallback operation
  could observe a concurrent stored-peer operation's temporarily
  installed DOLT_REMOTE_USER/DOLT_REMOTE_PASSWORD pair.

Adds three regressions: diverged-URL fail-closed, missing-remote
fail-closed, and env-fallback-does-not-observe-peer-credentials.

Refs: gastownhall/beads#5085 (review)

* style(dolt): use US spelling in the decrypt-funnel comments

The repo's misspell linter rejects 'Labelling' and 'labelled'. Comment
text only; no behavior change.

Refs: gastownhall/beads#5214 (CI)

* review: name the resolved credential-key path in the mismatch error

Maintainer review fixup for PR #5214 (adopt-pr iteration 1). Addresses the one
minor and the one nit from the review synthesis; both reviewers found 0 blockers
and 0 majors and the quality scorecard is approve (898/850).

Minor (Debuggability & Operability). All three CredentialKeyMismatchError call
sites passed the bare const credentialKeyFile, so the message claimed "the key
file .beads-credential-key is machine-local" without saying where it is. On the
dolt backend that basename is genuinely ambiguous: initCredentialKey resolves it
against s.beadsDir and falls back to the legacy s.dbPath as a transparent
migration, so during the migration window two files with that name can exist
carrying different keys. Pass filepath.Join(s.beadsDir, credentialKeyFile)
instead, at dolt/credentials.go and both embeddeddolt/federation.go sites. No
signature change: the parameter was already named keyFile and its doc comment
already describes it as machine-local.

beadsDir is provably non-empty at all three sites in production, verified in
source rather than assumed: dolt only reaches the funnel with a non-nil key, and
initCredentialKey leaves the key nil when beadsDir is empty; embeddeddolt's
ensureCredentialKey errors out when it is empty.

This lengthens a message the author pre-declared as a judgment call. The
synthesis adjudicated that carve-out deliberately: it covers the message's
wording and its single-line form, not which file the text identifies.

Nit (Test Evidence Quality). dolt's withPeerCredentials is the seam that carries
the sentinel into `bd federation status` on the default backend and had no
fails-closed pin, unlike its embedded twin TestWithPeerAuth_KeyMismatchFailsClosed.
Added one subtest on the existing sqlmock harness asserting the callback does not
run and the sentinel survives the seam's own wrap.

Both pins were proven non-vacuous by mutation, not assumed:
- Reverting the three call sites to the bare const reds all three dolt subtests
  and all three embeddeddolt tests, with the original bare-basename text in the
  diff output.
- Making withPeerCredentials swallow the decrypt error reds only the new subtest,
  on exactly the two properties the nit named (callback ran; no failure).

The dolt test needed beadsDir set on its hand-built store: filepath.Join("",
credentialKeyFile) is the bare basename, so with beadsDir left empty the
resolved-path assertion would have passed vacuously. The embeddeddolt pin's
package-level const became a function of the store for the same reason — its
store has a real temp beadsDir, so the clause now pins the resolved path.

Validation: go vet rc=0 on all three packages; internal/storage, dolt
(3 tests incl. both negative/narrowing tests) and embeddeddolt (3 credential
tests) green; cmd/bd TestEmbeddedFederation 12/12 green including the PR's own
status_credential_key_mismatch e2e subtest. make bazel-sync-check rc=0 with zero
tracked drift — no new files and zero import changes, so no BUILD srcs or deps
can move.

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

---------

Co-authored-by: Michael Pursifull <mike@arcaven.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
2026-09-30 20:29:57 -07:00

529 lines
14 KiB
Go

//go:build cgo
package main
import (
"errors"
"fmt"
"os"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/ui"
"golang.org/x/term"
)
var (
federationPeer string
federationStrategy string
federationUser string
federationPassword string
federationSov string
)
var federationCmd = &cobra.Command{
Use: "federation",
GroupID: "sync",
Short: "Manage peer-to-peer federation with other workspaces",
Long: `Manage peer-to-peer federation between Dolt-backed beads databases.
Federation enables synchronized issue tracking across multiple workspaces,
each maintaining their own Dolt database while sharing updates via remotes.
Requires the Dolt storage backend.`,
}
var federationSyncCmd = &cobra.Command{
Use: "sync [--peer name]",
Short: "Synchronize with a peer town",
Long: `Pull from and push to peer towns.
Without --peer, syncs with all configured peers.
With --peer, syncs only with the specified peer.
Handles merge conflicts using the configured strategy:
--strategy ours Keep local changes on conflict
--strategy theirs Accept remote changes on conflict
If no strategy is specified and conflicts occur, the sync will pause
and report which tables have conflicts for manual resolution.
Examples:
bd federation sync # Sync with all peers
bd federation sync --peer town-beta # Sync with specific peer
bd federation sync --strategy theirs # Auto-resolve using remote values`,
SilenceUsage: true,
SilenceErrors: true,
RunE: runFederationSync,
}
var federationStatusCmd = &cobra.Command{
Use: "status [--peer name]",
Short: "Show federation sync status",
Long: `Show synchronization status with peer towns.
Displays:
- Configured peers and their URLs
- Commits ahead/behind each peer
- Whether there are unresolved conflicts
Examples:
bd federation status # Status for all peers
bd federation status --peer town-beta # Status for specific peer`,
SilenceUsage: true,
SilenceErrors: true,
RunE: runFederationStatus,
}
var federationAddPeerCmd = &cobra.Command{
Use: "add-peer <name> <url>",
Short: "Add a federation peer with optional SQL credentials",
Long: `Add a new federation peer remote with optional SQL user authentication.
The URL can be:
- dolthub://org/repo DoltHub hosted repository
- host:port/database Direct dolt sql-server connection
- file:///path/to/repo Local file path (for testing)
Credentials are encrypted and stored locally. They are used automatically
when syncing with the peer. If --user is provided without --password,
you will be prompted for the password interactively.
Examples:
bd federation add-peer town-beta dolthub://acme/town-beta-beads
bd federation add-peer town-gamma 192.168.1.100:3306/beads --user sync-bot
bd federation add-peer partner https://partner.example.com/beads --user admin --password secret`,
Args: cobra.ExactArgs(2),
SilenceUsage: true,
SilenceErrors: true,
RunE: runFederationAddPeer,
}
var federationRemovePeerCmd = &cobra.Command{
Use: "remove-peer <name>",
Short: "Remove a federation peer",
Args: cobra.ExactArgs(1),
SilenceUsage: true,
SilenceErrors: true,
RunE: runFederationRemovePeer,
}
var federationListPeersCmd = &cobra.Command{
Use: "list-peers",
Short: "List configured federation peers",
SilenceUsage: true,
SilenceErrors: true,
RunE: runFederationListPeers,
}
func init() {
// Add subcommands
federationCmd.AddCommand(federationSyncCmd)
federationCmd.AddCommand(federationStatusCmd)
federationCmd.AddCommand(federationAddPeerCmd)
federationCmd.AddCommand(federationRemovePeerCmd)
federationCmd.AddCommand(federationListPeersCmd)
// Flags for sync
federationSyncCmd.Flags().StringVar(&federationPeer, "peer", "", "Specific peer to sync with")
federationSyncCmd.Flags().StringVar(&federationStrategy, "strategy", "", "Conflict resolution strategy (ours|theirs)")
// Flags for status
federationStatusCmd.Flags().StringVar(&federationPeer, "peer", "", "Specific peer to check")
// Flags for add-peer (SQL user authentication)
federationAddPeerCmd.Flags().StringVarP(&federationUser, "user", "u", "", "SQL username for authentication")
federationAddPeerCmd.Flags().StringVarP(&federationPassword, "password", "p", "", "SQL password (prompted if --user set without --password)")
federationAddPeerCmd.Flags().StringVar(&federationSov, "sovereignty", "", "Sovereignty tier (T1, T2, T3, T4)")
rootCmd.AddCommand(federationCmd)
}
func getFederatedStore() (storage.DoltStorage, error) {
if store == nil {
return nil, fmt.Errorf("no store available")
}
return store, nil
}
func runFederationSync(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("federation sync is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("federation-sync")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
ctx := rootCtx
ds, err := getFederatedStore()
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
if federationStrategy != "" && federationStrategy != "ours" && federationStrategy != "theirs" {
return HandleErrorRespectJSON("invalid strategy %q: must be 'ours' or 'theirs'", federationStrategy)
}
var peers []string
if federationPeer != "" {
peers = []string{federationPeer}
} else {
remotes, err := ds.ListRemotes(ctx)
if err != nil {
return HandleErrorRespectJSON("failed to list peers: %v", err)
}
for _, r := range remotes {
if r.Name != "origin" {
peers = append(peers, r.Name)
}
}
}
if len(peers) == 0 {
return HandleErrorRespectJSON("no federation peers configured (use 'bd federation add-peer' to add peers)")
}
// Sync with each peer
var results []*storage.SyncResult
for _, peer := range peers {
if !jsonOutput {
fmt.Printf("%s Syncing with %s...\n", ui.RenderAccent("🔄"), peer)
}
result, err := ds.Sync(ctx, peer, federationStrategy)
results = append(results, result)
if err != nil {
if !jsonOutput {
fmt.Printf(" %s %v\n", ui.RenderFail("✗"), err)
}
continue
}
if !jsonOutput {
if result.Fetched {
fmt.Printf(" %s Fetched\n", ui.RenderPass("✓"))
}
if result.Merged {
fmt.Printf(" %s Merged", ui.RenderPass("✓"))
if result.PulledCommits > 0 {
fmt.Printf(" (%d commits)", result.PulledCommits)
}
fmt.Println()
}
if len(result.Conflicts) > 0 {
if result.ConflictsResolved {
fmt.Printf(" %s Resolved %d conflicts using %s strategy\n",
ui.RenderPass("✓"), len(result.Conflicts), federationStrategy)
} else {
fmt.Printf(" %s %d conflicts need resolution\n",
ui.RenderWarn("⚠"), len(result.Conflicts))
for _, c := range result.Conflicts {
fmt.Printf(" - %s\n", c.Field)
}
}
}
if result.Pushed {
fmt.Printf(" %s Pushed\n", ui.RenderPass("✓"))
} else if result.PushError != nil {
fmt.Printf(" %s Push skipped: %v\n", ui.RenderMuted("○"), result.PushError)
}
}
}
if jsonOutput {
return outputJSON(map[string]interface{}{
"peers": peers,
"results": results,
})
}
return nil
}
func runFederationStatus(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("federation status is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("federation-status")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
ctx := rootCtx
ds, err := getFederatedStore()
if err != nil {
return HandleErrorRespectJSON("%v", err)
}
allRemotes, err := ds.ListRemotes(ctx)
if err != nil {
return HandleErrorRespectJSON("failed to list remotes: %v", err)
}
remoteURLs := make(map[string]string)
for _, r := range allRemotes {
remoteURLs[r.Name] = r.URL
}
var peers []string
if federationPeer != "" {
peers = []string{federationPeer}
} else {
for _, r := range allRemotes {
peers = append(peers, r.Name)
}
}
if len(peers) == 0 {
if jsonOutput {
return outputJSON(map[string]interface{}{
"peers": []string{},
"pendingChanges": 0,
})
}
fmt.Println("No federation peers configured.")
return nil
}
doltStatus, _ := ds.Status(ctx)
pendingChanges := 0
if doltStatus != nil {
pendingChanges = len(doltStatus.Staged) + len(doltStatus.Unstaged)
}
type peerStatus struct {
Status *storage.SyncStatus
URL string
Reachable bool
ReachError string
// localCredentialErr marks a fetch that failed on this machine's
// credential key rather than on the network, so the line below does not
// blame the peer. Unexported: not part of the --json shape.
localCredentialErr bool
}
var peerStatuses []peerStatus
for _, peer := range peers {
ps := peerStatus{
URL: remoteURLs[peer],
}
status, _ := ds.SyncStatus(ctx, peer)
ps.Status = status
fetchErr := ds.Fetch(ctx, peer)
if fetchErr == nil {
ps.Reachable = true
status, _ = ds.SyncStatus(ctx, peer)
ps.Status = status
} else {
ps.ReachError = fetchErr.Error()
ps.localCredentialErr = errors.Is(fetchErr, storage.ErrCredentialKeyMismatch)
}
peerStatuses = append(peerStatuses, ps)
}
if jsonOutput {
return outputJSON(map[string]interface{}{
"peers": peerStatuses,
"pendingChanges": pendingChanges,
})
}
fmt.Printf("\n%s Federation Status:\n\n", ui.RenderAccent("🌐"))
if pendingChanges > 0 {
fmt.Printf(" %s %d pending local changes\n\n", ui.RenderWarn("⚠"), pendingChanges)
}
for _, ps := range peerStatuses {
status := ps.Status
fmt.Printf(" %s %s\n", ui.RenderAccent(status.Peer), ui.RenderMuted(ps.URL))
switch {
case ps.Reachable:
fmt.Printf(" %s Reachable\n", ui.RenderPass("✓"))
case ps.localCredentialErr:
fmt.Printf(" %s Local credential error: %s\n", ui.RenderFail("✗"), ps.ReachError)
default:
fmt.Printf(" %s Unreachable: %s\n", ui.RenderFail("✗"), ps.ReachError)
}
if status.LocalAhead >= 0 {
fmt.Printf(" Ahead: %d commits\n", status.LocalAhead)
fmt.Printf(" Behind: %d commits\n", status.LocalBehind)
} else {
fmt.Printf(" Sync: %s\n", ui.RenderMuted("not fetched yet"))
}
if !status.LastSync.IsZero() {
fmt.Printf(" Last sync: %s\n", status.LastSync.Format("2006-01-02 15:04:05"))
}
if status.HasConflicts {
fmt.Printf(" %s Unresolved conflicts\n", ui.RenderWarn("⚠"))
}
fmt.Println()
}
return nil
}
func runFederationAddPeer(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("federation add-peer is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("federation-add-peer")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
ctx := rootCtx
name := args[0]
url := args[1]
password := federationPassword
if federationUser != "" && password == "" {
fmt.Fprint(os.Stderr, "Password: ")
pwBytes, err := term.ReadPassword(int(os.Stdin.Fd()))
fmt.Fprintln(os.Stderr)
if err != nil {
return HandleErrorRespectJSON("failed to read password: %v", err)
}
password = string(pwBytes)
}
sov := federationSov
if sov != "" {
sov = strings.ToUpper(sov)
if sov != "T1" && sov != "T2" && sov != "T3" && sov != "T4" {
return HandleErrorRespectJSON("invalid sovereignty tier: %s (must be T1, T2, T3, or T4)", federationSov)
}
}
if federationUser != "" {
peer := &storage.FederationPeer{
Name: name,
RemoteURL: url,
Username: federationUser,
Password: password,
Sovereignty: sov,
}
if err := store.AddFederationPeer(ctx, peer); err != nil {
return HandleErrorRespectJSON("failed to add peer: %v", err)
}
} else {
if err := store.AddRemote(ctx, name, url); err != nil {
return HandleErrorRespectJSON("failed to add peer: %v", err)
}
}
if jsonOutput {
return outputJSON(map[string]interface{}{
"added": name,
"url": url,
"has_auth": federationUser != "",
"sovereignty": sov,
})
}
fmt.Printf("Added peer %s: %s\n", ui.RenderAccent(name), url)
if federationUser != "" {
fmt.Printf(" User: %s (credentials stored)\n", federationUser)
}
if sov != "" {
fmt.Printf(" Sovereignty: %s\n", sov)
}
return nil
}
func runFederationRemovePeer(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("federation remove-peer is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("federation-remove-peer")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
ctx := rootCtx
name := args[0]
if err := store.RemoveRemote(ctx, name); err != nil {
return HandleErrorRespectJSON("failed to remove peer: %v", err)
}
if jsonOutput {
return outputJSON(map[string]interface{}{
"removed": name,
})
}
fmt.Printf("Removed peer: %s\n", name)
return nil
}
func runFederationListPeers(cmd *cobra.Command, args []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("federation list-peers is not supported in proxied-server mode")
}
evt := metrics.NewCommandEvent("federation-list-peers")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
ctx := rootCtx
remotes, err := store.ListRemotes(ctx)
if err != nil {
return HandleErrorRespectJSON("failed to list peers: %v", err)
}
if jsonOutput {
return outputJSON(formatFederationPeerListJSON(remotes))
}
if len(remotes) == 0 {
fmt.Println("No federation peers configured.")
return nil
}
fmt.Printf("\n%s Federation Peers:\n\n", ui.RenderAccent("🌐"))
for _, r := range remotes {
fmt.Printf(" %s %s\n", ui.RenderAccent(r.Name), ui.RenderMuted(r.URL))
}
fmt.Println()
return nil
}
type federationPeerListJSON struct {
Name string `json:"Name"`
URL string `json:"URL"`
}
func formatFederationPeerListJSON(remotes []storage.RemoteInfo) []federationPeerListJSON {
out := make([]federationPeerListJSON, 0, len(remotes))
for _, r := range remotes {
out = append(out, federationPeerListJSON{
Name: r.Name,
URL: r.URL,
})
}
return out
}