node-posix-ext

A drop-in replacement for the Node.js modules process, fs and posix providing their POSIX functionality on both POSIX and Windows platforms.

Motivation

Node.js exposes POSIX APIs, among the others. Some of them are implemented on Windows, some are not. When writing a cross-platform code, the latter must be wrapped by additional code, because the Node.js built-ins do not offer a cross-platform feature.

Some POSIX APIs can be implemented on Windows too and can provide the desired cross-platform functionality. For example, the built-in process object and the core fs module do. The optional modules posix and fs-ext provide additional POSIX APIs to complete the Node.js offer. However, not all functions are callable on Windows.

For example, user and group identifiers in file stats are (integer) numbers on POSIX platforms, while Windows represents them with SIDs. The type is different, but otherwise the primer is the same. Why not using the same methods on both platforms? User and group identifiers are "black boxes" for the caller anyway; meaning their actual data type...

Features

The following methods expect and/or return user and group identifiers (uid, gid) and this module implements them to handle and/or produce SIDs on windows, while defaulting to the original functionality in POSIX:

process: getuid, getgid, getgroups
fs:      stat, lstat, fstat, chown, lchown, fchown
posix:   getpwnam, getpwuid, getgrnam, getgrgid

Installation

The installation of this module can be performed either from the GitHub sources or simply from the NPM repository:

npm install posix-ext

