kokorobox-native 0.11.0 → 0.12.0

package/README.md

@@ -43,7 +43,7 @@ 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` |
@@ -79,10 +79,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 +103,20 @@ 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 |
+| --- | --- |
+| `networkDnsMutation` | macOS |
+| `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

@@ -3,6 +3,13 @@ export interface FirewallRule {
   applicationPath: string;
 }
 
+export interface UwpLoopbackApp {
+  sid: string;
+  packageName: string;
+  displayName: string;
+  enabled: boolean;
+}
+
 export interface NativeCapabilities {
   applicationInspection: boolean;
   executableDiscovery: boolean;
@@ -13,8 +20,13 @@ export interface NativeCapabilities {
   launchAtLogin: boolean;
   networkContext: boolean;
   networkMonitor: boolean;
+  networkDnsMutation: boolean;
+  serviceLifecycle: boolean;
+  managedFilePermissions: boolean;
   macosServiceManagement: boolean;
   macosApplicationRouting: boolean;
+  windowsPrivilegeRelaunch: boolean;
+  windowsUwpLoopback: boolean;
   coreFilePrivileges: boolean;
   serviceIdentity: boolean;
 }
@@ -185,6 +197,8 @@ 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,
@@ -196,8 +210,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"
@@ -246,3 +293,5 @@ export function scanWindowsApplications(
 export function getCurrentUserSid(): string;
 export function isRunningAsAdmin(): boolean;
 export function setupFirewallRules(rules: FirewallRule[]): void;
+export function listUwpLoopbackApps(): UwpLoopbackApp[];
+export function setUwpLoopbackExemption(sid: string, enabled: boolean): void;

package/index.js

@@ -104,13 +104,17 @@ 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,6 +127,8 @@ export const scanWindowsApplications = nativeBinding.scanWindowsApplications;
 export const getCurrentUserSid = nativeBinding.getCurrentUserSid;
 export const isRunningAsAdmin = nativeBinding.isRunningAsAdmin;
 export const setupFirewallRules = nativeBinding.setupFirewallRules;
+export const listUwpLoopbackApps = nativeBinding.listUwpLoopbackApps;
+export const setUwpLoopbackExemption = nativeBinding.setUwpLoopbackExemption;
 export const ServiceIdentity = nativeBinding.ServiceIdentity;
 export const openServiceIdentity = nativeBinding.openServiceIdentity;
 export const deleteServiceIdentity = nativeBinding.deleteServiceIdentity;

package/package.json

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