qa: route all radiance egress through an upstream SOCKS5 + bandit probe driver

.github/workflows/go.yml

@@ -5,9 +5,12 @@ name: Go
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "refactor" ]
+  # No branch filter here — run CI on every pull request regardless of target
+  # branch. This catches PRs aimed at refactor, feature branches, or anything
+  # else, not just main. The previous filter ("branches: [ main ]") silently
+  # skipped CI for PRs into refactor, which is our active dev branch.
   pull_request:
-    branches: [ "main" ]
 
 jobs:
 
@@ -21,6 +24,13 @@ jobs:
       with:
         go-version-file: "go.mod"
 
+    - name: Check for slog overwrite calls in tests
+      run: |
+        if grep -rn 'slog\.SetDefault\|slog\.SetLogLoggerLevel' --include='*_test.go' .; then
+          echo "::error::Test files should not upate the slog.Default logger or level. This pollutes the output."
+          exit 1
+        fi
+
     - name: Build
       run: go build -v -tags with_clash_api ./...
     - name: Test

AGENTS.md

@@ -1 +1,61 @@
 - Telemetry attributes: follow rules in https://github.com/getlantern/semconv/blob/main/AGENTS.md
+
+## Code Comments
+
+**Default: no comment.** Only add one if a specific *why* is load-bearing — invariant, concurrency guarantee, error condition, zero-value behavior, non-obvious caller contract, or a constraint that would surprise the reader. Aesthetic "this section is well-documented" comments are noise.
+
+Before writing any comment, run this checklist on the proposed text. If any answer is yes, delete or rewrite:
+
+1. Does it restate the identifier name or signature? (`// Foo does foo`, `// updateX manages X across Y`)
+2. Does it narrate what the visible next line does? (`// Cancel any existing listener` immediately above `cancel()`)
+3. Does it open with a generic lifecycle/management preamble before getting to the point? (`// manages the lifecycle of...`, `// handles the X for Y`)
+4. Does it reference tickets, coworkers, sibling files, commit SHAs, or other code locations? Those belong in the commit message / PR description — they rot in source.
+5. Does it describe the mechanism instead of the contract? (`authenticates via peer credentials over a Unix socket` vs. `authenticates each connection`)
+
+Lead with the *why*, not a summary of the function. If the only thing you can write is a summary, the comment isn't needed.
+
+Examples:
+
+```go
+// BAD — restates name, generic preamble, narrates the code
+// updateURLTestListener manages the lifecycle of the URL test result listener
+// across VPN status changes. Connected always re-attaches (canceling any
+// existing listener) so a stale event still leaves the listener bound to
+// the live storage.
+
+// GOOD — leads with the trap, no narration
+// Status events are dispatched in unordered goroutines, so reacting to
+// intermediate statuses risks a stale handler tearing down a listener
+// a concurrent Connected handler just attached. Only Connected (which
+// re-attaches unconditionally) and terminal-down statuses are acted on.
+```
+
+```go
+// BAD — narrates the next line
+// Cancel any in-flight offline tests and wait for them to finish.
+c.offlineTestCancel()
+<-done
+
+// GOOD — no comment; the names already say it
+c.offlineTestCancel()
+<-done
+```
+
+```go
+// BAD — references ticket and coworker
+// Per Freshdesk #172640 (reported by Alice), saveServers held the lock
+// for 1+ minute. We now release access before disk I/O.
+
+// GOOD — states the invariant; the ticket lives in git history
+// access is released before disk I/O so a slow write can't starve readers.
+```
+
+Before writing an inline comment, consider whether a doc comment on the enclosing function or type would make it unnecessary. Prefer documenting contracts at the declaration over explaining implementation details inline.
+
+TODO comments must state *what* needs to happen and *why* it isn't done now. `TODO: ???` is not actionable — either resolve it or remove it.
+
+## Go Doc Comments
+
+- When a doc comment is warranted on an exported identifier, start it with the identifier's name and use complete sentences: `// Foo does X.` The first sentence is the summary shown by `go doc` and pkg.go.dev.
+- Package comments: one per package, above the `package` clause (conventionally in `doc.go` for larger packages), starting with `// Package foo ...`.
+- Formatting (gofmt-aware since Go 1.19): blank lines separate paragraphs; indented lines render as code blocks; lines starting with `-`, `*`, or `1.` render as lists; `[Name]` links to other symbols; `# Heading` renders as a heading. Avoid HTML and manual wrapping.

