kokorobox-native 0.16.0 → 0.16.2

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,37 @@ 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
+## Diagnostics
 
-| 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` |
+`drainNativeLogs()` returns English JSON-compatible records with `ts`, `level`,
+`target`, and `msg`. Use one consumer to periodically drain the queue into the
+application's log. It retains at most 500 records; overflow produces a warning.
+`setNativeLogLevel("debug" | "info" | "warn" | "error")` changes recording
+severity (default: `info`). Healthy polling is only recorded at `debug`. Operation failures retain
+their original exceptions and causes; lifecycle successes record the operation
+name without arguments, keys, or signatures.
 
-`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.
+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`.
 
-`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.
+## Documentation
 
-`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.
+- [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)
 
-`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/diagnostics.js

@@ -0,0 +1,125 @@
+// Diagnostics belong to the calling application. Do not open a log file or
+// retain operation arguments (which may contain keys or signatures).
+const maxEntries = 500;
+const maxMessageLength = 4096;
+const levels = ["debug", "info", "warn", "error"];
+const lifecycleOperations = new Set([
+  "runServiceLifecycleElevated",
+  "registerMacosManagedService",
+  "unregisterMacosManagedService",
+  "reloadMacosManagedService",
+  "cleanupLegacyMacosService",
+  "stopMacosManagedService",
+  "repairManagedFilePermissions",
+  "setCorePrivileges",
+  "applyMacosApplicationRouting",
+  "stopMacosApplicationRouting",
+  "setLaunchAtLogin",
+  "setUwpLoopbackExemption",
+]);
+
+function boundedMessage(value) {
+  const text = String(value);
+  if (text.length <= maxMessageLength) return text;
+  let end = maxMessageLength;
+  if (/^[\uDC00-\uDFFF]$/.test(text[end])) end--;
+  return text.slice(0, end) + "…";
+}
+
+export function nativeErrorMessage(error) {
+  const parts = [];
+  const seen = new Set();
+  function visit(value, depth = 0) {
+    if (depth > 4 || seen.has(value)) return;
+    seen.add(value);
+    const message = value instanceof Error ? value.message : String(value);
+    if (message && !parts.includes(message))
+      parts.push(boundedMessage(message));
+    if (value && typeof value === "object" && value.cause != null) {
+      if (Array.isArray(value.cause))
+        value.cause.slice(0, 4).forEach((item) => visit(item, depth + 1));
+      else visit(value.cause, depth + 1);
+    }
+  }
+  visit(error);
+  return boundedMessage(parts.join(": "));
+}
+
+export function createNativeDiagnostics() {
+  let minimum = "info";
+  let entries = [];
+  let dropped = 0;
+  const record = (level, target, msg) => {
+    if (levels.indexOf(level) < levels.indexOf(minimum)) return;
+    entries.push({
+      ts: new Date().toISOString(),
+      level,
+      target,
+      msg: boundedMessage(msg),
+    });
+    if (entries.length > maxEntries) {
+      entries.shift();
+      dropped++;
+    }
+  };
+  return {
+    setLevel(level) {
+      if (!levels.includes(level))
+        throw new TypeError(
+          "Invalid Native log level: expected debug, info, warn, or error",
+        );
+      minimum = level;
+    },
+    drain() {
+      const result = entries;
+      entries = [];
+      if (dropped) {
+        result.unshift({
+          ts: new Date().toISOString(),
+          level: "warn",
+          target: "diagnostics",
+          msg: `Dropped ${dropped} older Native log entries`,
+        });
+        dropped = 0;
+      }
+      return result;
+    },
+    wrap(target, operation) {
+      if (typeof operation !== "function") return operation;
+      const failed = (error) => {
+        record("error", target, nativeErrorMessage(error));
+        throw error;
+      };
+      const completed = (value) => {
+        if (value && value.state === "error")
+          record(
+            "error",
+            target,
+            typeof value.message === "string"
+              ? value.message
+              : "Native operation returned an error status",
+          );
+        else if (lifecycleOperations.has(target))
+          record("info", target, "Native operation completed");
+        else record("debug", target, "Native operation completed");
+        return value;
+      };
+      return function (...args) {
+        let result;
+        try {
+          result = Reflect.apply(operation, this, args);
+        } catch (error) {
+          return failed(error);
+        }
+        if (result && typeof result.then === "function")
+          return result.then(completed, failed);
+        return completed(result);
+      };
+    },
+  };
+}
+
+const diagnostics = createNativeDiagnostics();
+export const wrapNativeOperation = diagnostics.wrap;
+export const drainNativeLogs = diagnostics.drain;
+export const setNativeLogLevel = diagnostics.setLevel;

