@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.

Documentation

Documentation is available on jsr.io.

A list of other modules can be found at github.com/neotales/js-os.

Installation

deno add jsr:@neotales/is-elevated
npx jsr add @neotales/is-elevated
npm install @neotales/is-elevated

Usage

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. |

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 Support

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.

• Deno: run with --allow-ffi.
• Bun: the native bun:ffi backend is selected automatically.
• Node.js: see Node.js FFI.

Node.js FFI

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.

License

MIT License