Skip to content
Swiss Army knife for Unix permissions
Branch: master
Clone or download
Latest commit 516906b Mar 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Improve documentation Mar 19, 2019
examples Add examples README Mar 19, 2019
src
test Fix Windows support Mar 19, 2019
.all-contributorsrc Add all-contributors Mar 10, 2019
.editorconfig Initial commit Dec 18, 2018
.eslintrc.js Update eslintrc Mar 4, 2019
.gitignore
.prettierrc.js Update prettierrc Mar 4, 2019
.travis.yml
CHANGELOG.md
LICENSE Upgrade license 2018 -> 2019 Feb 3, 2019
README.md
ava.config.js
gulpfile.js Do not use Babel with Gulp tasks Feb 27, 2019
package-lock.json
package.json Update published files Mar 19, 2019

README.md

Codecov Travis Node Gitter

Swiss Army knife for Unix permissions.

Unix file permissions can take many shapes: symbolic (ug+rw), octal (660) or a list of characters (drw-rw----). This library enables using any of these (instead of being limited to a single one) with any Node.js or CLI command.

This library can also perform operations on Unix permissions such as:

  • testing, setting and unsetting. Using bitwise operations (|, &, ^, ~) can be tedious and error-prone otherwise.
  • validating syntax.
  • normalizing. For example u+r,u+w can be shortened to u+rw.
  • inverting. For example a umask of 117 means new files will be created with 661 permissions.
  • checking the minimal or maximal permissions among a list of them. This can be useful to aggregate all the permissions of several files, e.g. during a directory recursion.

Permissions are manipulated as strings, not as file paths. This means you must use other utilities (such as chmod or stat) to get and set file permissions using those strings.

Examples

In JavaScript:

// Retrieve a file's permission as an object like
// `{ user: { write: false, read: true, ... }, ... }` instead of a number
convert.object(fs.statSync('/etc/passwd').mode)

// Set a file's permission using `symbolic` notation instead of a number
fs.chmod('/etc/passwd', convert.number('a=r'))

// Set a file's permission using `symbolic` notation instead of a number
fs.writeFile('/my/file', content, { mode: convert.number('a=r') })

// Disallow executing new files using `umask`
process.umask(convert.number(invert('a-x')))

// If your library takes Unix permissions as input, using
// `unix-permissions` under the hood lets your users choose their
// favorite Unix permissions type.
myLibrary.method({ mode: 'a-wx' })
myLibrary.method({ mode: '444' })

On the command line:

$ stat -c "%a" /etc/passwd
644

$ unix-permissions convert.symbolic "$(stat -c "%a" /etc/passwd)"
u=rw,go=r

Demo

You can try this library either:

Install

npm install unix-permissions

Usage (JavaScript)

const { convert } = require('unix-permissions')

// `permission` will be set to `rw-rw----`
const permission = convert.stat('660')

Several methods other than convert are available but they mostly follow the same pattern. Permission strings are passed as input and returned as output.

Usage (CLI)

$ unix-permissions convert.stat 660
rw-rw----

The same methods as in JavaScript are available. Exit code will be 1 if an error occurred, e.g. if the permission syntax is invalid.

Types

You can use any of the following permission types as input. You can also convert() between them:

  • octal strings like "422"
  • decimal number like 274
  • stat like rw-rw-r--
  • symbolic like a+rw
  • object like { user: { read: true, write: false, execute: false }, group: { write: false }, others: { write: false } }

Special permissions (setuid, setgid, sticky) can be used.

Please see the types full documentation.

Methods

convert.octal|number|stat|symbolic|object(permission)

Convert permission to another type.
Full documentation.

type(permission)

Returns the permission's type or invalid.
Full documentation.

normalize(permission)

Normalize a permission to its canonical shape. Throw if permission is invalid.
Full documentation.

positive(permission)

Remove all negative permissions.
Full documentation.

contain(permission, permissions...)

Tests whether permission includes permissions.
Full documentation.

equal(permission, permissions...)

Tests whether permission equals exactly permissions.
Full documentation.

set(permission, permissions...)

Set permissions on permission. This is useful to avoid error-prone bitwise operations (|, &, ^, ~).
Full documentation.

not(permission)

Inverts permission including special permissions. This can be used in combination with set() to unset permissions instead of setting them.
Full documentation.

invert(permission)

Inverts permission and removes special permissions.
Full documentation.

min(permissions...)

Retrieve the lowest permissions among all arguments.
Full documentation.

max(permissions...)

Retrieve the highest permissions among all arguments.
Full documentation.

Contributors

ehmicky
ehmicky

💻 🎨 🤔 📖
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.