Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
188 lines (126 sloc) 6.99 KB

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 (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' })

Please see the examples directory for more JavaScript examples.

Examples (CLI)

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

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

Please see the examples directory for more CLI examples.

Playground

You can try this library directly from your browser here.

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

Please see the methods full documentation for more information and examples.

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

Convert permission to another type.

type(permission)

Returns the permission's type or invalid.

normalize(permission)

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

positive(permission)

Remove all negative permissions.

contain(permission, permissions...)

Tests whether permission includes permissions.

equal(permission, permissions...)

Tests whether permission equals exactly permissions.

set(permission, permissions...)

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

not(permission)

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

invert(permission)

Inverts permission and removes special permissions.

min(permissions...)

Retrieve the lowest permissions among all arguments.

max(permissions...)

Retrieve the highest permissions among all arguments.

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.