@neotales/is-elevated 0.0.0-alpha.0 → 0.0.0-alpha.2

package/LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright 2024-2026 Mr. Neobeard
+Copyright 2024-2026 Neotales
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 documentation files (the "Software"), to deal in the Software without restriction, including without limitation the

package/README.md

@@ -8,8 +8,8 @@ On Unix-like systems this typically means root. On Windows it checks whether the
 ![logo](https://raw.githubusercontent.com/neotales/js-std/refs/heads/dev/eng/assets/logo.png)
 
 [![JSR](https://jsr.io/badges/@neotales/is-elevated)](https://jsr.io/@neotales/is-elevated)
-[![npm version](https://badge.fury.io/js/@neostd%2Fis-elevated.svg)](https://badge.fury.io/js/@neostd%2Fis-elevated)
-[![GitHub version](https://badge.fury.io/gh/neostd%2Fjs.svg)](https://badge.fury.io/gh/neostd%2Fjs)
+[![npm version](https://badge.fury.io/js/@neotales%2Fis-elevated.svg)](https://badge.fury.io/js/@neotales%2Fis-elevated)
+[![GitHub version](https://badge.fury.io/gh/neotales%2Fjs.svg)](https://badge.fury.io/gh/neotales%2Fjs)
 
 ## Documentation
 
@@ -64,15 +64,24 @@ On Windows, the package opens the current process token and calls `GetTokenInfor
 
 This intentionally does not use `Shell32.IsUserAnAdmin`. That API checks administrator-group membership rather than the current process token, so it can disagree under User Account Control when an administrator account is running with a filtered, non-elevated token. `TokenElevation` reports the process state directly.
 
-## Runtime Notes
+## Runtime Support
 
-Node.js uses either `node:ffi` or the optional `koffi` peer dependency when available. Bun and Deno use their native FFI support.
-Tests for OS-specific behavior are skipped when the current runtime does not support the required platform semantics.
+This npm package supports Node, Bun, and Deno. Deno users can import it with
+`npm:@neotales/is-elevated`. Call `isElevatedAvailable()` before relying on
+Windows elevation detection when the runtime's FFI configuration may be unknown.
 
-## License
+- **Deno**: run with `--allow-ffi`.
+- **Bun**: the native `bun:ffi` backend is selected automatically.
+- **Node.js**: see [Node.js FFI](#nodejs-ffi).
 
-[MIT License](./LICENSE.md)
+## Node.js FFI
 
-## Runtime Support
+On Windows, Node.js requires a native FFI backend. Run Node >= 26 with
+`--experimental-ffi` to enable `node:ffi`, or install koffi with
+`npm install koffi` when optional dependencies were omitted or unavailable.
+When neither is available, `isElevatedAvailable()` returns `false` and
+`isElevated()` throws an error that links to this section.
 
-This npm package supports Node, Bun, and Deno. Deno users can import it with `npm:@neotales/is-elevated`; use the JSR package for the Deno-only implementation.
+## License
+
+[MIT License](./LICENSE.md)

package/esm/ffi_bun.js

@@ -17,13 +17,6 @@ export function evalIsProcessElevated(cache = true) {
     if (cache && elevated !== undefined) {
         return elevated;
     }
-    elevated = globalThis.process?.getuid?.() === 0;
-    if (!globalThis.Bun) {
-        return elevated;
-    }
-    if (globalThis.process?.platform !== "win32") {
-        return elevated;
-    }
     const advapi32 = dlopen("Advapi32.dll", {
         OpenProcessToken: { args: [FFIType.ptr, FFIType.u32, FFIType.ptr], returns: FFIType.bool },
         GetTokenInformation: {
@@ -36,24 +29,28 @@ export function evalIsProcessElevated(cache = true) {
         CloseHandle: { args: [FFIType.ptr], returns: FFIType.bool },
         GetLastError: { args: [], returns: FFIType.i32 },
     });
-    const TOKEN_QUERY = 0x0008;
-    const TOKEN_ELEVATION = 20;
-    const processHandle = kernel32.symbols.GetCurrentProcess();
-    const tokenHandle = new BigUint64Array(1);
-    const tokenHandlePtr = ptr(tokenHandle);
-    const success = advapi32.symbols.OpenProcessToken(processHandle, TOKEN_QUERY, tokenHandlePtr);
-    if (!success)
-        throw new Error("Failed to open process token");
     try {
-        const tokenInfo = new Uint8Array(4);
-        const returnLength = new Uint32Array(1);
-        const result = advapi32.symbols.GetTokenInformation(tokenHandle[0], TOKEN_ELEVATION, ptr(tokenInfo), 4, ptr(returnLength));
-        if (!result)
-            throw new Error(`Failed to get token information ${kernel32.symbols.GetLastError()}`);
-        elevated = tokenInfo[0] !== 0;
-        return elevated;
+        const TOKEN_QUERY = 0x0008;
+        const TOKEN_ELEVATION = 20;
+        const tokenHandle = new BigUint64Array(1);
+        const success = advapi32.symbols.OpenProcessToken(kernel32.symbols.GetCurrentProcess(), TOKEN_QUERY, ptr(tokenHandle));
+        if (!success)
+            throw new Error("Failed to open process token");
+        try {
+            const tokenInfo = new Uint8Array(4);
+            const returnLength = new Uint32Array(1);
+            const result = advapi32.symbols.GetTokenInformation(tokenHandle[0], TOKEN_ELEVATION, ptr(tokenInfo), 4, ptr(returnLength));
+            if (!result)
+                throw new Error(`Failed to get token information ${kernel32.symbols.GetLastError()}`);
+            elevated = tokenInfo[0] !== 0;
+            return elevated;
+        }
+        finally {
+            kernel32.symbols.CloseHandle(tokenHandle[0]);
+        }
     }
     finally {
-        kernel32.symbols.CloseHandle(tokenHandlePtr);
+        advapi32.close();
+        kernel32.close();
     }
 }

package/esm/ffi_deno.js

@@ -18,12 +18,8 @@ const deno = globalThis.Deno;
  * ```
  */
 export function evalIsProcessElevated(cache = true) {
-    if (!cache || elevated === undefined) {
-        elevated = deno.uid() === 0;
-    }
-    if (deno.build.os !== "windows") {
+    if (cache && elevated !== undefined)
         return elevated;
-    }
     const advapi32 = deno.dlopen("Advapi32.dll", {
         OpenProcessToken: { parameters: ["pointer", "u32", "pointer"], result: "bool" },
         GetTokenInformation: {
@@ -43,21 +39,19 @@ export function evalIsProcessElevated(cache = true) {
         const tokenHandle = new BigUint64Array(1);
         const tokenHandlePtr = deno.UnsafePointer.of(tokenHandle);
         const success = advapi32.symbols.OpenProcessToken(processHandle, TOKEN_QUERY, tokenHandlePtr);
-        if (!success) {
+        if (!success)
             throw new Error("Failed to open process token");
-        }
         try {
             const tokenInfo = new Uint8Array(4);
             const returnLength = new Uint32Array(1);
             const result = advapi32.symbols.GetTokenInformation(tokenHandle[0], TOKEN_ELEVATION, deno.UnsafePointer.of(tokenInfo), 4, deno.UnsafePointer.of(returnLength));
-            if (!result) {
+            if (!result)
                 throw new Error("Failed to get token information " + kernel32.symbols.GetLastError());
-            }
             elevated = tokenInfo[0] !== 0;
             return elevated;
         }
         finally {
-            kernel32.symbols.CloseHandle(tokenHandlePtr);
+            kernel32.symbols.CloseHandle(deno.UnsafePointer.create(tokenHandle[0]));
         }
     }
     finally {

package/esm/ffi_koffi.js

@@ -31,16 +31,14 @@ export function evalIsProcessElevated(cache = true) {
     const processHandle = GetCurrentProcess();
     const tokenOut = [null];
     const opened = OpenProcessToken(processHandle, TOKEN_QUERY, tokenOut);
-    if (!opened) {
+    if (!opened)
         throw new Error(`Failed to open process token (${GetLastError()})`);
-    }
     try {
         const tokenInfo = new Uint8Array(4);
         const returnLength = [0];
-        const ok = GetTokenInformation(tokenOut[0], TOKEN_ELEVATION, tokenInfo, 4, returnLength);
-        if (!ok) {
+        const result = GetTokenInformation(tokenOut[0], TOKEN_ELEVATION, tokenInfo, 4, returnLength);
+        if (!result)
             throw new Error(`Failed to get token information (${GetLastError()})`);
-        }
         elevated = tokenInfo[0] !== 0;
         return elevated;
     }

package/esm/ffi_node.js

@@ -2,18 +2,9 @@ import process from "node:process";
 const { createRequire } = process.getBuiltinModule("node:module");
 const require = createRequire(import.meta.url);
 const ffi = require("node:ffi");
-const advapi32 = ffi.dlopen("Advapi32.dll", {
-    OpenProcessToken: { arguments: ["pointer", "u32", "pointer"], return: "u8" },
-    GetTokenInformation: {
-        arguments: ["pointer", "u32", "pointer", "u32", "pointer"],
-        return: "u8",
-    },
-});
-const kernel32 = ffi.dlopen("Kernel32.dll", {
-    GetCurrentProcess: { arguments: [], return: "pointer" },
-    CloseHandle: { arguments: ["pointer"], return: "u8" },
-    GetLastError: { arguments: [], return: "u32" },
-});
+if (!ffi) {
+    throw new Error();
+}
 let elevated;
 /**
  * Reports whether the current process is running with elevated privileges.
@@ -31,26 +22,42 @@ export function evalIsProcessElevated(cache = true) {
     if (cache && elevated !== undefined) {
         return elevated;
     }
-    const TOKEN_QUERY = 0x0008;
-    const TOKEN_ELEVATION = 20;
-    const processHandle = kernel32.functions.GetCurrentProcess();
-    const tokenHandleBuf = new Uint8Array(8);
-    const opened = advapi32.functions.OpenProcessToken(processHandle, TOKEN_QUERY, tokenHandleBuf);
-    if (!opened) {
-        throw new Error(`Failed to open process token (${kernel32.functions.GetLastError()})`);
-    }
-    const tokenHandle = new DataView(tokenHandleBuf.buffer).getBigUint64(0, true);
+    const advapi32 = ffi.dlopen("Advapi32.dll", {
+        OpenProcessToken: { arguments: ["pointer", "u32", "pointer"], return: "u8" },
+        GetTokenInformation: {
+            arguments: ["pointer", "u32", "pointer", "u32", "pointer"],
+            return: "u8",
+        },
+    });
+    const kernel32 = ffi.dlopen("Kernel32.dll", {
+        GetCurrentProcess: { arguments: [], return: "pointer" },
+        CloseHandle: { arguments: ["pointer"], return: "u8" },
+        GetLastError: { arguments: [], return: "u32" },
+    });
     try {
-        const tokenInfo = new Uint8Array(4);
-        const returnLength = new Uint8Array(4);
-        const ok = advapi32.functions.GetTokenInformation(tokenHandle, TOKEN_ELEVATION, tokenInfo, 4, returnLength);
-        if (!ok) {
-            throw new Error(`Failed to get token information (${kernel32.functions.GetLastError()})`);
+        const TOKEN_QUERY = 0x0008;
+        const TOKEN_ELEVATION = 20;
+        const processHandle = kernel32.functions.GetCurrentProcess();
+        const tokenHandleBuf = new Uint8Array(8);
+        const success = advapi32.functions.OpenProcessToken(processHandle, TOKEN_QUERY, tokenHandleBuf);
+        if (!success)
+            throw new Error(`Failed to open process token (${kernel32.functions.GetLastError()})`);
+        const tokenHandle = new DataView(tokenHandleBuf.buffer).getBigUint64(0, true);
+        try {
+            const tokenInfo = new Uint8Array(4);
+            const returnLength = new Uint8Array(4);
+            const result = advapi32.functions.GetTokenInformation(tokenHandle, TOKEN_ELEVATION, tokenInfo, 4, returnLength);
+            if (!result)
+                throw new Error(`Failed to get token information (${kernel32.functions.GetLastError()})`);
+            elevated = tokenInfo[0] !== 0;
+            return elevated;
+        }
+        finally {
+            kernel32.functions.CloseHandle(tokenHandle);
         }
-        elevated = tokenInfo[0] !== 0;
-        return elevated;
     }
     finally {
-        kernel32.functions.CloseHandle(tokenHandle);
+        advapi32.lib.close();
+        kernel32.lib.close();
     }
 }

package/esm/index.js

@@ -8,42 +8,57 @@ function evalUnixElevation(cache = true) {
     elevated = uid === 0;
     return elevated;
 }
-let impl = evalUnixElevation;
 const runtime = globalThis;
-if (process.platform === "win32") {
-    const { createRequire } = process.getBuiltinModule("node:module");
-    const require = createRequire(import.meta.url);
-    if (runtime.Deno) {
-        impl = require("./ffi_deno.js").evalIsProcessElevated;
-    }
-    else if (runtime.Bun) {
-        impl = require("./ffi_bun.js").evalIsProcessElevated;
-    }
-    else {
-        try {
-            if (process.getBuiltinModule("node:ffi")) {
-                impl = require("./ffi_node.js").evalIsProcessElevated;
-            }
-            else {
-                impl = require("./ffi_koffi.js").evalIsProcessElevated;
-            }
+const isWindows = process.platform === "win32";
+function unsupportedNodeFfi() {
+    throw new Error("Unable to determine Windows process elevation because neither node:ffi nor koffi is available. Run Node.js >= 26 with --experimental-ffi, or install koffi with npm install koffi. See https://github.com/neotales/js-os/blob/dev/npm/is-elevated/README.md#nodejs-ffi");
+}
+function unsupportedRuntimeFfi() {
+    throw new Error("Unable to determine Windows process elevation because the runtime FFI backend is unavailable. Run Deno with --allow-ffi. See https://github.com/neotales/js-os/blob/dev/npm/is-elevated/README.md#runtime-support");
+}
+let impl = evalUnixElevation;
+let isSupported = !isWindows;
+if (isWindows) {
+    try {
+        if (runtime.Deno) {
+            impl = (await import("./ffi_deno.js")).evalIsProcessElevated;
+        }
+        else if (runtime.Bun) {
+            impl = (await import("./ffi_bun.js")).evalIsProcessElevated;
         }
-        catch (error) {
+        else {
             try {
-                impl = require("./ffi_koffi.js").evalIsProcessElevated;
+                impl = (await import("./ffi_node.js")).evalIsProcessElevated;
             }
             catch {
-                if (process.env.DEBUG === "true")
-                    console.debug(error);
+                impl = (await import("./ffi_koffi.js")).evalIsProcessElevated;
             }
         }
+        // A backend import can succeed while FFI permissions or DLL loading fail.
+        // Probe it once before exposing a supported evaluator.
+        impl();
+        isSupported = true;
     }
+    catch (error) {
+        if (process.env.DEBUG === "true")
+            console.debug(error);
+        impl = runtime.Deno || runtime.Bun ? unsupportedRuntimeFfi : unsupportedNodeFfi;
+    }
+}
+/**
+ * Returns whether elevation detection is available in the current runtime.
+ *
+ * @returns `true` when {@linkcode isElevated} can evaluate the current process.
+ */
+export function isElevatedAvailable() {
+    return isSupported;
 }
 /**
  * Reports whether the current process is running with elevated privileges.
  *
  * @param cache - Whether to reuse the result from the first evaluation.
  * @returns Whether the process has elevated privileges.
+ * @throws {Error} On Windows when the runtime has no usable FFI backend.
  * @example
  * import { isElevated } from "@neotales/is-elevated";
  *

package/esm/index.test.js

@@ -0,0 +1,39 @@
+import { strictEqual, throws } from "node:assert/strict";
+import process from "node:process";
+import { test } from "node:test";
+import { isElevated, isElevatedAvailable } from "./index.js";
+import { evalIsProcessElevated as evalNodeIsProcessElevated } from "./node.js";
+test("isElevated returns a boolean", () => {
+    if (process.platform === "win32" && !isElevatedAvailable())
+        return;
+    strictEqual(typeof isElevated(), "boolean");
+    strictEqual(typeof isElevated(false), "boolean");
+});
+test("isElevatedAvailable returns a boolean", () => {
+    strictEqual(typeof isElevatedAvailable(), "boolean");
+});
+test("isElevated caches by default", () => {
+    if (process.platform === "win32" && !isElevatedAvailable())
+        return;
+    strictEqual(isElevated(), isElevated());
+});
+test("node evaluator returns a boolean", () => {
+    strictEqual(typeof evalNodeIsProcessElevated(), "boolean");
+    strictEqual(typeof evalNodeIsProcessElevated(false), "boolean");
+});
+test("node evaluator matches effective uid semantics on unix-like runtimes", { skip: process.platform === "win32" || (!process.geteuid && !process.getuid) }, () => {
+    strictEqual(evalNodeIsProcessElevated(false), (process.geteuid?.() ?? process.getuid?.()) === 0);
+});
+test("isElevated matches effective uid semantics on unix-like runtimes", { skip: process.platform === "win32" || (!process.geteuid && !process.getuid) }, () => {
+    strictEqual(isElevated(false), (process.geteuid?.() ?? process.getuid?.()) === 0);
+});
+test("node evaluator falls back to false when uid is unavailable", { skip: process.platform !== "win32" }, () => {
+    strictEqual(evalNodeIsProcessElevated(false), false);
+});
+test("root helper returns a boolean on Windows-specific runtimes", { skip: process.platform !== "win32" }, () => {
+    if (!isElevatedAvailable()) {
+        throws(() => isElevated(), /node:ffi nor koffi.*#nodejs-ffi/);
+        return;
+    }
+    strictEqual(typeof isElevated(false), "boolean");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neotales/is-elevated",
-  "version": "0.0.0-alpha.0",
+  "version": "0.0.0-alpha.2",
   "description": "Detect whether the current process is elevated.",
   "keywords": [
     "admin",
@@ -47,10 +47,9 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "build:test": "tsc -p tsconfig.test.json",
-    "test": "pnpm run build:test && node --test .test/tests/*.test.js",
-    "test:ffi": "pnpm run build:test && node --experimental-ffi --test .test/tests/*.test.js",
-    "test:bun": "pnpm run build:test && bun test ./.test/tests",
-    "test:deno": "pnpm run build:test && deno test -A .test/tests"
+    "test": "node --test esm/*.test.js",
+    "test:ffi": "node --experimental-ffi --test esm/*.test.js",
+    "test:bun": "bun test ./esm",
+    "test:deno": "deno test -A esm/*.test.js"
   }
 }

package/types/index.d.ts

@@ -1,8 +1,15 @@
+/**
+ * Returns whether elevation detection is available in the current runtime.
+ *
+ * @returns `true` when {@linkcode isElevated} can evaluate the current process.
+ */
+export declare function isElevatedAvailable(): boolean;
 /**
  * Reports whether the current process is running with elevated privileges.
  *
  * @param cache - Whether to reuse the result from the first evaluation.
  * @returns Whether the process has elevated privileges.
+ * @throws {Error} On Windows when the runtime has no usable FFI backend.
  * @example
  * import { isElevated } from "@neotales/is-elevated";
  *

package/types/index.test.d.ts

@@ -0,0 +1 @@
+export {};