kokorobox-native 0.16.2 → 0.16.3

package/README.md

@@ -43,6 +43,24 @@ The traffic presenter emits JSON Lines to stderr. The Windows portable updater
 also saves its last run in `%TEMP%/kokorobox-portable-updater.log` because Desktop
 exits before extraction. These sidecars include Unix milliseconds in `timestamp`.
 
+## System Proxy diagnostics
+
+`getSystemProxyDiagnostics()` returns actual OS configuration with independent
+availability information. Windows, macOS and Linux share the same entry point;
+platform-specific details are nested under `windows`, `macos` or `linux`.
+macOS uses SystemConfiguration for effective HTTP/HTTPS/SOCKS, PAC/discovery,
+primary IPv4/IPv6 services and the current Network Location. Reading never asks
+for administrator authorization. Runtime health and connectivity belong to
+KokoroBox Service, not this API.
+
+`setSystemProxy(settings)` supports explicit Windows/macOS manual, PAC and
+disabled actions. macOS honors `onlyActiveDevice`, preserves PAC/discovery
+when restoring manual proxies, and reuses Native's administrator dialog if
+required for a write. Its structured result includes
+`automaticSettingsPreserved`; callers must not resume a legacy watchdog or
+cleanup that would erase those settings. Never invoke this setter merely to
+inspect or refresh diagnostics.
+
 ## Documentation
 
 - [JavaScript API guide](../docs/api.md)

package/diagnostics.js

