nsri (NodeJS Subresource Integrity)

General Info

Release Info

Development Info

---

A Node.js utility tool that creates an integrity object containing the hash checksums of a file or a directory structure, that can be saved to an .integrity.json file [], or put inside the project's manifest file (project.json).

The hashes are computed using, by default, the sha1 algorithm for files and sha512 algorithm for directories, with base64 encoding, complying to Subresource Integrity spec, but other Node.js crypto supported algorithms and encodings can be used.

Instalation

To install as a dependency, simply type:

npm i nsri --save

To install for global use, simply type:

npm i nsri -g

Behavior

NOTE:

• The .integrity.json file itself is being excluded in all computations.
• The node_modules, .git*, .svn*, .hg* directories are excluded by default.

Files

Hashes are the same when:

• File names and contents are the same

Hashes are different when:

• File names are different and contents are the same
• File contents are different and names are the same

Directories

Contents: The file names (and their data contents) and subdirectories names (with their contents) of the directory

Hashes are the same when:

• Directory names and contents are the same (strict: true)
• Only root directory names are different and subdirectory names and all contents are the same (strict: false)

Hashes are different when:

• Directory names are different and contents are the same (strict: true)
• Directory contents are different and names are the same

Usage

CLI

nsri has a built-in command-line inteface.

nsri <command> [options]

To see the available commands type:

nsri -h

and for available command options type:

nsri <command> -h

More info an be found at the CLI section.

API

nsri can also be used programatically (TypeScript types are included).

More info can be found at the API section.

Configuration

Config File

nsri supports cosmiconfig configuration.

Valid config filenames are: .nsrirc, .nsrirc.js, .nsrirc.json, .nsrirc.yaml, .nsrirc.yml, .nsrirc.config.js. In package.json the property name MUST be nsri.

NOTE: Configurations set via CLI are overriding configurations set via cosmiconfig. To avoid confusion use one or the other.

Ignore File

Exclusions also can be set via an ignore file (.nsriignore), which supports the gitignore pattern format.

NOTE: ExclusionsExclutionsExclutions set via CLI or cosmiconfig are getting merged with those in the ignore file and from those only unique entries are assigned.

Integrity object schema

{
  "version": ... schema version,
  "hashes": ... verbosely or non-verbosely computed hashes
}

More info on the used schema can be found here.

Verbosely hashes schema

{
  "directoryName": {
    "contents": {
      "aFileName":  ... file computed hash string,
      "anotherFileName":  ... file computed hash string
    },
    "hash": ... directory computed hash string
  }
}

Examples of a verbosely computed hash integrity file can be found here.

Non-verbosely hashes schema

{
  "fileOrDirectoryName": ... file or directory computed hash string
}

Examples

Examples on how to use nsri, via CLI or API, can be found at the examples section.

If you believe that the examples are incomplete or incorrect, please submit an issue or better yet a PR.

Contributing

If you like to contribute make sure to check-out the Contribution Guidelines section.

License

This project is licensed under the MIT license.

Versioning

This project follows Semantic Versioning 2.0.0.