kokorobox-native 0.16.0 → 0.16.1

package/README.md

@@ -1,7 +1,7 @@
 # kokorobox-native
 
-Native Node.js APIs used by KokoroBox Desktop. This package is an ESM loader:
-it selects the native binary for the current operating system and architecture.
+Native Node.js APIs used by KokoroBox Desktop. This ESM package selects the
+native binary for the current operating system and architecture.
 
 ## Installation
 
@@ -9,8 +9,8 @@ it selects the native binary for the current operating system and architecture.
 pnpm add kokorobox-native
 ```
 
-Prebuilt optional packages are available for x64 and arm64 Windows (MSVC),
-macOS, and GNU/Linux. The loader also accepts a development binary through
+Prebuilt optional packages support x64 and arm64 Windows (MSVC), macOS, and
+GNU/Linux. For local development, the loader also accepts
 `NAPI_RS_NATIVE_LIBRARY_PATH`.
 
 ## Usage
@@ -19,146 +19,23 @@ macOS, and GNU/Linux. The loader also accepts a development binary through
 import {
   getNativeCapabilities,
   getNetworkContext,
-  getTrafficPresenterPath,
   inspectApplication,
 } from "kokorobox-native";
 
 const capabilities = getNativeCapabilities();
 const network = await getNetworkContext();
 const app = await inspectApplication("/Applications/KokoroBox.app");
-const presenter = getTrafficPresenterPath();
 ```
 
-The full TypeScript declarations are shipped in
-[`index.d.ts`](index.d.ts).
+Check `getNativeCapabilities()` before using optional platform features.
 
-## API overview
+## Documentation
 
-| Area | Exports |
-| --- | --- |
-| Capabilities | `getNativeCapabilities` |
-| Traffic presenter | `getTrafficPresenterPath` |
-| Icons | `fileToDataUrl`, `getAppName` |
-| Applications | `inspectApplication`, `scanWindowsApplications`, `findExecutables` |
-| Rules | `fileToStr` |
-| Platform | `getLaunchAtLogin`, `setLaunchAtLogin`, `getNetworkContext`, `waitForNetworkContextChange` |
-| Service identity | `openServiceIdentity`, `deleteServiceIdentity`, `ServiceIdentity` |
-| Linux terminal proxy | `setTerminalProxyEnvironment`, `clearTerminalProxyEnvironment` |
-| macOS service | `getMacosManagedServiceStatus`, `registerMacosManagedService`, `unregisterMacosManagedService`, `reloadMacosManagedService`, `openMacosLoginItemsSettings` |
-| macOS application routing | `applyMacosApplicationRouting`, `getMacosApplicationRoutingStatus`, `stopMacosApplicationRouting`, `openMacosApplicationRoutingSettings` |
-| Core permissions | `getCorePrivilegeStatus`, `setCorePrivileges` |
-| Privileged operations | `runServiceLifecycleElevated`, `cleanupLegacyMacosService`, `stopMacosManagedService`, `repairManagedFilePermissions` |
-| Windows | `getCurrentUserSid`, `isRunningAsAdmin`, `relaunchCurrentApplicationWithPrivilege`, `ensureKokoroBoxCoreFirewall`, `listUwpLoopbackApps`, `setUwpLoopbackExemption` |
+- [JavaScript API guide](../docs/api.md)
+- [TypeScript declarations](index.d.ts)
+- [Platform behavior and security contract](../docs/platform-services.md)
+- [Traffic presenter protocol](../docs/traffic-presenter.md)
+- [Repository layout and build commands](../README.md)
 
-`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
-signing identifier on macOS. `scanWindowsApplications` is asynchronous and
-Windows-only; it accepts an optional result limit and executable-name exclusion
-list.
-
-`findExecutables` asynchronously searches absolute additional directories,
-`PATH`, and platform-standard binary locations without spawning command-line
-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
-the formats listed in the TypeScript declaration.
-
-Launch-at-login requires a stable filesystem-safe `identifier`, a display name,
-and an absolute executable path. It returns the selected backend: the Windows
-current-user Run key, macOS `SMAppService.mainApp`, or Linux XDG Autostart. On
-macOS, `requiresApproval` reports when the entry is registered but still needs
-approval in System Settings. Network context is best-effort, so optional fields
-such as the default interface and SSID may be absent. macOS obtains this state
-directly from SystemConfiguration without parsing command output.
-Windows obtains the preferred interface and DNS servers from IP Helper and the
-SSID from Native Wi-Fi, without spawning PowerShell.
-
-`waitForNetworkContextChange(previous, timeoutMs)` resolves with a changed
-snapshot or `null` when the timeout expires. `openServiceIdentity()` opens an
-opaque Ed25519 signer backed by the platform credential store; its private key
-is not returned to JavaScript. Linux can use an explicitly reported protected
-file fallback when Secret Service is unavailable.
-
-On Linux, the terminal proxy functions manage only KokoroBox's user-session
-configuration. The set call returns whether the systemd user manager was
-updated; clearing returns `null` when no managed file exists. See the
-[platform-services contract](../docs/platform-services.md) for the exact path
-and return semantics.
-
-The macOS managed-service functions accept the basename of an embedded
-LaunchDaemon plist and use `SMAppService` directly. They return an explicit
-`requires-approval` state when an administrator must approve the daemon in
-System Settings.
-
-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
-use them as a general privileged-command interface. See the repository's
-[platform-services contract](../docs/platform-services.md) for validation and
-platform behavior.
-
-`getTrafficPresenterPath()` returns the presenter executable shipped in the
-same platform package as the loaded native binding. The presenter accepts the
-versioned JSON-lines protocol documented by the `traffic-presenter` crate on
-standard input and terminates when its parent closes that stream.
-
-## Platform behavior
-
-Use `getNativeCapabilities()` before enabling an optional system feature.
-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 |
-| `linuxTerminalProxy` | Linux |
-
-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
-repair are separate purpose-specific APIs.
-
-`relaunchCurrentApplicationWithPrivilege(args, elevated)` starts a new copy of
-the current Windows application without accepting an executable path. An
-elevated relaunch presents the standard UAC prompt; the unelevated path uses
-the interactive desktop shell token. It does not configure persistent
-elevation.
-
-`listUwpLoopbackApps()` reports Windows app containers with an opaque ID,
-display metadata, category (`user`, `microsoft`, or `system`), package type,
-and exemption status. Pass that ID to `setUwpLoopbackExemption()` to change the
-app's loopback exemption.
-
-## Contributing
-
-The source is a three-crate Rust workspace. The root crate implements native
-behavior, `napi/` maps it into this package’s JavaScript API, and
-`traffic-presenter/` builds the sidecar. See the root
-[README](../README.md#repository-structure) for the complete layout and build
-commands.
-
-This project is derived from
-[`UruhaLushia/sparkle-native`](https://github.com/UruhaLushia/sparkle-native)
-and is licensed under GPL-3.0-only.
+Derived from [UruhaLushia/sparkle-native](https://github.com/UruhaLushia/sparkle-native)
+and licensed under GPL-3.0-only.

package/package.json

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