kokorobox-native 0.11.1 → 0.13.0

package/README.md

@@ -43,10 +43,10 @@ The full TypeScript declarations are shipped in
 | Rules | `fileToStr` |
 | Platform | `getLaunchAtLogin`, `setLaunchAtLogin`, `getNetworkContext` |
 | macOS service | `getMacosManagedServiceStatus`, `registerMacosManagedService`, `unregisterMacosManagedService`, `reloadMacosManagedService`, `openMacosLoginItemsSettings` |
-| macOS application routing | `invokeMacosApplicationRouting` |
+| macOS application routing | `applyMacosApplicationRouting`, `getMacosApplicationRoutingStatus`, `stopMacosApplicationRouting`, `openMacosApplicationRoutingSettings` |
 | Core permissions | `getCorePrivilegeStatus`, `setCorePrivileges` |
 | Privileged operations | `runServiceLifecycleElevated`, `cleanupLegacyMacosService`, `stopMacosManagedService`, `repairManagedFilePermissions` |
-| Windows | `getCurrentUserSid`, `isRunningAsAdmin`, `relaunchCurrentApplicationWithPrivilege`, `setupFirewallRules` |
+| Windows | `getCurrentUserSid`, `isRunningAsAdmin`, `relaunchCurrentApplicationWithPrivilege`, `ensureKokoroBoxCoreFirewall` |
 
 `inspectApplication` validates the input for the current platform and resolves
 it to a routing identifier: an executable path on Windows and Linux, or a code
@@ -59,6 +59,10 @@ list.
 tools. It returns canonical paths for stable deduplication; prefix matching is
 available only when explicitly requested.
 
+`ensureKokoroBoxCoreFirewall` accepts the two Mihomo executable paths and the
+KokoroBox application path. Native fixes the three rule names and validates
+the executable basenames before changing Windows Firewall state.
+
 `fileToStr` converts a rule file and returns each generated output keyed by its
 behavior, metadata for those outputs, and rules that were skipped. Its optional
 `RuleConvertOptions` accepts Mihomo, General, Egern, and sing-box targets and
@@ -79,10 +83,11 @@ LaunchDaemon plist and use `SMAppService` directly. They return an explicit
 `requires-approval` state when an administrator must approve the daemon in
 System Settings.
 
-`invokeMacosApplicationRouting(request)` runs the bounded, versioned macOS
-application-routing control-plane protocol off the Node.js main thread. It
-controls the bundled System Extension and Network Extension; packet forwarding
-continues to run in the separate extension process.
+The macOS application-routing functions run the bounded control plane off the
+Node.js main thread. Their typed configuration omits fixed protocol details
+such as version, fail-closed behavior, loopback hosts, and reserved ports; the
+native layer owns and validates that wire envelope. Packet forwarding continues
+to run in the separate System Extension process.
 
 Core-file privilege APIs are supported on macOS and Linux. They accept only
 canonical, existing executables named `mihomo` or `mihomo-alpha`; callers cannot
@@ -102,6 +107,19 @@ Windows account, elevation, Firewall, and application-scan APIs report an
 `UNSUPPORTED_PLATFORM:` error on other operating systems instead of behaving as
 no-ops.
 
+The capability contract includes dedicated flags for APIs that have narrower
+support than the package itself:
+
+| Capability | Supported platforms |
+| --- | --- |
+| `serviceLifecycle` | Windows, macOS, Linux |
+| `managedFilePermissions` | macOS, Linux |
+| `windowsPrivilegeRelaunch` | Windows |
+| `windowsUwpLoopback` | Windows |
+
+Use these flags instead of inferring availability from `process.platform` or
+from a related but broader capability.
+
 `runServiceLifecycleElevated(options)` accepts only the KokoroBox Service
 `init`, `install`, `uninstall`, `start`, `stop`, and `restart` actions. macOS
 legacy-service cleanup, managed-service stopping, and managed-file permission

package/index.d.ts

