[client,android] Generate debug bundle to file (#7528)

* [client] Add a debug bundle file export to the Android bridge

The Android app can only upload a debug bundle and hand the user a key.
Users who want to inspect what leaves their device before sharing it
have no way to get the zip itself. Add DebugBundleFile, which generates
the bundle into the cache directory and returns its path instead of
uploading; the app copies it wherever the user chose and removes it.

DebugBundle keeps its behavior. Both entry points share the unexported
debugBundle with an upload switch, so the body stays where it was and
merges cleanly with the MDM overlay change on main.

Because the file variant leaves the zip to the caller and the upload
variant only removes it after the upload finishes, a process killed in
between leaves a zip behind in the cache. Remove stale bundles before
generating a new one: RemoveStaleBundles deletes zips matching the
generator's pattern that are older than an hour. Remote debug jobs write
to the same directory, so younger files are treated as still in use.

* Preserve network map for debug bundle on Android

* [client] Keep exported Android debug bundles out of the stale cleanup

DebugBundleFile hands the zip to the caller, but the file kept the
netbird.debug.*.zip name that RemoveStaleBundles matches, so a later
debug run could delete it once it was older than an hour. Rename the
exported bundle to netbird.debug-file.*.zip after generation so the
cleanup only ever touches bundles no caller owns.

* [client] Warn when a stale debug bundle cannot be removed

A failed removal means bundles pile up in the cache directory, so log it
at Warn instead of Debug. A file that is already gone was removed by a
concurrent cleanup and is skipped silently.

* [client] Drop the outdated debugBundle comment

The comment still said the file variant leaves the zip in place, but it
is renamed by debug.ExportBundle since the stale-cleanup change.

* [client] Test that the network map reaches the debug bundle

Cover both halves of the path Android now relies on: the engine keeps
the latest sync response once persistence is enabled, and the bundle
generator writes it to network_map.json (anonymized or not) and omits
the file when there is no sync response.

* [client] Remove abandoned exported debug bundles after a day

An exported bundle is owned by the caller, but if the app is killed
before it copies and deletes the file, nothing ever removes it from the
cache directory. Let RemoveStaleBundles also match exported bundles,
with a 24 hour max age instead of the caller-provided one, so a bundle
that is still being saved survives while an abandoned one goes.

client/android/client.go

@@ -213,6 +213,7 @@ func (c *Client) Run(platformFiles PlatformFiles, urlOpener URLOpener, isAndroid
 	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder,
 		internal.WithNetEvents(c.netMgr))
 	c.setState(cfg, cacheDir, cfgFile, connectClient)
+	connectClient.SetSyncResponsePersistence(true)
 	// This path runs the interactive SSO flow, so reaching here means the peer
 	// is authenticated again — release the latch Status() reports from. Clear
 	// only once the fresh connect client is installed: until then Status()
@@ -256,6 +257,7 @@ func (c *Client) RunWithoutLogin(platformFiles PlatformFiles, dns *DNSList, dnsR
 	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder,
 		internal.WithNetEvents(c.netMgr))
 	c.setState(cfg, cacheDir, cfgFile, connectClient)
+	connectClient.SetSyncResponsePersistence(true)
 	return connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
 }
 
@@ -327,6 +329,19 @@ func (c *Client) NotifyNetworkChange() {
 // or "strict"; strict also anonymizes internal IP ranges, peer names, and
 // WireGuard public keys, and implies anonymize.
 func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool, anonymizeLevel string) (string, error) {
+	return c.debugBundle(platformFiles, anonymize, anonymizeLevel, true)
+}
+
+// DebugBundleFile generates a debug bundle and returns the path of the zip in
+// the cache directory instead of uploading it, so the app can hand the file to
+// the user for inspection. The caller owns the file and removes it once done;
+// the stale-bundle cleanup of later runs removes it only after a day.
+// anonymize and anonymizeLevel behave as in DebugBundle.
+func (c *Client) DebugBundleFile(platformFiles PlatformFiles, anonymize bool, anonymizeLevel string) (string, error) {
+	return c.debugBundle(platformFiles, anonymize, anonymizeLevel, false)
+}
+
+func (c *Client) debugBundle(platformFiles PlatformFiles, anonymize bool, anonymizeLevel string, upload bool) (string, error) {
 	cfg, cacheDir, cc := c.stateSnapshot()
 
 	// If the engine hasn't been started, load config from disk
@@ -342,6 +357,11 @@ func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool, anonym
 		cacheDir = platformFiles.CacheDir()
 	}
 