package/index.d.ts

@@ -1,3 +1,14 @@
+export interface NativeLogEntry {
+  ts: string;
+  level: "debug" | "info" | "warn" | "error";
+  target: string;
+  msg: string;
+}
+/** Drains at most 500 entries and an optional overflow warning; use one consumer. */
+export declare function drainNativeLogs(): NativeLogEntry[];
+/** Controls recording, independently from display language. Defaults to info. */
+export declare function setNativeLogLevel(level: NativeLogEntry["level"]): void;
+
 export interface UwpLoopbackApp {
   /** Opaque identifier used only when changing this app's loopback exemption. */
   id: string;

package/index.js

@@ -5,6 +5,13 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from "node:path";
 import { createRequire } from "node:module";
+import {
+  nativeErrorMessage,
+  wrapNativeOperation,
+  drainNativeLogs,
+  setNativeLogLevel,
+} from "./diagnostics.js";
+export { drainNativeLogs, setNativeLogLevel };
 
 const require = createRequire(import.meta.url);
 const __dirname = new URL(".", import.meta.url).pathname.replace(
@@ -71,7 +78,9 @@ export function getPortableUpdaterPath() {
     const packagedPath = join(dirname(packageEntry), filename);
     if (existsSync(packagedPath)) return packagedPath;
   }
-  throw new Error(`Portable updater is missing for ${process.platform} ${process.arch}`);
+  throw new Error(
+    `Portable updater is missing for ${process.platform} ${process.arch}`,
+  );
 }
 
 function requireNative() {
@@ -105,49 +114,88 @@ function requireNative() {
 const nativeBinding = requireNative();
 
 if (!nativeBinding) {
-  const error = new Error("Failed to load kokorobox-native binding");
+  const detail = nativeErrorMessage({
+    cause: loadErrors,
+    toString: () => "Failed to load kokorobox-native binding",
+  });
+  const error = new Error(detail);
   error.cause = loadErrors;
   throw error;
 }
 
-export default nativeBinding;
-export const fileToDataUrl = nativeBinding.fileToDataUrl;
-export const fileToStr = nativeBinding.fileToStr;
-export const getAppName = nativeBinding.getAppName;
-export const getNativeCapabilities = nativeBinding.getNativeCapabilities;
-export const getWindowsServiceStatus = nativeBinding.getWindowsServiceStatus;
-export const getLinuxServiceStatus = nativeBinding.getLinuxServiceStatus;
-export const setTerminalProxyEnvironment = nativeBinding.setTerminalProxyEnvironment;
-export const clearTerminalProxyEnvironment = nativeBinding.clearTerminalProxyEnvironment;
-export const findExecutables = nativeBinding.findExecutables;
-export const getLaunchAtLogin = nativeBinding.getLaunchAtLogin;
-export const setLaunchAtLogin = nativeBinding.setLaunchAtLogin;
-export const getNetworkContext = nativeBinding.getNetworkContext;
-export const waitForNetworkContextChange = nativeBinding.waitForNetworkContextChange;
-export const getMacosManagedServiceStatus = nativeBinding.getMacosManagedServiceStatus;
-export const getMacosServiceProcessStatus = nativeBinding.getMacosServiceProcessStatus;
-export const registerMacosManagedService = nativeBinding.registerMacosManagedService;
-export const unregisterMacosManagedService = nativeBinding.unregisterMacosManagedService;
-export const reloadMacosManagedService = nativeBinding.reloadMacosManagedService;
-export const openMacosLoginItemsSettings = nativeBinding.openMacosLoginItemsSettings;
-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;
-export const repairManagedFilePermissions = nativeBinding.repairManagedFilePermissions;
-export const relaunchCurrentApplicationWithPrivilege = nativeBinding.relaunchCurrentApplicationWithPrivilege;
-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;
-export const isRunningAsAdmin = nativeBinding.isRunningAsAdmin;
-export const ensureKokoroBoxCoreFirewall = nativeBinding.ensureKokoroBoxCoreFirewall;
-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;
+// Preserve native classes and unsupported exports; wrap callable operations
+// for both named imports and the default binding without changing arguments.
+const diagnosticBinding = {};
+for (const [name, descriptor] of Object.entries(
+  Object.getOwnPropertyDescriptors(nativeBinding),
+)) {
+  if (/^[a-z]/.test(name) && typeof descriptor.value === "function") {
+    descriptor.value = wrapNativeOperation(name, descriptor.value);
+  }
+  Object.defineProperty(diagnosticBinding, name, descriptor);
+}
+diagnosticBinding.drainNativeLogs = drainNativeLogs;
+diagnosticBinding.setNativeLogLevel = setNativeLogLevel;
+export default diagnosticBinding;
+export const fileToDataUrl = diagnosticBinding.fileToDataUrl;
+export const fileToStr = diagnosticBinding.fileToStr;
+export const getAppName = diagnosticBinding.getAppName;
+export const getNativeCapabilities = diagnosticBinding.getNativeCapabilities;
+export const getWindowsServiceStatus =
+  diagnosticBinding.getWindowsServiceStatus;
+export const getLinuxServiceStatus = diagnosticBinding.getLinuxServiceStatus;
+export const setTerminalProxyEnvironment =
+  diagnosticBinding.setTerminalProxyEnvironment;
+export const clearTerminalProxyEnvironment =
+  diagnosticBinding.clearTerminalProxyEnvironment;
+export const findExecutables = diagnosticBinding.findExecutables;
+export const getLaunchAtLogin = diagnosticBinding.getLaunchAtLogin;
+export const setLaunchAtLogin = diagnosticBinding.setLaunchAtLogin;
+export const getNetworkContext = diagnosticBinding.getNetworkContext;
+export const waitForNetworkContextChange =
+  diagnosticBinding.waitForNetworkContextChange;
+export const getMacosManagedServiceStatus =
+  diagnosticBinding.getMacosManagedServiceStatus;
+export const getMacosServiceProcessStatus =
+  diagnosticBinding.getMacosServiceProcessStatus;
+export const registerMacosManagedService =
+  diagnosticBinding.registerMacosManagedService;
+export const unregisterMacosManagedService =
+  diagnosticBinding.unregisterMacosManagedService;
+export const reloadMacosManagedService =
+  diagnosticBinding.reloadMacosManagedService;
+export const openMacosLoginItemsSettings =
+  diagnosticBinding.openMacosLoginItemsSettings;
+export const applyMacosApplicationRouting =
+  diagnosticBinding.applyMacosApplicationRouting;
+export const getMacosApplicationRoutingStatus =
+  diagnosticBinding.getMacosApplicationRoutingStatus;
+export const stopMacosApplicationRouting =
+  diagnosticBinding.stopMacosApplicationRouting;
+export const openMacosApplicationRoutingSettings =
+  diagnosticBinding.openMacosApplicationRoutingSettings;
+export const runServiceLifecycleElevated =
+  diagnosticBinding.runServiceLifecycleElevated;
+export const cleanupLegacyMacosService =
+  diagnosticBinding.cleanupLegacyMacosService;
+export const stopMacosManagedService =
+  diagnosticBinding.stopMacosManagedService;
+export const repairManagedFilePermissions =
+  diagnosticBinding.repairManagedFilePermissions;
+export const relaunchCurrentApplicationWithPrivilege =
+  diagnosticBinding.relaunchCurrentApplicationWithPrivilege;
+export const getCorePrivilegeStatus = diagnosticBinding.getCorePrivilegeStatus;
+export const setCorePrivileges = diagnosticBinding.setCorePrivileges;
+export const inspectApplication = diagnosticBinding.inspectApplication;
+export const scanWindowsApplications =
+  diagnosticBinding.scanWindowsApplications;
+export const getCurrentUserSid = diagnosticBinding.getCurrentUserSid;
+export const isRunningAsAdmin = diagnosticBinding.isRunningAsAdmin;
+export const ensureKokoroBoxCoreFirewall =
+  diagnosticBinding.ensureKokoroBoxCoreFirewall;
+export const listUwpLoopbackApps = diagnosticBinding.listUwpLoopbackApps;
+export const setUwpLoopbackExemption =
+  diagnosticBinding.setUwpLoopbackExemption;
+export const ServiceIdentity = diagnosticBinding.ServiceIdentity;
+export const openServiceIdentity = diagnosticBinding.openServiceIdentity;
+export const deleteServiceIdentity = diagnosticBinding.deleteServiceIdentity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokorobox-native",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "KokoroBox native bridge",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,7 @@
   "license": "GPL-3.0-only",
   "files": [
     "index.js",
+    "diagnostics.js",
     "index.d.ts",
     "README.md"
   ],
@@ -32,6 +33,7 @@
     ]
   },
   "scripts": {
+    "test:logs": "node --test tests/diagnostics.test.mjs",
     "build": "napi build --platform --release --strip --no-js --dts napi.generated.d.ts",
     "build:debug": "napi build --platform --no-js --dts napi.generated.d.ts",
     "create-npm-dirs": "napi create-npm-dirs",
@@ -48,11 +50,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.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"
   }
 }