For Windows users: you will need a C++ compiler capable of compiling native Node.js modules and Python 2.x, before you install this module. If you do not have those, you can install them easily by installing the NPM module windows-build-tools globaly. Execute the following command in the PowerShell Console or Command Prompt with elevated permissions ("Run as Administrator"`):

npm install --global --production windows-build-tools

Usage

This module provides patched objects for the process, fs and posix modules, adding functionality on Windows and reusing the built-in one on POSIX:

var posix = require('../lib/posix-ext'),
    process = posix.process,
    fs = posix.fs;

Process Calls on Windows

process.getgid()

Returns the current process's group SID as string.

// Prints "GID: S-1-5-32-513"
console.log('GID:', process.getgid());

process.getuid()

Returns the current process's user SID as string.

// Prints "UID: S-1-5-21-3974217899-2981595321-1938156221-1011"
console.log('UID:', process.getuid());

process.getgroups()

Returns supplementary groups of the current process as an array of strings with the group SIDs.

console.log('Groups:', process.getgroups());

POSIX Calls on Windows

posix.getgrnam(group)

Gets the group information structured as a POSIX group database entry for the given group. group can be specified as a string with a group name.

var util = require('util');
util.inspect(posix.getgrnam('NOTO\\Users'));

A sample output of the code above:

{ name: 'NOTO\\Users', passwd: 'x',
  gid: 'S-1-5-21-3974217899-2981595321-1938156221-513',
  members:
   [ 'NT AUTHORITY\\INTERACTIVE',
     'NT AUTHORITY\\Authenticated Users',
     'NOTO\\prantlf' ] }

posix.getgruid(user)

Gets the group information structured as a POSIX group database entry for the given group. group can be specified as a string with a SID.

var group = posix.getgrnam('S-1-5-21-3974217899-2981595321-1938156221-513');

See getgrnam for more information.

posix.getpwnam(user)

Gets the user information structured as a POSIX user database entry for the given user. user can be specified as a string with a user name.

var util = require('util');
util.inspect(posix.getpwnam('NOTO\\prantlf'));

A sample output of the code above:

{ name: 'NOTO\\prantlf', passwd: 'x',
  uid: 'S-1-5-21-3974217899-2981595321-1938156221-1011',
  gid: 'S-1-5-32-513',
  gecos: 'Ferdinand Prantl',
  shell: '', dir: '' }

posix.getpwuid(user)

Gets the user information structured as a POSIX user database entry for the given user. user can be specified as a string with a SID.

var user = posix.getpwnam('S-1-5-21-3974217899-2981595321-1938156221-1011');

See getpwnam for more information.

posix.options: object

Exposes flags to control behavior of the methods above.

populateGroupMembers: boolean

Disables enumerating of group members to populate the members property of the group information. If yoiu do not need it and work on a slow domain network with a groups with many members, you may turn it off. The value it true (populating members is enabled) by default.

posix.options.populateGroupMembers = false;

FileSystem Calls on Windows

Every method as also a synchronous alternative. Their names end with the "Sync" suffix and they lack the last callback argument. If they succeed, they return their result, instead of passing it to the second callback argument. If they fail, they throw the error, instead of passing it to the first callback argument.

fs.stat(path, callback)

Refers to users and groups in the output uid and gid properties by their SIDs (strings). See the original implementation for more infoemation.

fs.lstat(path, callback)

Refers to users and groups in the output uid and gid properties by their SIDs (strings). See the original implementation for more infoemation.

fs.fstat(fd, callback)

Refers to users and groups in the output uid and gid properties by their SIDs (strings). See the original implementation for more infoemation.

fs.chown(path, uid, gid, callback)

Refers to users and groups in the input uid and gid arguments by their SIDs (strings). See the original implementation for more infoemation.

fs.lchown(path, uig, gid, callback)

Refers to users and groups in the input uid and gid arguments by their SIDs (strings). See the original implementation for more infoemation.

fs.fchown(fd, uid, gid, callback)

Refers to users and groups in the input uid and gid arguments by their SIDs (strings). See the original implementation for more infoemation.

Script Example

Output of the example/example-whoami.js run on Linux:

$ node node_modules/posix-ext/example/example-whoami.js
user:   { name: 'prantlf', passwd: 'x',
  uid: 1000, gid: 1000,
  gecos: 'Ferdinand Prantl,,,[email protected]',
  shell: '/bin/bash', dir: '/home/prantlf' }
group:  { name: 'prantlf', passwd: 'x', gid: 1000, members: [] }
groups: [ 'adm (4)',
  'cdrom (24)',
  'sudo (27)',
  'dip (30)',
  'plugdev (46)',
  'lpadmin (109)',
  'sambashare (124)',
  'prantlf (1000)' ]

Output of the example/example-whoami.js run on Windows:

> node node_modules\posix-ext\example\example-whoami.js
user:   { name: 'NOTO\\prantlf', passwd: 'x',
  uid: 'S-1-5-21-3974217899-2981595321-1938156221-1011',
  gid: 'S-1-5-32-513',
  gecos: 'Ferdinand Prantl',
  shell: '', dir: '' }
group:  { name: 'NOTO\\Users', passwd: 'x',
  gid: 'S-1-5-21-3974217899-2981595321-1938156221-513',
  members:
   [ 'NT AUTHORITY\\INTERACTIVE',
     'NT AUTHORITY\\Authenticated Users',
     'NOTO\\prantlf' ] }
groups: [ 'NOTO\\Users (S-1-5-21-3974217899-2981595321-1938156221-513)',
  'Everyone (S-1-1-0)',
  'BUILTIN\\Users (S-1-5-32-545)',
  'BUILTIN\\Remote Desktop Users (S-1-5-32-555)',
  'NT AUTHORITY\\INTERACTIVE (S-1-5-4)',
  'NT AUTHORITY\\Authenticated Users (S-1-5-11)',
  'LOCAL (S-1-2-0)',
  'NT AUTHORITY\\NTLM Authentication (S-1-5-64-10)' ]

Build

Make sure that you have [NodeJS] >= 4 and the global NPM module node-gyp installed. Clone the Github repository to a local directory and enter it. Install the package dependencies, build and test.

git clone https://github.com/prantlf/node-posix-ext.git
cd node-posix-ext
npm install
node-gyp configure
node-gyp build
npm test

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.

First fork this repository and clone your fork locally instead of cloning the original. See the "Build" chapter above for more details about how to clone it and install the build dependencies.

Before you commit, check if tests succeed:

node-gyp configure
node-gyp build
npm test

Commit your changes to a separtate branch, so that you can create a pull request for it:

git checkout -b <branch name>
git commit -a
git push origin <branch name>

Release History

• 2018-04-27 v0.4.5 Upgrade NPM module dependencies
• 2017-08-07 v0.4.0 Allow disable populating group members
• 2017-08-07 v0.3.0 Fix handling of files and users with non-ASCII characters
• 2017-08-06 v0.2.0 Fix building for recent Node.js versions on Windows
• 2017-07-29 v0.1.2 Fix building for Node.js versions >= 0.12 and <= 8
• 2014-01-20 v0.1.1 Fix building with MSVC 2008
• 2014-01-02 v0.1.0 Initial release

License

Copyright (c) 2013-2018 Ferdinand Prantl

Licensed under the MIT license.