@wuyuchentr/run-as-user 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# @wuyuchentr/run-as-user
+
+Drop privileges and run a function as another user. **Requires root.** POSIX-only (Linux, macOS).
+
+> Designed for daemon processes that start as root and want to drop to a lower-privileged user.
+
+## Install
+
+```bash
+npm install @wuyuchentr/run-as-user
+```
+
+## Usage
+
+```js
+const { runAs, isRoot } = require('@wuyuchentr/run-as-user');
+
+runAs('nobody', () => {
+  // This code runs as the 'nobody' user
+  startServer();
+});
+```
+
+### Forms
+
+```js
+// By username
+runAs('www-data', () => { ... });
+runAs('nobody', () => { ... });
+
+// By UID
+runAs(65534, () => { ... });
+
+// By object (no /etc/passwd lookup)
+runAs({ uid: 1000, gid: 1000 }, () => { ... });
+```
+
+### Helpers
+
+```js
+isRoot();  // → true if euid === 0
+```
+
+## How it works
+
+Resolves the target user via `/etc/passwd`, then in order:
+
+1. `initgroups()` — set supplementary groups
+2. `setgid()` — set primary group ID
+3. `setuid()` — set user ID (permanent drop)
+
+After `setuid()` the process **cannot regain root**. This is intentional.
+
+## Notes
+
+- Only works on POSIX with `setuid`/`setgid` syscalls
+- The target user must exist in `/etc/passwd` (unless using `{ uid, gid }` form)
+- `{ uid, gid }` form skips supplementary group initialization

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@wuyuchentr/run-as-user",
+  "version": "1.0.0",
+  "description": "Drop privileges and run a function as another user (requires root). POSIX-only.",
+  "main": "src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "privilege",
+    "drop",
+    "setuid",
+    "setgid",
+    "user",
+    "security",
+    "root"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wuyuchentr/run-as-user.git"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,86 @@
+const fs = require('fs');
+
+function parsePasswd() {
+  const byName = {};
+  const byUid = {};
+  try {
+    const data = fs.readFileSync('/etc/passwd', 'utf-8');
+    for (const line of data.split('\n')) {
+      if (!line || line.startsWith('#')) continue;
+      const parts = line.split(':');
+      if (parts.length < 7) continue;
+      const entry = {
+        username: parts[0],
+        uid: parseInt(parts[2], 10),
+        gid: parseInt(parts[3], 10),
+        home: parts[5],
+        shell: parts[6].trim(),
+      };
+      byName[entry.username] = entry;
+      byUid[entry.uid] = entry;
+    }
+  } catch {}
+  return { byName, byUid };
+}
+
+const _passwd = parsePasswd();
+
+function resolveUser(spec) {
+  if (typeof spec === 'number') {
+    const e = _passwd.byUid[spec];
+    if (!e) throw new Error(`User with UID ${spec} not found in /etc/passwd`);
+    return e;
+  }
+  if (typeof spec === 'string') {
+    if (/^\d+$/.test(spec)) return resolveUser(parseInt(spec, 10));
+    const e = _passwd.byName[spec];
+    if (!e) throw new Error(`User '${spec}' not found in /etc/passwd`);
+    return e;
+  }
+  if (spec && typeof spec.uid === 'number' && typeof spec.gid === 'number') {
+    return {
+      username: spec.username || `uid-${spec.uid}`,
+      uid: spec.uid,
+      gid: spec.gid,
+      home: spec.home || '',
+      shell: spec.shell || '',
+    };
+  }
+  throw new Error('runAs: expected username (string), UID (number), or { uid, gid } object');
+}
+
+function isRoot() {
+  return typeof process.geteuid === 'function' && process.geteuid() === 0;
+}
+
+function runAs(user, fn) {
+  if (process.platform === 'win32')
+    throw new Error('runAs is not supported on Windows');
+
+  if (typeof fn !== 'function')
+    throw new Error('runAs: second argument must be a function');
+
+  if (!isRoot())
+    throw new Error('runAs requires root privileges (euid !== 0)');
+
+  const target = resolveUser(user);
+
+  if (process.getuid() === target.uid && process.getgid() === target.gid) {
+    return fn();
+  }
+
+  if (target.username) {
+    try { process.initgroups(target.username, target.gid); } catch {}
+  }
+
+  try {
+    process.setgid(target.gid);
+    process.setuid(target.uid);
+  } catch (err) {
+    throw new Error(`Failed to drop privileges to ${target.username || target.uid}: ${err.message}`);
+  }
+
+  return fn();
+}
+
+module.exports = { runAs, isRoot, resolveUser };