From 00be145044caea72fabcbbfb49b926e6349aec76 Mon Sep 17 00:00:00 2001
From: Roger <moond4rk13@gmail.com>
Date: Sat, 16 May 2026 12:26:57 +0800
Subject: [PATCH] refactor(browser): publicize key-injection capability api
 (#597)

Promote keyRetrieversSetter to public KeyManager and lift
keychainPasswordSetter from browser_darwin.go into browser.go as
KeychainPasswordReceiver. Engines already implement these methods;
only type-assertion sites switch to the public interface names.
---
 browser/browser.go         | 11 +++++++----
 browser/browser_darwin.go  | 22 +++++-----------------
 browser/browser_linux.go   |  4 ++--
 browser/browser_windows.go |  4 ++--
 4 files changed, 16 insertions(+), 25 deletions(-)

diff --git a/browser/browser.go b/browser/browser.go
index 291d42c..556e6a7 100644
--- a/browser/browser.go
+++ b/browser/browser.go
@@ -111,13 +111,16 @@ func pickFromConfigs(configs []types.BrowserConfig, opts PickOptions) ([]Browser
 	return browsers, nil
 }
 
-// keyRetrieversSetter is an optional capability interface. Chromium variants implement it to
-// receive the per-tier master-key retrievers (V10 / V11 / V20) as a single Retrievers struct;
-// Firefox and Safari do not.
-type keyRetrieversSetter interface {
+// KeyManager is implemented by engines that accept externally-provided master-key retrievers (Chromium family only).
+type KeyManager interface {
 	SetKeyRetrievers(keyretriever.Retrievers)
 }
 
+// KeychainPasswordReceiver is implemented by engines that need the macOS login password (Safari only).
+type KeychainPasswordReceiver interface {
+	SetKeychainPassword(string)
+}
+
 // resolveGlobs expands glob patterns in browser configs' UserDataDir.
 // This supports MSIX/UWP browsers on Windows whose package directories
 // contain a dynamic publisher hash suffix (e.g., "TheBrowserCompany.Arc_*").
diff --git a/browser/browser_darwin.go b/browser/browser_darwin.go
index 185bd4b..0263a06 100644
--- a/browser/browser_darwin.go
+++ b/browser/browser_darwin.go
@@ -155,20 +155,8 @@ func resolveKeychainPassword(flagPassword string) string {
 	return password
 }
 
-// keychainPasswordSetter is an optional capability interface satisfied by
-// Safari, which reads InternetPassword records directly from the login keychain.
-type keychainPasswordSetter interface {
-	SetKeychainPassword(string)
-}
-
-// newPlatformInjector returns a closure that injects the Chromium master-key
-// retriever and the Safari Keychain password into each Browser.
-//
-// Resolution is lazy: the keychain password prompt and retriever construction
-// are deferred until the first Browser that actually needs them passes through
-// the closure. Browsers that satisfy neither setter interface (e.g. Firefox)
-// short-circuit without ever touching the keychain, so `-b firefox` on macOS
-// no longer triggers a password prompt.
+// newPlatformInjector lazily wires retrievers (and the macOS keychain password) into each Browser;
+// `-b firefox` never triggers a keychain prompt because lazy resolution skips browsers that need neither.
 func newPlatformInjector(opts PickOptions) func(Browser) {
 	var (
 		password   string
@@ -176,8 +164,8 @@ func newPlatformInjector(opts PickOptions) func(Browser) {
 		resolved   bool
 	)
 	return func(b Browser) {
-		rs, needsRetrievers := b.(keyRetrieversSetter)
-		kps, needsKeychainPassword := b.(keychainPasswordSetter)
+		km, needsRetrievers := b.(KeyManager)
+		kps, needsKeychainPassword := b.(KeychainPasswordReceiver)
 		if !needsRetrievers && !needsKeychainPassword {
 			return
 		}
@@ -187,7 +175,7 @@ func newPlatformInjector(opts PickOptions) func(Browser) {
 			resolved = true
 		}
 		if needsRetrievers {
-			rs.SetKeyRetrievers(retrievers)
+			km.SetKeyRetrievers(retrievers)
 		}
 		if needsKeychainPassword {
 			kps.SetKeychainPassword(password)
diff --git a/browser/browser_linux.go b/browser/browser_linux.go
index 2eb4398..afc6a47 100644
--- a/browser/browser_linux.go
+++ b/browser/browser_linux.go
@@ -75,8 +75,8 @@ func platformBrowsers() []types.BrowserConfig {
 func newPlatformInjector(_ PickOptions) func(Browser) {
 	retrievers := keyretriever.DefaultRetrievers()
 	return func(b Browser) {
-		if s, ok := b.(keyRetrieversSetter); ok {
-			s.SetKeyRetrievers(retrievers)
+		if km, ok := b.(KeyManager); ok {
+			km.SetKeyRetrievers(retrievers)
 		}
 	}
 }
diff --git a/browser/browser_windows.go b/browser/browser_windows.go
index c324735..44d7059 100644
--- a/browser/browser_windows.go
+++ b/browser/browser_windows.go
@@ -132,8 +132,8 @@ func platformBrowsers() []types.BrowserConfig {
 func newPlatformInjector(_ PickOptions) func(Browser) {
 	retrievers := keyretriever.DefaultRetrievers()
 	return func(b Browser) {
-		if s, ok := b.(keyRetrieversSetter); ok {
-			s.SetKeyRetrievers(retrievers)
+		if km, ok := b.(KeyManager); ok {
+			km.SetKeyRetrievers(retrievers)
 		}
 	}
 }