@neotales/is-elevated 0.0.0-alpha.0

package/LICENSE.md

@@ -0,0 +1,16 @@
+# MIT License
+
+Copyright 2024-2026 Mr. Neobeard
+
+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
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @neotales/is-elevated
+
+## Overview
+
+`@neotales/is-elevated` detects whether the current process is running with elevated privileges.
+On Unix-like systems this typically means root. On Windows it checks whether the current token is elevated.
+
+![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)
+
+## Documentation
+
+Documentation is available on [jsr.io](https://jsr.io/@neotales/is-elevated/doc).
+
+A list of other modules can be found at [github.com/neotales/js-os](https://github.com/neotales/js-os).
+
+## Installation
+
+```bash
+# Deno
+deno add jsr:@neotales/is-elevated
+
+# npm from jsr
+npx jsr add @neotales/is-elevated
+
+# from npmjs.org
+npm install @neotales/is-elevated
+```
+
+## Usage
+
+```typescript
+import { isElevated } from "@neotales/is-elevated";
+
+if (!isElevated()) {
+  throw new Error("Run this as admin/root");
+}
+```
+
+## Exports
+
+| Export       | Subpath                 | Description                                      |
+| ------------ | ----------------------- | ------------------------------------------------ |
+| `isElevated` | `@neotales/is-elevated` | Detects whether the current process is elevated. |
+
+```typescript
+import { isElevated } from "@neotales/is-elevated";
+
+const elevated = isElevated();
+
+if (elevated) {
+  console.log("ready for privileged work");
+}
+```
+
+## Elevation Detection
+
+On Unix-like systems, elevation means an effective user ID of `0`. Node and Bun check `process.geteuid()` when available, then fall back to `process.getuid()`. The result is cached so repeated checks do not need to query the runtime again.
+
+On Windows, the package opens the current process token and calls `GetTokenInformation` with `TokenElevation`. Node uses native `node:ffi` when available and otherwise the optional `koffi` dependency; Bun and Deno use their native FFI implementations. The FFI implementations are loaded only on Windows.
+
+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
+
+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.
+
+## License
+
+[MIT License](./LICENSE.md)
+
+## Runtime Support
+
+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.

package/esm/ffi_bun.js

@@ -0,0 +1,59 @@
+/// <reference types="@types/bun" />
+import { dlopen, FFIType, ptr } from "bun:ffi";
+let elevated;
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_bun.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+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: {
+            args: [FFIType.u64, FFIType.u32, FFIType.ptr, FFIType.u32, FFIType.ptr],
+            returns: FFIType.bool,
+        },
+    });
+    const kernel32 = dlopen("Kernel32.dll", {
+        GetCurrentProcess: { args: [], returns: FFIType.ptr },
+        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;
+    }
+    finally {
+        kernel32.symbols.CloseHandle(tokenHandlePtr);
+    }
+}

package/esm/ffi_deno.js

@@ -0,0 +1,67 @@
+/**
+ * Implements native Windows elevation detection for Deno.
+ *
+ * @module @neotales/is-elevated/ffi_deno
+ */
+let elevated;
+const deno = globalThis.Deno;
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_deno.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+export function evalIsProcessElevated(cache = true) {
+    if (!cache || elevated === undefined) {
+        elevated = deno.uid() === 0;
+    }
+    if (deno.build.os !== "windows") {
+        return elevated;
+    }
+    const advapi32 = deno.dlopen("Advapi32.dll", {
+        OpenProcessToken: { parameters: ["pointer", "u32", "pointer"], result: "bool" },
+        GetTokenInformation: {
+            parameters: ["u64", "u32", "pointer", "u32", "pointer"],
+            result: "bool",
+        },
+    });
+    const kernel32 = deno.dlopen("Kernel32.dll", {
+        GetCurrentProcess: { parameters: [], result: "pointer" },
+        CloseHandle: { parameters: ["pointer"], result: "bool" },
+        GetLastError: { parameters: [], result: "i32" },
+    });
+    try {
+        const TOKEN_QUERY = 0x0008;
+        const TOKEN_ELEVATION = 20;
+        const processHandle = kernel32.symbols.GetCurrentProcess();
+        const tokenHandle = new BigUint64Array(1);
+        const tokenHandlePtr = deno.UnsafePointer.of(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, deno.UnsafePointer.of(tokenInfo), 4, deno.UnsafePointer.of(returnLength));
+            if (!result) {
+                throw new Error("Failed to get token information " + kernel32.symbols.GetLastError());
+            }
+            elevated = tokenInfo[0] !== 0;
+            return elevated;
+        }
+        finally {
+            kernel32.symbols.CloseHandle(tokenHandlePtr);
+        }
+    }
+    finally {
+        advapi32.close();
+        kernel32.close();
+    }
+}

package/esm/ffi_koffi.js