Makefile

@@ -4,9 +4,5 @@ proto:
 	protoc --go_out=. --plugin=build/protoc-gen-go --go_opt=paths=source_relative api/protos/subscription.proto
 	protoc --go_out=. --plugin=build/protoc-gen-go --go_opt=paths=source_relative issue/issue.proto
 
-mock:
-	go install go.uber.org/mock/mockgen@latest
-	go generate ./...
-
 test:
 	go test -v ./...

README.md

@@ -34,50 +34,103 @@ Available variables:
 *   `RADIANCE_FEATURE_OVERRIDE`: Comma-separated list of feature flags to force-enable on the server side. If set, the value is sent as the `X-Lantern-Feature-Override` header on config requests in any environment, and it is recommended for testing/non-production use. For example, `RADIANCE_FEATURE_OVERRIDE=bandit_assignment` enables bandit-based proxy assignment during testing.
 
 
-## Packages
+## Architecture
 
-Use `common.Init` to setup directories and configure loggers. 
-> [!note]
-> This isn't necessary if `NewRadiance` was called as it will call `Init` for you.
+Radiance is structured around a `LocalBackend` pattern that ties together all core functionality: configuration, servers, VPN connection, account management, issue reporting, and telemetry. The `LocalBackend` is the central coordinator and should be the primary interface for interacting with Radiance programmatically.
 