@@ -16,6 +16,7 @@ const lifecycleOperations = new Set([
   "stopMacosApplicationRouting",
   "setLaunchAtLogin",
   "setUwpLoopbackExemption",
+  "setSystemProxy",
 ]);
 
 function boundedMessage(value) {
@@ -91,6 +92,24 @@ export function createNativeDiagnostics() {
         throw error;
       };
       const completed = (value) => {
+        if (target === "getSystemProxyDiagnostics") {
+          record(value.status === "available" ? "info" : "warn", "SystemProxy", `[SystemProxy] Configuration: ${value.status}; Proxy enabled: ${value.enabled ?? "unknown"}`);
+          if (value.macos) {
+            const effective = value.macos.effective;
+            const count = value.macos.activeServiceIds?.length ?? 0;
+            record("info", "SystemProxy", `[SystemProxy/macOS] Active network services: ${count}; HTTP: ${effective?.http?.enabled ?? "unknown"}; HTTPS: ${effective?.https?.enabled ?? "unknown"}; PAC: ${effective?.pacEnabled ?? "unknown"}; Auto discovery: ${effective?.autoDiscovery ?? "unknown"}`);
+          }
+          if (value.linux) {
+            const backend = ["gnome", "kde", "environment", "unsupported"].includes(value.linux.backend) ? value.linux.backend : "unknown";
+            const portal = value.linux.portal?.status === "available" ? "available" : "unavailable";
+            record("info", "SystemProxy", `[SystemProxy] Linux backend: ${backend}; Portal: ${portal}`);
+          }
+          if (value.pac?.enabled) record("info", "SystemProxy", "[SystemProxy] PAC configuration detected");
+          for (const [name, state] of Object.entries({winHttp: value.windows?.winHttp, appContainer: value.windows?.appContainer})) {
+            if (state?.status === "unavailable") record("warn", "SystemProxy", `[SystemProxy] ${name}: unavailable`);
+          }
+          return value;
+        }
         if (value && value.state === "error")
           record(
             "error",

package/index.d.ts

@@ -325,3 +325,94 @@ export function ensureKokoroBoxCoreFirewall(
 ): void;
 export function listUwpLoopbackApps(): UwpLoopbackApp[];
 export function setUwpLoopbackExemption(id: string, enabled: boolean): void;
+
+export interface NativeProxyEndpoint {
+  host: string;
+  port: number;
+}
+export interface MacProxyProtocol {
+  enabled: boolean;
+  endpoint?: NativeProxyEndpoint | null;
+}
+export interface MacProxyState {
+  http: MacProxyProtocol;
+  https: MacProxyProtocol;
+  socks: MacProxyProtocol;
+  pacEnabled: boolean;
+  pacUrl?: string | null;
+  autoDiscovery: boolean;
+  bypass: string[];
+  excludeSimpleHostnames: boolean;
+}
+export interface MacNetworkService {
+  id: string;
+  name: string;
+  interface?: string | null;
+  enabled: boolean;
+  active: boolean;
+  primary: boolean;
+  status: "available" | "unavailable";
+  proxies?: MacProxyState | null;
+}
+export interface MacOSProxyDetails {
+  effective?: MacProxyState | null;
+  activeServiceIds: string[];
+  services: MacNetworkService[];
+  networkLocation?: string | null;
+  locationErrorCode?: string | null;
+  serviceErrorCode?: string | null;
+}
+export interface NativeSystemProxyMutation {
+  automaticSettingsPreserved: boolean;
+}
+export interface NativeSystemProxyDiagnostics {
+  platform: "windows" | "darwin" | "linux";
+  status: "available" | "unavailable" | "unsupported";
+  errorCode?: string | null;
+  enabled?: boolean | null;
+  proxies: {
+    http?: NativeProxyEndpoint | null;
+    https?: NativeProxyEndpoint | null;
+    socks?: NativeProxyEndpoint | null;
+  };
+  pac?: { enabled: boolean; url?: string | null } | null;
+  bypass: string[];
+  macos?: MacOSProxyDetails | null;
+  linux?: {
+    desktopEnvironment: string;
+    backend: "gnome" | "kde" | "environment" | "unsupported";
+    mode?: "none" | "manual" | "auto" | "wpad" | "environment" | null;
+    reversedBypass: boolean;
+    environment: { name: string; endpoint?: NativeProxyEndpoint | null; bypass: string[]; valid: boolean }[];
+    portal: { status: "available" | "unavailable"; direct: boolean; proxies: NativeProxyEndpoint[]; errorCode?: string | null };
+  } | null;
+  windows?: {
+    proxyServer?: string | null;
+    proxyOverride?: string | null;
+    autoConfigUrl?: string | null;
+    winHttp: {
+      status: "available" | "unavailable";
+      mode?: "direct" | "proxy" | "advanced" | null;
+      proxy?: string | null;
+      bypass?: string | null;
+      errorCode?: string | null;
+    };
+    appContainer: {
+      supported: boolean;
+      status: "available" | "unavailable";
+      loopbackExemptionCount?: number | null;
+      errorCode?: string | null;
+    };
+  } | null;
+}
+export interface NativeSystemProxySettings {
+  mode: "manual" | "auto" | "disabled";
+  host?: string;
+  port?: number;
+  bypass: string[];
+  pacUrl?: string;
+  onlyActiveDevice?: boolean;
+}
+export declare function getSystemProxyDiagnostics(): Promise<NativeSystemProxyDiagnostics>;
+/** Explicit user action only. Leaves WinHTTP/UWP unchanged; macOS manual restore preserves PAC/discovery. */
+export declare function setSystemProxy(settings: NativeSystemProxySettings): Promise<NativeSystemProxyMutation>;

package/index.js

@@ -199,3 +199,6 @@ export const setUwpLoopbackExemption =
 export const ServiceIdentity = diagnosticBinding.ServiceIdentity;
 export const openServiceIdentity = diagnosticBinding.openServiceIdentity;
 export const deleteServiceIdentity = diagnosticBinding.deleteServiceIdentity;
+
+export const getSystemProxyDiagnostics = diagnosticBinding.getSystemProxyDiagnostics;
+export const setSystemProxy = diagnosticBinding.setSystemProxy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokorobox-native",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "description": "KokoroBox native bridge",
   "type": "module",
   "main": "index.js",
@@ -50,11 +50,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "kokorobox-native-win32-x64-msvc": "0.16.2",
-    "kokorobox-native-win32-arm64-msvc": "0.16.2",
-    "kokorobox-native-darwin-x64": "0.16.2",
-    "kokorobox-native-darwin-arm64": "0.16.2",
-    "kokorobox-native-linux-x64-gnu": "0.16.2",
-    "kokorobox-native-linux-arm64-gnu": "0.16.2"
+    "kokorobox-native-win32-x64-msvc": "0.16.3",
+    "kokorobox-native-win32-arm64-msvc": "0.16.3",
+    "kokorobox-native-darwin-x64": "0.16.3",
+    "kokorobox-native-darwin-arm64": "0.16.3",
+    "kokorobox-native-linux-x64-gnu": "0.16.3",
+    "kokorobox-native-linux-arm64-gnu": "0.16.3"
   }
 }