ssri npm version license Travis AppVeyor Coverage Status

ssri, short for Standard Subresource Integrity, is a Node.js utility for parsing, manipulating, serializing, generating, and verifying Subresource Integrity hashes.

Install

$ npm install --save ssri

Table of Contents

Example

```javascript const ssri = require('ssri')

const integrity = 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo'

// Parsing and serializing const parsed = ssri.parse(integrity) ssri.stringify(parsed) // === integrity (works on non-Integrity objects) parsed.toString() // === integrity

// Async stream functions ssri.checkStream(fs.createReadStream('./my-file'), integrity).then(...) ssri.fromStream(fs.createReadStream('./my-file')).then(sri => { sri.toString() === integrity }) fs.createReadStream('./my-file').pipe(ssri.createCheckerStream(sri))

// Sync data functions ssri.fromData(fs.readFileSync('./my-file')) // === parsed ssri.checkData(fs.readFileSync('./my-file'), integrity) // => 'sha512' ```

Features

Contributing

The ssri team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! The Contributor Guide has all the information you need for everything from reporting bugs to contributing entire new features. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.

API

> ssri.parse(sri, [opts]) -> Integrity

Parses sri into an Integrity data structure. sri can be an integrity string, an Hash-like with digest and algorithm fields and an optional options field, or an Integrity-like object. The resulting object will be an Integrity instance that has this shape:

javascript { 'sha1': [{algorithm: 'sha1', digest: 'deadbeef', options: []}], 'sha512': [ {algorithm: 'sha512', digest: 'c0ffee', options: []}, {algorithm: 'sha512', digest: 'bad1dea', options: ['foo']} ], }

If opts.single is truthy, a single Hash object will be returned. That is, a single object that looks like {algorithm, digest, options}, as opposed to a larger object with multiple of these.

If opts.strict is truthy, the resulting object will be filtered such that it strictly follows the Subresource Integrity spec, throwing away any entries with any invalid components. This also means a restricted set of algorithms will be used -- the spec limits them to sha256, sha384, and sha512.

Strict mode is recommended if the integrity strings are intended for use in browsers, or in other situations where strict adherence to the spec is needed.

Example

javascript ssri.parse('sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo') // -> Integrity object

> ssri.stringify(sri, [opts]) -> String

This function is identical to Integrity#toString(), except it can be used on any object that parse can handle -- that is, a string, an Hash-like, or an Integrity-like.

The opts.sep option defines the string to use when joining multiple entries together. To be spec-compliant, this must be whitespace. The default is a single space (' ').

If opts.strict is true, the integrity string will be created using strict parsing rules. See ssri.parse.

Example

```javascript // Useful for cleaning up input SRI strings: ssri.stringify('\n\rsha512-foo\n\t\tsha384-bar') // -> 'sha512-foo sha384-bar'

// Hash-like: only a single entry. ssri.stringify({ algorithm: 'sha512', digest:'9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==', options: ['foo'] }) // -> // 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo'

// Integrity-like: full multi-entry syntax. Similar to output of ssri.parse ssri.stringify({ 'sha512': [ { algorithm: 'sha512', digest:'9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==', options: ['foo'] } ] }) // -> // 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo' ```

> Integrity#concat(otherIntegrity, [opts]) -> Integrity

Concatenates an Integrity object with another IntegrityLike, or an integrity string.

This is functionally equivalent to concatenating the string format of both integrity arguments, and calling ssri.parse on the new string.

If opts.strict is true, the new Integrity will be created using strict parsing rules. See ssri.parse.

Example

``javascript // This will combine the integrity checks for two different versions of // your index.js file so you can use a single integrity string and serve // either of these to clients, from a single