feat(api): gate the wallet-backend-fronted routes behind --wallet-backend-routes-enabled

[piyalbasu]

TL;DR

Two endpoints return a 500 to every caller in production, staging, and local dev — the account-balances one and the account-history one. Both depend on wallet-backend, which is only configured in dev; everywhere else the service has no wallet-backend client at all, so requests fail before going anywhere. Both have been publicly reachable and broken in production this whole time; no Freighter client calls either, so nothing depends on them.

This adds one config switch controlling whether those endpoints are served at all. Turned off, their paths behave as though they were never built: callers get a 404 and nothing runs behind them. Production turns them off; dev, staging, and local are unchanged. Turning them back on later is one environment-variable change and a pod restart — no rebuild and no release.

To be clear about what this is not: this does not fix either endpoint. It stops production from publicly serving errors. Making them actually work requires configuring wallet-backend for those environments, which is separate work.

Updated after review: originally gated only account-balances. @aristidesstaffieri pointed out account-history has the same dependency — confirmed, so both are now gated by one flag and it is renamed accordingly.

Implementation details (for agents)

Root cause of the 500. Both service methods fail at their first step, on the same guard, because a wallet-backend client is only constructed when both a URL and a signing key are non-empty:

freighter-backend-v2/internal/services/wallet_backend.go

Lines 178 to 181 in 0fedf7f

	client := w.configureNetworkClient(network)
	if client == nil {
	return nil, fmt.Errorf("wallet backend client not configured for network: %s", network)
	}

freighter-backend-v2/internal/services/wallet_backend.go

Lines 318 to 324 in 0fedf7f

	defer func() { w.recordWBCall("GetAccountTransactions", network, start, err) }()
	client := w.configureNetworkClient(network)
	if client == nil {
	return nil, fmt.Errorf("wallet backend client not configured for network: %s", network)
	}

freighter-backend-v2/internal/services/wallet_backend.go