+	// Clear what an interrupted earlier run may have left in the cache before
+	// adding to it. Remote debug jobs write to the same directory, so anything
+	// younger than an hour is treated as possibly still in use.
+	debug.RemoveStaleBundles(cacheDir, time.Hour)
+
 	deps := debug.GeneratorDependencies{
 		InternalConfig: cfg,
 		StatusRecorder: c.recorder,
@@ -379,6 +399,9 @@ func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool, anonym
 	if err != nil {
 		return "", fmt.Errorf("generate debug bundle: %w", err)
 	}
+	if !upload {
+		return debug.ExportBundle(path)
+	}
 	defer func() {
 		if err := os.Remove(path); err != nil {
 			log.Errorf("failed to remove debug bundle file: %v", err)

client/internal/debug/debug.go

@@ -379,9 +379,38 @@ func NewBundleGenerator(deps GeneratorDependencies, cfg BundleConfig) *BundleGen
 	}
 }
 
+// bundleFilePattern names the bundle zips Generate creates in tempDir; the
+// asterisk is filled in by os.CreateTemp.
+const bundleFilePattern = "netbird.debug.*.zip"
+
+const exportedBundlePrefix = "netbird.debug-file."
+
+const exportedBundleMaxAge = 24 * time.Hour
+
+// RemoveStaleBundles deletes bundle zips that an interrupted generation or
+// upload left behind in dir. Only files older than maxAge go, so a bundle that
+// another caller is still writing or uploading in the same directory survives.
+// Exported bundles are kept for exportedBundleMaxAge instead.
+func RemoveStaleBundles(dir string, maxAge time.Duration) {
+	removeStaleFiles(dir, bundleFilePattern, maxAge)
+	removeStaleFiles(dir, exportedBundlePrefix+"*.zip", exportedBundleMaxAge)
+}
+
+// ExportBundle renames a generated bundle out of the RemoveStaleBundles pattern
+// and returns the new path. The caller owns the file from then on; an export
+// abandoned for longer than exportedBundleMaxAge is removed by RemoveStaleBundles.
+func ExportBundle(path string) (string, error) {
+	base := strings.TrimPrefix(filepath.Base(path), strings.SplitN(bundleFilePattern, "*", 2)[0])
+	exported := filepath.Join(filepath.Dir(path), exportedBundlePrefix+base)
+	if err := os.Rename(path, exported); err != nil {
+		return "", fmt.Errorf("export debug bundle: %w", err)
+	}
+	return exported, nil
+}
+
 // Generate creates a debug bundle and returns the location.
 func (g *BundleGenerator) Generate() (resp string, err error) {
-	bundlePath, err := os.CreateTemp(g.tempDir, "netbird.debug.*.zip")
+	bundlePath, err := os.CreateTemp(g.tempDir, bundleFilePattern)
 	if err != nil {
 		return "", fmt.Errorf("create zip file: %w", err)
 	}
@@ -1725,3 +1754,26 @@ func anonymizeSlice(v []any, anonymizer *anonymize.Anonymizer) []any {
 	}
 	return v
 }
+
+func removeStaleFiles(dir, pattern string, maxAge time.Duration) {
+	matches, err := filepath.Glob(filepath.Join(dir, pattern))
+	if err != nil {
+		log.Debugf("glob stale debug bundles in %s: %v", dir, err)
+		return
+	}
+
+	cutoff := time.Now().Add(-maxAge)
+	for _, path := range matches {
+		info, err := os.Stat(path)
+		if err != nil || info.ModTime().After(cutoff) {
+			continue
+		}
+		if err := os.Remove(path); err != nil {
+			if !errors.Is(err, fs.ErrNotExist) {
+				log.Warnf("remove stale debug bundle %s: %v", path, err)
+			}
+			continue
+		}
+		log.Infof("removed stale debug bundle %s", path)
+	}
+}

client/internal/debug/debug_test.go

@@ -4,6 +4,7 @@ import (
 	"archive/zip"
 	"bytes"
 	"encoding/json"
+	"fmt"
 	"net"
 	"net/netip"
 	"net/url"
@@ -969,3 +970,52 @@ func renderAddConfigSpecific(g *BundleGenerator) string {
 func newAnonymizerForTest() *anonymize.Anonymizer {
 	return anonymize.NewAnonymizer(anonymize.DefaultAddresses())
 }
+
+func TestRemoveStaleBundles(t *testing.T) {
+	dir := t.TempDir()
+	stale := filepath.Join(dir, "netbird.debug.111.zip")
+	fresh := filepath.Join(dir, "netbird.debug.222.zip")
+	other := filepath.Join(dir, "netbird.debug.333.txt")
+	owned := filepath.Join(dir, "netbird.debug.444.zip")
+	abandoned := filepath.Join(dir, "netbird.debug.555.zip")
+	for _, p := range []string{stale, fresh, other, owned, abandoned} {
+		require.NoError(t, os.WriteFile(p, []byte("x"), 0o600))
+	}
+	exported, err := ExportBundle(owned)
+	require.NoError(t, err)
+	exportedAbandoned, err := ExportBundle(abandoned)
+	require.NoError(t, err)
+	old := time.Now().Add(-2 * time.Hour)
+	for _, p := range []string{stale, other, exported} {
+		require.NoError(t, os.Chtimes(p, old, old))
+	}
+	ancient := time.Now().Add(-exportedBundleMaxAge - time.Hour)
+	require.NoError(t, os.Chtimes(exportedAbandoned, ancient, ancient))
+
+	RemoveStaleBundles(dir, time.Hour)
+
+	assert.NoFileExists(t, stale, "bundle older than maxAge should be removed")
+	assert.FileExists(t, fresh, "bundle younger than maxAge must survive, it may still be uploading")
+	assert.FileExists(t, other, "files outside the bundle pattern must not be touched")
+	assert.NoFileExists(t, owned)
+	assert.FileExists(t, exported, "exported bundle is caller-owned and must survive maxAge")
+	assert.NoFileExists(t, exportedAbandoned, "exported bundle older than exportedBundleMaxAge is abandoned")
+}
+
+func TestBundleIncludesNetworkMap(t *testing.T) {
+	for _, anonymize := range []bool{false, true} {
+		t.Run(fmt.Sprintf("anonymize=%t", anonymize), func(t *testing.T) {
+			g := NewBundleGenerator(GeneratorDependencies{
+				SyncResponse: &mgmProto.SyncResponse{NetworkMap: &mgmProto.NetworkMap{Serial: 1}},
+			}, BundleConfig{Anonymize: anonymize})
+
+			require.Contains(t, bundleEntries(t, g), "network_map.json")
+		})
+	}
+}
+
+func TestBundleOmitsNetworkMapWithoutSyncResponse(t *testing.T) {
+	g := NewBundleGenerator(GeneratorDependencies{}, BundleConfig{})
+
+	require.NotContains(t, bundleEntries(t, g), "network_map.json")
+}

client/internal/engine_test.go

@@ -1493,3 +1493,21 @@ func TestOverlayAddrsFromAllowedIPs(t *testing.T) {
 		})
 	}
 }
+
+func TestEngine_SyncResponsePersistence(t *testing.T) {
+	e := &Engine{}
+
+	_, err := e.GetLatestSyncResponse()
+	require.Error(t, err, "persistence is disabled by default")
+
+	e.SetSyncResponsePersistence(true)
+	e.persistSyncResponse(&mgmtProto.SyncResponse{NetworkMap: &mgmtProto.NetworkMap{Serial: 7}})
+
+	got, err := e.GetLatestSyncResponse()
+	require.NoError(t, err)
+	assert.Equal(t, uint64(7), got.GetNetworkMap().GetSerial())
+
+	e.SetSyncResponsePersistence(false)
+	_, err = e.GetLatestSyncResponse()
+	require.Error(t, err)
+}