kokorobox-native 0.3.0 → 0.5.0

package/README.md

@@ -1,15 +1,84 @@
 # kokorobox-native
 
-Native Node.js APIs used by KokoroBox Desktop.
+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.
 
-The package exposes file/icon helpers, asynchronous application inspection, Windows executable
-directory scanning, rule conversion, Windows elevation and SID queries, and Windows Firewall rule
-management. Platform-specific N-API binaries are selected at runtime.
+## Installation
 
-Use `getNativeCapabilities()` before offering optional platform features. Windows-only calls fail
-with an `UNSUPPORTED_PLATFORM:` error outside Windows rather than reporting a no-op success.
+```sh
+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
+`NAPI_RS_NATIVE_LIBRARY_PATH`.
+
+## Usage
+
+```ts
+import {
+  getNativeCapabilities,
+  getNetworkContext,
+  inspectApplication,
+} from "kokorobox-native";
+
+const capabilities = getNativeCapabilities();
+const network = await getNetworkContext();
+const app = await inspectApplication("/Applications/KokoroBox.app");
+```
+
+The full TypeScript declarations are shipped in
+[`index.d.ts`](index.d.ts).
+
+## API overview
+
+| Area | Exports |
+| --- | --- |
+| Capabilities | `getNativeCapabilities` |
+| Icons | `fileToDataUrl`, `getAppName` |
+| Applications | `inspectApplication`, `scanWindowsApplications` |
+| Rules | `fileToStr` |
+| Platform | `getLaunchAtLogin`, `setLaunchAtLogin`, `getNetworkContext` |
+| Core permissions | `getCorePrivilegeStatus`, `setCorePrivileges` |
+| Windows | `getCurrentUserSid`, `isRunningAsAdmin`, `runElevated`, `setupFirewallRules` |
+
+`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.
+
+`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: Windows Task
+Scheduler, macOS Login Items, or Linux XDG Autostart. Network context is
+best-effort, so optional fields such as the default interface and SSID may be
+absent.
+
+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.
+
+## 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.
+
+## Contributing
+
+The source is a two-crate Rust workspace. The root crate implements native
+behavior; `napi/` maps it into this package’s JavaScript API. 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 remains licensed
-under GPL-3.0-only. KokoroBox maintains its own package and release lifecycle so the bridge can
-evolve with product-specific APIs.
+[`UruhaLushia/sparkle-native`](https://github.com/UruhaLushia/sparkle-native)
+and is licensed under GPL-3.0-only.

package/index.d.ts

@@ -9,6 +9,38 @@ export interface NativeCapabilities {
   windowsAccount: boolean;
   windowsElevation: boolean;
   windowsFirewall: boolean;
+  launchAtLogin: boolean;
+  networkContext: boolean;
+  coreFilePrivileges: boolean;
+}
+
+export interface LaunchAtLoginOptions {
+  /** Stable, filesystem-safe identifier, such as `com.amamiyakokoro.kokorobox`. */
+  identifier: string;
+  displayName: string;
+  executablePath: string;
+  arguments?: string[];
+}
+
+export interface LaunchAtLoginStatus {
+  enabled: boolean;
+  backend: "windows-task-scheduler" | "macos-login-item" | "linux-xdg-autostart";
+}
+
+/** Best-effort active-network state. Unavailable fields are omitted instead of guessed. */
+export interface NetworkContext {
+  defaultInterface?: string;
+  /** Active network-service name. Currently populated on macOS and Linux. */
+  defaultService?: string;
+  dnsServers: string[];
+  ssid?: string;
+}
+
+export interface CorePrivilegeStatus {
+  /** Canonical path validated by the native library. */
+  path: string;
+  /** Whether the set-user-ID bit is present. */
+  granted: boolean;
 }
 
 export interface ApplicationInfo {
@@ -75,6 +107,19 @@ export function fileToStr(
 ): RuleStringResult;
 export function getAppName(path: string): string;
 export function getNativeCapabilities(): NativeCapabilities;
+export function getLaunchAtLogin(options: LaunchAtLoginOptions): Promise<LaunchAtLoginStatus>;
+export function setLaunchAtLogin(
+  options: LaunchAtLoginOptions,
+  enabled: boolean,
+): Promise<LaunchAtLoginStatus>;
+export function getNetworkContext(): Promise<NetworkContext>;
+/** Inspect only validated `mihomo` and `mihomo-alpha` executable paths. */
+export function getCorePrivilegeStatus(paths: string[]): CorePrivilegeStatus[];
+/** Grant or revoke the constrained Unix core-file privilege. */
+export function setCorePrivileges(
+  paths: string[],
+  enabled: boolean,
+): Promise<CorePrivilegeStatus[]>;
 export function inspectApplication(path: string): Promise<ApplicationInfo>;
 export function scanWindowsApplications(
   directory: string,

package/index.js

@@ -52,14 +52,12 @@ function requireNative() {
   if (process.platform === "win32") {
     if (process.arch === "x64") return requireBinding("win32-x64-msvc");
     if (process.arch === "arm64") return requireBinding("win32-arm64-msvc");
-    if (process.arch === "ia32") return requireBinding("win32-ia32-msvc");
   } else if (process.platform === "darwin") {
     if (process.arch === "x64") return requireBinding("darwin-x64");
     if (process.arch === "arm64") return requireBinding("darwin-arm64");
   } else if (process.platform === "linux") {
     if (process.arch === "x64") return requireBinding("linux-x64-gnu");
     if (process.arch === "arm64") return requireBinding("linux-arm64-gnu");
-    if (process.arch === "loong64") return requireBinding("linux-loong64-gnu");
   }
 
   loadErrors.push(
@@ -83,6 +81,11 @@ export const fileToDataUrl = nativeBinding.fileToDataUrl;
 export const fileToStr = nativeBinding.fileToStr;
 export const getAppName = nativeBinding.getAppName;
 export const getNativeCapabilities = nativeBinding.getNativeCapabilities;
+export const getLaunchAtLogin = nativeBinding.getLaunchAtLogin;
+export const setLaunchAtLogin = nativeBinding.setLaunchAtLogin;
+export const getNetworkContext = nativeBinding.getNetworkContext;
+export const getCorePrivilegeStatus = nativeBinding.getCorePrivilegeStatus;
+export const setCorePrivileges = nativeBinding.setCorePrivileges;
 export const inspectApplication = nativeBinding.inspectApplication;
 export const scanWindowsApplications = nativeBinding.scanWindowsApplications;
 export const getCurrentUserSid = nativeBinding.getCurrentUserSid;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokorobox-native",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "KokoroBox native bridge",
   "type": "module",
   "main": "index.js",
@@ -24,13 +24,11 @@
     "binaryName": "kokorobox-native",
     "targets": [
       "x86_64-pc-windows-msvc",
-      "i686-pc-windows-msvc",
       "aarch64-pc-windows-msvc",
       "x86_64-apple-darwin",
       "aarch64-apple-darwin",
       "x86_64-unknown-linux-gnu",
-      "aarch64-unknown-linux-gnu",
-      "loongarch64-unknown-linux-gnu"
+      "aarch64-unknown-linux-gnu"
     ]
   },
   "scripts": {
@@ -49,13 +47,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "kokorobox-native-win32-x64-msvc": "0.3.0",
-    "kokorobox-native-win32-ia32-msvc": "0.3.0",
-    "kokorobox-native-win32-arm64-msvc": "0.3.0",
-    "kokorobox-native-darwin-x64": "0.3.0",
-    "kokorobox-native-darwin-arm64": "0.3.0",
-    "kokorobox-native-linux-x64-gnu": "0.3.0",
-    "kokorobox-native-linux-arm64-gnu": "0.3.0",
-    "kokorobox-native-linux-loong64-gnu": "0.3.0"
+    "kokorobox-native-win32-x64-msvc": "0.5.0",
+    "kokorobox-native-win32-arm64-msvc": "0.5.0",
+    "kokorobox-native-darwin-x64": "0.5.0",
+    "kokorobox-native-darwin-arm64": "0.5.0",
+    "kokorobox-native-linux-x64-gnu": "0.5.0",
+    "kokorobox-native-linux-arm64-gnu": "0.5.0"
   }
 }