-### `vpn`
+In addition to being the core of the [Lantern client](https://github.com/getlantern/lantern), radiance also provides a standalone daemon and CLI:
 
-The `vpn` package provides high-level functions for controlling the VPN tunnel. 
+- **`lanternd`** — the VPN daemon that runs the `LocalBackend` and exposes an IPC server. It can run in the foreground or be installed as a system service.
+- **`lantern`** — a CLI client that communicates with the daemon over IPC.
 
-To connect to the best available server, you can use the `QuickConnect` function. This function takes a server group (`servers.SGLantern`, `servers.SGUser`, or `"all"`) and a `PlatformInterface` as input. For example:
+### Building CLI & Daemon
 
-```go
-err := vpn.QuickConnect(servers.SGLantern, platIfce)
+From the `cmd/` directory:
+
+```sh
+make build-daemon
+make build-cli
+```
+Or using [just](https://github.com/casey/just)
+```sh
+just build-daemon
+just build-cli
 ```
 
-will connect to the best Lantern server, while:
+Both binaries are output to `bin/`. You can also run the daemon directly with `make run-daemon`.
 
-```go
-err := vpn.QuickConnect("all", platIfce)
+### Running
+
+```sh
+# Start the daemon
+lanternd run --data-path ~/data --log-path ~/logs
+
+# Install/uninstall as a system service
+lanternd install --data-path ~/data --log-path ~/logs
+lanternd uninstall
+
+# CLI commands (requires a running daemon)
+lantern connect [--tag <server-tag>]
+lantern disconnect
+lantern status
+lantern servers
+lantern account login
+lantern subscription
+lantern split-tunnel
+lantern logs
+lantern ip
 ```
 
-will connect to the best overall.
+## Packages
+
+Use `common.Init` to setup directories and configure loggers.
+> [!note]
+> This isn't necessary if `NewLocalBackend` was called as it will call `Init` for you.
+
+### `backend`
+
+The `backend` package provides `LocalBackend`, the main entry point for all Radiance functionality. Create one with `NewLocalBackend(ctx, opts)` and call `Start()` to begin fetching configuration and serving requests. `LocalBackend` owns and coordinates the `VPNClient`, `ServerManager`, `ConfigHandler`, `AccountClient`, `IssueReporter`, and telemetry.
+
+### `vpn`
 
-You can also connect to a specific server using `ConnectToServer`. This function requires a server group, a server tag, and a `PlatformInterface`. For example:
+The `vpn` package provides `VPNClient`, which manages the lifecycle of the VPN tunnel.
 
 ```go
-err := vpn.ConnectToServer(servers.SGUser, "my-server", platIfce)
+client := vpn.NewVPNClient(dataPath, logger, platformIfce)
+err := client.Connect(boxOptions)
 ```
 
-Both `QuickConnect` and `ConnectToServer` can be called without disconnecting first, allowing you to seamlessly switch between servers or connection modes.
+`Connect` can be called without disconnecting first, allowing you to seamlessly switch between servers. Once connected, you can query status or view `Connections`. To stop the VPN, call `Disconnect`.
 
-Once connected, you can check the `GetStatus` or view `ActiveConnections`. To stop the VPN, simply call `Disconnect`. The package also supports reconnecting to the last used server with `Reconnect`.
+> [!note]
+> In most cases, you should use the `LocalBackend` methods (`ConnectVPN`, `DisconnectVPN`, `RestartVPN`, `VPNStatus`) rather than using `VPNClient` directly.
 
-This package also includes split tunneling capabilities, allowing you to include or exclude specific applications, domains, or IP addresses from the VPN tunnel. You can manage split tunneling by creating a `SplitTunnel` handler with `NewSplitTunnelHandler`. This handler allows you to `Enable` or `Disable` split tunneling, `AddItem` or `RemoveItem` from the filter, and view the current `Filters`.
+This package also includes split tunneling capabilities via the `SplitTunnel` type, allowing you to include or exclude specific applications, domains, or IP addresses from the VPN tunnel.
 
 ### `servers`
 
-The `servers` package is responsible for managing all VPN server configurations, separating them into two groups: `lantern` (official Lantern servers) and `user` (user-provided servers).
+The `servers` package manages all VPN server configurations, separating them into two groups: `lantern` (official Lantern servers fetched from the config) and `user` (user-provided servers).
 
-The `Manager` allows you to `AddServers` and `RemoveServer` configurations. You can retrieve the config for a specific server with `GetServerByTag` or use `Servers` to retrieve all configs.
+The `Manager` allows you to `AddServers` and `RemoveServers` configurations. You can retrieve the config for a specific server with `GetServerByTag` or use `Servers` to retrieve all configs.
 
 > [!caution]
-> While you can get a new `Manager` instance with `NewManager`, it is recommended to use `Radiance.ServerManager`. This will return the shared manager instance. `NewManager` can be useful for retrieving server information if you don't have access to the shared instance, but the new instance should not be kept as it won't stay in sync and adding server configs to it will overwrite existing configs if both manager instances are pointed to the same server file.
+> While you can get a new `Manager` instance with `NewManager`, it is recommended to use the `LocalBackend`'s server methods (`Servers`, `AddServers`, `RemoveServers`, `GetServerByTag`). These use the shared manager instance. `NewManager` can be useful for retrieving server information if you don't have access to the shared instance, but the new instance should not be kept as it won't stay in sync.
+
+A key feature of this package is the ability to add private servers from a server manager via an access token using `AddPrivateServer`. This process uses Trust-on-first-use (TOFU) to securely add the server. Once a private server is added, you can invite other users with `InviteToPrivateServer` and revoke access with `RevokePrivateServerInvite`.
+
+### `ipc`
+
+The `ipc` package provides the communication layer between the `lantern` CLI and the `lanternd` daemon. The `ipc.Server` exposes an HTTP API backed by the `LocalBackend`, and the `ipc.Client` provides a typed Go client for calling it. All communication happens over a local socket.
+
+### `account`
+
+The `account` package handles user authentication (email/password and OAuth), signup, email verification, account recovery, device management, and subscription operations. It communicates with the Lantern account server and caches authentication state locally.
+
+### `config`
+
+The `config` package fetches proxy configuration from the Lantern API on a polling interval and emits `NewConfigEvent` events when the configuration changes. The `LocalBackend` subscribes to these events to update server configurations automatically.
+
+### `events`
 
-A key feature of this package is the ability to add private servers from a server manager via an access token using `AddPrivateServer`. This process uses Trust-on-first-use (TOFU) to securely add the server. Once a private server is added, you can use the manager to invite other users to it with `InviteToPrivateServer` and revoke access with `RevokePrivateServerInvite`.
+A generic pub-sub event system used throughout Radiance for decoupled communication between components (config changes, VPN status updates, log entries, etc.).
 

account/auth.go

@@ -0,0 +1,117 @@
+package account
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"math/big"
+
+	"github.com/1Password/srp"
+	"golang.org/x/crypto/pbkdf2"
+	"google.golang.org/protobuf/proto"
+
+	"github.com/getlantern/radiance/account/protos"
+)
+
+func (a *Client) fetchSalt(ctx context.Context, email string) (*protos.GetSaltResponse, error) {
+	query := map[string]string{"email": email}
+	resp, err := a.sendRequest(ctx, "GET", "/users/salt", query, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	var salt protos.GetSaltResponse
+	if err := proto.Unmarshal(resp, &salt); err != nil {
+		return nil, fmt.Errorf("unmarshaling salt response: %w", err)
+	}
+	return &salt, nil
+}
+
+// clientProof performs the SRP authentication flow to generate the client proof for the given email and password.
+func (a *Client) clientProof(ctx context.Context, email, password string, salt []byte) ([]byte, error) {
+	srpClient, err := newSRPClient(email, password, salt)
+	if err != nil {
+		return nil, err
+	}
+
+	A := srpClient.EphemeralPublic()
+	data := &protos.PrepareRequest{
+		Email: email,
+		A:     A.Bytes(),
+	}
+	resp, err := a.sendRequest(ctx, "POST", "/users/prepare", nil, nil, data)
+	if err != nil {
+		return nil, err
+	}
+
+	var srpB protos.PrepareResponse
+	if err := proto.Unmarshal(resp, &srpB); err != nil {
+		return nil, fmt.Errorf("unmarshaling prepare response: %w", err)
+	}
+	B := big.NewInt(0).SetBytes(srpB.B)
+	if err = srpClient.SetOthersPublic(B); err != nil {
+		return nil, err
+	}
+
+	key, err := srpClient.Key()
+	if err != nil || key == nil {
+		return nil, fmt.Errorf("user_not_found error while generating Client key %w", err)
+	}
+	if !srpClient.GoodServerProof(salt, email, srpB.Proof) {
+		return nil, fmt.Errorf("user_not_found checking server proof %w", err)
+	}
+
+	proof, err := srpClient.ClientProof()
+	if err != nil {
+		return nil, fmt.Errorf("user_not_found generating client proof %w", err)
+	}
+	return proof, nil
+}
+
+// getSalt retrieves the salt for the given email address or it's cached value.
+func (a *Client) getSalt(ctx context.Context, email string) ([]byte, error) {
+	if cached := a.getSaltCached(); cached != nil {
+		return cached, nil
+	}
+	resp, err := a.fetchSalt(ctx, email)
+	if err != nil {
+		return nil, err
+	}
+	return resp.Salt, nil
+}
+
+const group = srp.RFC5054Group3072
+
+func newSRPClient(email, password string, salt []byte) (*srp.SRP, error) {
+	if len(salt) == 0 || len(password) == 0 || len(email) == 0 {
+		return nil, errors.New("salt, password and email should not be empty")
+	}
+
+	encryptedKey, err := generateEncryptedKey(password, email, salt)
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate encrypted key: %w", err)
+	}
+
+	return srp.NewSRPClient(srp.KnownGroups[group], encryptedKey, nil), nil
+}
+
+func generateEncryptedKey(password, email string, salt []byte) (*big.Int, error) {
+	if len(salt) == 0 || len(password) == 0 || len(email) == 0 {
+		return nil, errors.New("salt or password or email is empty")
+	}
+	combinedInput := password + email
+	encryptedKey := pbkdf2.Key([]byte(combinedInput), salt, 4096, 32, sha256.New)
+	encryptedKeyBigInt := big.NewInt(0).SetBytes(encryptedKey)
+	return encryptedKeyBigInt, nil
+}
+
+func generateSalt() ([]byte, error) {
+	salt := make([]byte, 16)
+	if n, err := rand.Read(salt); err != nil {
+		return nil, err
+	} else if n != 16 {
+		return nil, errors.New("failed to generate 16 byte salt")
+	}
+	return salt, nil
+}