@@ -1,8 +1,3 @@
-export interface FirewallRule {
-  name: string;
-  applicationPath: string;
-}
-
 export interface UwpLoopbackApp {
   sid: string;
   packageName: string;
@@ -20,8 +15,12 @@ export interface NativeCapabilities {
   launchAtLogin: boolean;
   networkContext: boolean;
   networkMonitor: boolean;
+  serviceLifecycle: boolean;
+  managedFilePermissions: boolean;
   macosServiceManagement: boolean;
   macosApplicationRouting: boolean;
+  windowsPrivilegeRelaunch: boolean;
+  windowsUwpLoopback: boolean;
   coreFilePrivileges: boolean;
   serviceIdentity: boolean;
 }
@@ -192,8 +191,6 @@ export function setLaunchAtLogin(
   enabled: boolean,
 ): Promise<LaunchAtLoginStatus>;
 export function getNetworkContext(): Promise<NetworkContext>;
-/** Set DNS on the active macOS network service; [] restores automatic DNS. */
-export function setActiveNetworkDns(servers: string[]): Promise<void>;
 /** Resolve when the native network snapshot changes, or `undefined` on timeout. */
 export function waitForNetworkContextChange(
   previous: NetworkContext,
@@ -205,8 +202,41 @@ export function registerMacosManagedService(plistName: string): MacOSManagedServ
 export function unregisterMacosManagedService(plistName: string): MacOSManagedServiceStatus;
 export function reloadMacosManagedService(plistName: string): MacOSManagedServiceStatus;
 export function openMacosLoginItemsSettings(): void;
-/** Invoke the versioned macOS Network/System Extension control-plane protocol. */
-export function invokeMacosApplicationRouting(request: string): Promise<string>;
+export type MacosApplicationRoutingIdentifierKind = "SIGNING_IDENTIFIER" | "PROCESS_NAME";
+export type MacosApplicationRoutingProtocol = "TCP" | "UDP" | "BOTH";
+export type MacosApplicationRoutingAction = "PROXY" | "DIRECT" | "BLOCK";
+export type MacosApplicationRoutingState =
+  | "disabled"
+  | "starting"
+  | "running"
+  | "stopping"
+  | "error";
+export interface MacosApplicationRoutingRule {
+  signingIdentifier: string;
+  identifierKind: MacosApplicationRoutingIdentifierKind;
+  ruleProtocol: MacosApplicationRoutingProtocol;
+  action: MacosApplicationRoutingAction;
+  enabled: boolean;
+  priority: number;
+}
+export interface MacosApplicationRoutingConfiguration {
+  proxyAvailable: boolean;
+  proxyUdpDns: boolean;
+  diagnosticLogging: boolean;
+  rules: MacosApplicationRoutingRule[];
+}
+export interface MacosApplicationRoutingStatus {
+  state: MacosApplicationRoutingState;
+  needsUserApproval: boolean;
+  message?: string;
+}
+/** Apply a bounded policy through the macOS Network/System Extension control plane. */
+export function applyMacosApplicationRouting(
+  configuration: MacosApplicationRoutingConfiguration,
+): Promise<MacosApplicationRoutingStatus>;
+export function getMacosApplicationRoutingStatus(): Promise<MacosApplicationRoutingStatus>;
+export function stopMacosApplicationRouting(): Promise<MacosApplicationRoutingStatus>;
+export function openMacosApplicationRoutingSettings(): Promise<MacosApplicationRoutingStatus>;
 export type ServiceLifecycleAction =
   | "init"
   | "install"
@@ -254,6 +284,10 @@ export function scanWindowsApplications(
 ): Promise<ApplicationScanResult>;
 export function getCurrentUserSid(): string;
 export function isRunningAsAdmin(): boolean;
-export function setupFirewallRules(rules: FirewallRule[]): void;
+export function ensureKokoroBoxCoreFirewall(
+  mihomoPath: string,
+  mihomoAlphaPath: string,
+  applicationPath: string,
+): void;
 export function listUwpLoopbackApps(): UwpLoopbackApp[];
 export function setUwpLoopbackExemption(sid: string, enabled: boolean): void;

package/index.js

@@ -104,14 +104,16 @@ export const findExecutables = nativeBinding.findExecutables;
 export const getLaunchAtLogin = nativeBinding.getLaunchAtLogin;
 export const setLaunchAtLogin = nativeBinding.setLaunchAtLogin;
 export const getNetworkContext = nativeBinding.getNetworkContext;
-export const setActiveNetworkDns = nativeBinding.setActiveNetworkDns;
 export const waitForNetworkContextChange = nativeBinding.waitForNetworkContextChange;
 export const getMacosManagedServiceStatus = nativeBinding.getMacosManagedServiceStatus;
 export const registerMacosManagedService = nativeBinding.registerMacosManagedService;
 export const unregisterMacosManagedService = nativeBinding.unregisterMacosManagedService;
 export const reloadMacosManagedService = nativeBinding.reloadMacosManagedService;
 export const openMacosLoginItemsSettings = nativeBinding.openMacosLoginItemsSettings;
-export const invokeMacosApplicationRouting = nativeBinding.invokeMacosApplicationRouting;
+export const applyMacosApplicationRouting = nativeBinding.applyMacosApplicationRouting;
+export const getMacosApplicationRoutingStatus = nativeBinding.getMacosApplicationRoutingStatus;
+export const stopMacosApplicationRouting = nativeBinding.stopMacosApplicationRouting;
+export const openMacosApplicationRoutingSettings = nativeBinding.openMacosApplicationRoutingSettings;
 export const runServiceLifecycleElevated = nativeBinding.runServiceLifecycleElevated;
 export const cleanupLegacyMacosService = nativeBinding.cleanupLegacyMacosService;
 export const stopMacosManagedService = nativeBinding.stopMacosManagedService;
@@ -123,7 +125,7 @@ export const inspectApplication = nativeBinding.inspectApplication;
 export const scanWindowsApplications = nativeBinding.scanWindowsApplications;
 export const getCurrentUserSid = nativeBinding.getCurrentUserSid;
 export const isRunningAsAdmin = nativeBinding.isRunningAsAdmin;
-export const setupFirewallRules = nativeBinding.setupFirewallRules;
+export const ensureKokoroBoxCoreFirewall = nativeBinding.ensureKokoroBoxCoreFirewall;
 export const listUwpLoopbackApps = nativeBinding.listUwpLoopbackApps;
 export const setUwpLoopbackExemption = nativeBinding.setUwpLoopbackExemption;
 export const ServiceIdentity = nativeBinding.ServiceIdentity;

package/package.json

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