@@ -0,0 +1,51 @@
+import process from "node:process";
+const { createRequire } = process.getBuiltinModule("node:module");
+const require = createRequire(import.meta.url);
+const koffi = require("koffi");
+const advapi32 = koffi.load("Advapi32.dll");
+const kernel32 = koffi.load("Kernel32.dll");
+const OpenProcessToken = advapi32.func("int __stdcall OpenProcessToken(void *ProcessHandle, uint32 DesiredAccess, _Out_ void **TokenHandle)");
+const GetTokenInformation = advapi32.func("int __stdcall GetTokenInformation(void *TokenHandle, uint32 TokenInformationClass, void *TokenInformation, uint32 TokenInformationLength, _Out_ uint32 *ReturnLength)");
+const GetCurrentProcess = kernel32.func("void * __stdcall GetCurrentProcess()");
+const CloseHandle = kernel32.func("int __stdcall CloseHandle(void *hObject)");
+const GetLastError = kernel32.func("uint32 __stdcall GetLastError()");
+let elevated;
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_koffi.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+export function evalIsProcessElevated(cache = true) {
+    if (cache && elevated !== undefined) {
+        return elevated;
+    }
+    const TOKEN_QUERY = 0x0008;
+    const TOKEN_ELEVATION = 20;
+    const processHandle = GetCurrentProcess();
+    const tokenOut = [null];
+    const opened = OpenProcessToken(processHandle, TOKEN_QUERY, tokenOut);
+    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) {
+            throw new Error(`Failed to get token information (${GetLastError()})`);
+        }
+        elevated = tokenInfo[0] !== 0;
+        return elevated;
+    }
+    finally {
+        if (tokenOut[0])
+            CloseHandle(tokenOut[0]);
+    }
+}

package/esm/ffi_node.js

@@ -0,0 +1,56 @@
+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" },
+});
+let elevated;
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_node.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+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);
+    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()})`);
+        }
+        elevated = tokenInfo[0] !== 0;
+        return elevated;
+    }
+    finally {
+        kernel32.functions.CloseHandle(tokenHandle);
+    }
+}

package/esm/index.js

@@ -0,0 +1,56 @@
+import process from "node:process";
+let elevated;
+function evalUnixElevation(cache = true) {
+    if (cache && elevated !== undefined) {
+        return elevated;
+    }
+    const uid = process.geteuid?.() ?? process.getuid?.();
+    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;
+            }
+        }
+        catch (error) {
+            try {
+                impl = require("./ffi_koffi.js").evalIsProcessElevated;
+            }
+            catch {
+                if (process.env.DEBUG === "true")
+                    console.debug(error);
+            }
+        }
+    }
+}
+/**
+ * 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.
+ * @example
+ * import { isElevated } from "@neotales/is-elevated";
+ *
+ * if (isElevated()) {
+ *   console.log("The process is elevated.");
+ * }
+ */
+export function isElevated(cache = true) {
+    return impl(cache);
+}

package/esm/node.js

@@ -0,0 +1,20 @@
+import process from "node:process";
+let elevated;
+/**
+ * Reports whether the current process has an effective user ID of zero.
+ *
+ * @param cache - Whether to reuse the result from the first evaluation.
+ * @returns Whether the process has an effective user ID of zero.
+ * @example
+ * import { evalIsProcessElevated } from "./node.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ */
+export function evalIsProcessElevated(cache = true) {
+    if (cache && elevated !== undefined) {
+        return elevated;
+    }
+    const uid = process.geteuid?.() ?? process.getuid?.();
+    elevated = uid === 0;
+    return elevated;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@neotales/is-elevated",
+  "version": "0.0.0-alpha.0",
+  "description": "Detect whether the current process is elevated.",
+  "keywords": [
+    "admin",
+    "elevated",
+    "root",
+    "std",
+    "sudo",
+    "windows"
+  ],
+  "homepage": "https://github.com/neotales/js-os",
+  "bugs": {
+    "url": "https://github.com/neotales/js-os/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neotales/js-os.git",
+    "directory": "npm/is-elevated"
+  },
+  "files": [
+    "esm",
+    "types"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./esm/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.9.3",
+    "typescript": "^6.0.3"
+  },
+  "optionalDependencies": {
+    "koffi": "^2.9.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "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"
+  }
+}

package/types/ffi_bun.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_bun.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+export declare function evalIsProcessElevated(cache?: boolean): boolean;

package/types/ffi_deno.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Implements native Windows elevation detection for Deno.
+ *
+ * @module @neotales/is-elevated/ffi_deno
+ */
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_deno.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+export declare function evalIsProcessElevated(cache?: boolean): boolean;

package/types/ffi_koffi.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_koffi.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+export declare function evalIsProcessElevated(cache?: boolean): boolean;

package/types/ffi_node.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { evalIsProcessElevated } from "./ffi_node.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ * ```
+ */
+export declare function evalIsProcessElevated(cache?: boolean): boolean;

package/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ * @example
+ * import { isElevated } from "@neotales/is-elevated";
+ *
+ * if (isElevated()) {
+ *   console.log("The process is elevated.");
+ * }
+ */
+export declare function isElevated(cache?: boolean): boolean;

package/types/node.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reports whether the current process has an effective user ID of zero.
+ *
+ * @param cache - Whether to reuse the result from the first evaluation.
+ * @returns Whether the process has an effective user ID of zero.
+ * @example
+ * import { evalIsProcessElevated } from "./node.js";
+ *
+ * const elevated = evalIsProcessElevated();
+ */
+export declare function evalIsProcessElevated(cache?: boolean): boolean;