Lines 69 to 88 in 0fedf7f

	// Initialize pubnet client if URL and signing key are provided
	if pubnetUrl != "" && pubnetSigningKey != "" {
	pubnetJWTGenerator, err := auth.NewJWTTokenGenerator(pubnetSigningKey)
	if err != nil {
	return nil, fmt.Errorf("creating pubnet JWT generator: %w", err)
	}
	pubnetSigner := auth.NewHTTPRequestSigner(pubnetJWTGenerator)
	pubnetClient = wbclient.NewClient(pubnetUrl, pubnetSigner)
	pubnetClient.HTTPClient = httpClient
	}
	// Initialize testnet client if URL and signing key are provided
	if testnetUrl != "" && testnetSigningKey != "" {
	testnetJWTGenerator, err := auth.NewJWTTokenGenerator(testnetSigningKey)
	if err != nil {
	return nil, fmt.Errorf("creating testnet JWT generator: %w", err)
	}
	testnetSigner := auth.NewHTTPRequestSigner(testnetJWTGenerator)
	testnetClient = wbclient.NewClient(testnetUrl, testnetSigner)
	testnetClient.HTTPClient = httpClient

Those flags default to "", and only the dev deployment sets WALLET_BACKEND_* (verified against stellar/kube master at e0ce2144d). Measured 2026-07-29 — 500 on all four combinations, prd and stg × PUBLIC and TESTNET, each instant (~0.08–0.4s, no round trip). Instant and network-independent is what distinguishes the nil-client path from an upstream outage.

Why exactly these two routes — this is the complete set, not just the two we noticed. walletBackendService is passed to exactly two handlers, NewAccountBalancesHandler and NewAccountHistoryHandler. The interface's third method, GetHealth, is wired to no HTTP handler at all (the only GetHealth call under internal/api/ is on rpcService, in rpc_health.go). So gating both closes the entire wallet-backend-dependent surface.

What changed:

• internal/config/config.go — new WalletBackendRoutesEnabled field on AppConfig.
• cmd/serve/serve.go — --wallet-backend-routes-enabled, default true. Viper's AutomaticEnv with a -→_ replacer binds it to WALLET_BACKEND_ROUTES_ENABLED with no extra wiring, the same mechanism as the existing --db-enabled / DB_ENABLED pair.
• internal/api/serve.go — the route table gains an enabled field; initHandlers skips disabled routes, so their paths fall through to the mux's 404 with no handler, no auth middleware, and no upstream call.

freighter-backend-v2/internal/api/serve.go

Lines 249 to 262 in 0fedf7f

	// The wallet-backend-fronted routes, config-gated together by
	// --wallet-backend-routes-enabled. These are the ONLY two routes that touch
	// walletBackendService, and both fail identically when it is unconfigured:
	// configureNetworkClient returns nil and the handler errors before any network
	// call, so every request 500s. wallet-backend is configured only in dev, so
	// they are disabled in production until that upstream is wired up.
	// enabled=false leaves both paths 404ing.
	//
	// They share one flag deliberately: they share one dependency and one failure
	// mode, so there is no state where enabling exactly one is correct. If a route
	// is ever added here that can work without wallet-backend, give it its own
	// gate rather than widening this one.
	{http.MethodPost, "/api/v1/accounts/balances", handlers.CustomHandler(accountBalancesHandler.GetAccountBalances), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},
	{http.MethodGet, "/api/v1/accounts/{address}/transactions", handlers.CustomHandler(accountHistoryHandler.GetAccountTransactions), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},

Why one flag rather than two. The routes share one dependency and one failure mode, so there is no state where enabling exactly one is correct — a second flag's only novel setting would be a misconfiguration. The name states the dependency rather than an endpoint list, so a future third wallet-backend route needs no new flag, and it groups with the WALLET_BACKEND_* vars already in the manifests. If a route is later added that can work without wallet-backend, it should get its own gate rather than widening this one.

Why a table field rather than conditionally appending. The table's stated purpose is to be the one source of truth that both initHandlers and the strict-mode guard test enumerate, so a route "cannot silently skip the auth guard." Making the table's shape depend on config would break that property and hide disabled routes from the guard test. The cost is a mechanical true on the other 9 entries, since Go positional composite literals require every field.

A trap this had to avoid. testCfg builds a mostly zero-value AppConfig, so the flag would have defaulted to false in tests — and AllUserFacingRoutesGatedInStrict, which probes every gated route for a 401, would have seen a 404 and failed in a way that reads like an auth regression. testCfg now sets it true explicitly, and that guard's assertion message names the unregistered-route case so a future failure is self-explanatory.

Tests. Table-driven over both routes — 404 when disabled, 401-in-strict when enabled (the latter proves each route is registered and still auth-gated, so the flag can't quietly become an auth bypass). Adding a third wallet-backend route extends that coverage by one line rather than being silently missed. Plus WalletBackendRoutesGatedTogether, which asserts routes() disables exactly these two patterns — it exists because gating only one route, leaving the other publicly 500ing in prd, would otherwise pass every other test. Command-level tests cover the config path prd actually uses (flag default, and WALLET_BACKEND_ROUTES_ENABLED=false/=true reaching the config field through viper), since the api-package tests set the field directly and would stay green through a renamed flag or broken env binding — a fail-open.

Mutation-tested rather than assumed. A passing test isn't evidence it guards anything, so each guard was checked against the break it's meant to catch:

Mutation	Caught by
flag default flipped to false	DefaultsTrue
flag renamed to a different word	FalseFromEnv
v.AutomaticEnv() removed	FalseFromEnv
account-history reverted to always-enabled	DisabledNotRegistered/account-history and GatedTogether

Verification. Full suite green (19 packages); go vet, gofmt, and shadow clean. Beyond the tests, I ran the built binary both ways, since the env var is what kube actually sets:

Run	balances	transactions	token-prices	ping
WALLET_BACKEND_ROUTES_ENABLED=false	404	404	400	200
flag unset (default)	500	500	400	200

The off run logs route disabled by config; not registering once per route, naming both patterns; the on run logs neither. The 500s in the second row reproduce the prd/stg failure exactly, which independently confirms the diagnosis above.

golangci-lint and gofumpt aren't installed in my environment and staticcheck is built against an older Go than this module requires, so make check can't complete locally — those three need CI to cover.

Observability note. While disabled, the metrics middleware labels unmatched requests handler="unknown", so this traffic is counted there rather than under its own handler labels. Anything keyed on those labels goes quiet — intended, but worth knowing before someone hunts for the missing series.

Deploy ordering. The companion stellar/kube change must land before the prd image bump. WALLET_BACKEND_ROUTES_ENABLED is inert on images that predate the flag, so that order gives zero exposure window; the reverse ships the new image with both routes still enabled in prd until the manifest catches up.

Follow-ups / out of scope:

• Neither stg nor prd can serve these routes until WALLET_BACKEND_* is configured. The signing keys are secrets and must be seeded in each namespace's own Vault folder, since cross-namespace reads are blocked by the restrict-external-secrets-to-namespaces Kyverno policy.
• Dev has no WALLET_BACKEND_TESTNET_SIGNING_KEY, so ?network=TESTNET 500s there today. Pre-existing and unrelated to this change.
• The v2 runbooks write the balances path as /api/v1/account-balances, which does not exist — verified against prd, that path 404s while the real one 500s. Tracked separately; note freighter-backend v1 genuinely serves /api/v1/account-balances/<pubkey>, so a blanket rename would break the v1 runbooks.
• Design doc at docs/design/2026-07-29-wallet-backend-routes-toggle.md, which also records the rejected alternatives (deriving the gate from whether wallet-backend is configured, two independent flags, and blocking at the Traefik edge).

[Copilot]

Pull request overview

Adds a runtime configuration gate for the account-balances route, allowing production to return 404 while its wallet-backend dependency remains unavailable.

Changes:

• Adds the --balances-enabled / BALANCES_ENABLED setting.
• Conditionally registers the balances route.
• Tests enabled and disabled routing behavior and documents deployment considerations.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal/config/config.go	Defines the balances toggle.
cmd/serve/serve.go	Registers the CLI/environment-backed flag.
internal/api/serve.go	Skips disabled routes during mux registration.
internal/api/serve_test.go	Tests disabled and authenticated enabled states.
docs/design/2026-07-29-balances-endpoint-toggle.md	Documents design and deployment behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aristidesstaffieri]

should we also gate  GET /api/v1/accounts/{address}/transactions using the same flag, it also relies on wallet backend

[piyalbasu]

Yes — confirmed, and done in 0fedf7f. Thanks, this was the right call.

TL;DR: You're right that it has the same dependency, and it's broken the same way right now — I measured it returning errors in both production and staging, on both networks. Both endpoints are now turned off by one shared switch, which I've renamed to describe the dependency rather than one endpoint. I also checked whether anything else depends on wallet-backend: these two are the complete set.

Implementation details (for agents)

Confirmation, in code. GetAccountTransactions hits the identical nil-client guard as the balances path, reached through the same configureNetworkClient, which returns nil when no WALLET_BACKEND_* URL + signing-key pair is configured:

freighter-backend-v2/internal/services/wallet_backend.go

Lines 318 to 324 in 0fedf7f

	defer func() { w.recordWBCall("GetAccountTransactions", network, start, err) }()
	client := w.configureNetworkClient(network)
	if client == nil {
	return nil, fmt.Errorf("wallet backend client not configured for network: %s", network)
	}

Confirmation, live. Measured 2026-07-29, anonymous (both deployments run --auth-mode permissive by flag default, so these reach the handler):

	prd	stg
GET /accounts/{addr}/transactions?network=PUBLIC	500 ~0.42s	500 ~0.16s
GET /accounts/{addr}/transactions?network=TESTNET	500 ~0.08s	500 ~0.17s

All four instant and network-independent, which is what separates the nil-client path from a wallet-backend outage.

Completeness check — these two are the whole set. Rather than gate the two we'd noticed, I checked what else touches the service: walletBackendService is passed to exactly two handlers (NewAccountBalancesHandler, NewAccountHistoryHandler), and the interface's third method GetHealth is wired to no HTTP handler at all — the only GetHealth call under internal/api/ is on rpcService in rpc_health.go. So nothing else is exposed by this dependency.

Rename:

BalancesEnabled     -> WalletBackendRoutesEnabled
--balances-enabled  -> --wallet-backend-routes-enabled
BALANCES_ENABLED    -> WALLET_BACKEND_ROUTES_ENABLED

One flag, not two. They share one dependency and one failure mode, so there's no state where enabling exactly one is correct — a second flag's only novel setting would be a misconfiguration. Naming it after the dependency also means a future third wallet-backend route needs no new flag, and it groups with the WALLET_BACKEND_* vars already in the manifests. If a route is later added that can work without wallet-backend, it should get its own gate rather than widening this one — that's noted in the table comment.

freighter-backend-v2/internal/api/serve.go

Lines 249 to 262 in 0fedf7f

	// The wallet-backend-fronted routes, config-gated together by
	// --wallet-backend-routes-enabled. These are the ONLY two routes that touch
	// walletBackendService, and both fail identically when it is unconfigured:
	// configureNetworkClient returns nil and the handler errors before any network
	// call, so every request 500s. wallet-backend is configured only in dev, so
	// they are disabled in production until that upstream is wired up.
	// enabled=false leaves both paths 404ing.
	//
	// They share one flag deliberately: they share one dependency and one failure
	// mode, so there is no state where enabling exactly one is correct. If a route
	// is ever added here that can work without wallet-backend, give it its own
	// gate rather than widening this one.
	{http.MethodPost, "/api/v1/accounts/balances", handlers.CustomHandler(accountBalancesHandler.GetAccountBalances), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},
	{http.MethodGet, "/api/v1/accounts/{address}/transactions", handlers.CustomHandler(accountHistoryHandler.GetAccountTransactions), true, s.cfg.AppConfig.WalletBackendRoutesEnabled},

Tests are now table-driven over both routes, so a third extends coverage by one line instead of being missed. I also added WalletBackendRoutesGatedTogether, asserting routes() disables exactly these two patterns — specifically because gating only one route (the bug you caught) would otherwise pass every other test. Mutation-checked: reverting account-history to always-enabled fails both DisabledNotRegistered/account-history and GatedTogether.

Verified on the built binary with the new variable, both routes:

Run	balances	transactions	token-prices	ping
WALLET_BACKEND_ROUTES_ENABLED=false	404	404	400	200
flag unset (default)	500	500	400	200

Off logs route disabled by config; not registering once per route, naming both patterns; on logs neither.

Companion PRs updated for the rename: stellar/kube#4783 (prd manifest) and stellar/wallet-eng-runbooks#21 (on-call note now covers both routes). The kube one still needs to land before the next prd image bump — the variable is inert on the running image, so that order closes the window rather than opening one.