KGAProxy

A clean Manifest V3 browser extension for importing, switching, checking, filtering, and monitoring proxy connections.

---

What Is KGAProxy?

KGAProxy is a lightweight proxy management extension for Chromium-based browsers. It is built for users who need a fast local tool for working with proxy lists without a heavy dashboard, external backend, account system, or build pipeline.

The extension lets you paste a proxy list, switch between entries, save imports, bypass selected websites with global filters, detect approximate proxy countries, run health checks, and watch the current connection state from a minimal colored toolbar indicator.

Highlights

Feature	Description
Proxy import	Paste plain text proxy lists in several common formats.
Manual switching	Click any proxy to make it the active browser proxy.
Saved imports	Keep previous proxy lists locally and load them later.
Global filters	Bypass the proxy for matching URLs such as ozon.ru/*.
Health checks	Verify the active proxy and rotate away from failed entries.
Geo-IP lookup	Detect approximate country and city information for proxy hosts.
Toolbar status	Show connection state as a simple gray, red, or green circle.
Local storage	Persist proxy state in chrome.storage.local.
No build step	Plain HTML, CSS, and JavaScript. Load it directly as unpacked.

Quick Start

1. Open a Chromium-based browser.
2. Navigate to chrome://extensions.
3. Enable Developer mode.
4. Click Load unpacked.
5. Select the KGAProxy project directory.
6. Pin the extension to the toolbar.
7. Open the popup and import your proxy list.

After changing source files, reload the extension from chrome://extensions.

Core Workflow

Import proxies -> Select active proxy -> Enable proxy mode -> Check status
              -> Add filters if needed -> Save import -> Reuse later

A typical session:

1. Paste proxies into Import proxies.
2. Click Import.
3. Select a proxy from Proxy list.
4. Turn on the top-right proxy toggle.
5. Use Check now to validate the active proxy.
6. Use Countries to detect approximate proxy locations.
7. Use Save current to keep the current proxy set.

Supported Proxy Formats

KGAProxy accepts common proxy line formats. Blank lines and lines beginning with # are ignored.

http://user:pass@host:port
https://user:pass@host:port
socks5://user:pass@host:port
host:port
user:pass@host:port
host:port:user:pass

Examples:

http://alice:secret@203.0.113.10:8080
socks5://user:pass@198.51.100.42:1080
192.0.2.15:3128

Proxy Switching

The proxy list is interactive. Click a proxy entry to make it active.

When a proxy is selected:

• The active entry is highlighted.
• Proxy mode is enabled.
• Browser proxy settings are updated through the Chrome proxy API.
• Proxy authentication is supplied automatically when credentials are available.

Toolbar Status Indicator

The browser toolbar icon is intentionally minimal. It is a colored circle that reflects the current proxy state.

Color	Meaning
Gray	Proxy mode is disabled or no proxy is selected.
Red	Proxy mode is enabled, but the active proxy is not confirmed working.
Green	Proxy mode is enabled and the active proxy is confirmed alive.

Global Filters

Global filters define URL patterns that should bypass the proxy. Matching requests are sent directly instead of through the selected proxy.

Examples:

ozon.ru/*
ozon.*
*.example.com/*

Filters are applied through a generated PAC script. This allows KGAProxy to evaluate both the full request URL and the request host.

Saved Imports

The extension stores recent import sets locally. This makes it easy to switch between different proxy collections without pasting the same list repeatedly.

Available actions:

Action	Purpose
Import	Parse a pasted proxy list and load it into the current session.
Save current	Save the currently loaded proxy list.
Load	Restore a previously saved import.
Remove	Delete a saved import from local storage.

Identical imports are deduplicated.

Country Detection

The Countries button performs approximate geo-IP lookup for proxies in the current list.

Displayed metadata may include:

• Country code
• Country name
• City

Geo-IP data is approximate. It can be wrong for datacenter IPs, recently reassigned ranges, VPN infrastructure, CDN-like routing, or proxy providers that route traffic differently than the host location suggests.

Health Checks And Rotation

KGAProxy can test the active proxy against a public IP endpoint. If the active proxy fails, it is marked as dead and the extension attempts to rotate to another proxy.

Proxy states:

State	Meaning
unknown	The proxy has not been checked yet.
alive	The latest health check succeeded.
dead	The latest health check failed.

Data Storage

All extension state is stored locally through chrome.storage.local.

Stored data may include:

• Current proxy list
• Saved import lists
• Active proxy index
• Enable or disable state
• Global filter patterns
• Proxy health state
• Approximate geo-IP metadata

KGAProxy does not require a custom backend server.

Permissions

KGAProxy uses browser permissions required for proxy management and authentication.

Permission	Why it is needed
proxy	Apply and clear browser proxy settings.
storage	Persist extension configuration locally.
alarms	Run periodic health checks.
webRequest	Observe proxy authentication requests.
webRequestAuthProvider	Provide proxy credentials when required.
<all_urls>	Support proxy auth and PAC-based routing across browser traffic.

Network Requests

The extension may make external requests for:

• Proxy health checks.
• Approximate geo-IP detection.

These requests are used only for operational proxy management.

Project Structure

KGAProxy/
├── background.js   # Service worker: proxy state, PAC config, auth, checks, geo lookup
├── popup.html      # Popup markup
├── popup.css       # Popup visual design
├── popup.js        # Popup interactions and rendering
├── manifest.json   # Chrome extension manifest
├── logo.svg        # Popup logo asset
└── LICENSE         # Custom restrictive license

Development

KGAProxy intentionally avoids bundlers and build tools. The source is direct browser-extension code.

Development loop:

1. Edit source files.
2. Open chrome://extensions.
3. Click Reload on the extension card.
4. Reopen the popup.
5. Test proxy import, switching, filters, countries, and health checks.

Useful syntax checks:

node --check background.js
node --check popup.js

Limitations

• Browser proxy settings apply to the regular browser profile globally.
• Manifest V3 service workers can restart, so state must be persisted.
• Geo-IP results are approximate and may be inaccurate.
• Health checks depend on external network availability.
• Some proxy providers route traffic differently from the proxy host location.
• Proxy reliability depends on the provider and network conditions.

Security Notes

Proxy credentials are stored in local browser extension storage. Treat the browser profile as sensitive if you import authenticated proxies.

Do not import proxy lists from untrusted sources unless you understand the risk.

License

KGAProxy is distributed under a custom restrictive license.

Commercial use, redistribution, resale, republishing, rebranding, sublicensing, uploading to extension stores, uploading to application stores, or publishing modified versions without the author's explicit written permission is prohibited.

See LICENSE for the full license terms.