diff --git a/README.md b/README.md index cf9cfa0..eaed9be 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) hashes. * [API](#api) * Parsing & Serializing * [`parse`](#parse) + * [`stringify`](#stringify) * [`Integrity#concat`](#integrity-concat) * [`Integrity#toString`](#integrity-to-string) - * [`serialize`](#serialize) * Integrity Generation * [`fromData`](#from-data) * [`fromStream`](#from-stream) @@ -36,8 +36,8 @@ const integrity = 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xp // Parsing and serializing const parsed = ssri.parse(integrity) +ssri.stringify(parsed) // === integrity (works on non-Integrity objects) parsed.toString() // === integrity -ssri.serialize(parsed) // === integrity (works on non-Integrity objects) // Async stream functions ssri.checkStream(fs.createReadStream('./my-file'), parsed).then(...) @@ -101,6 +101,49 @@ browsers, or in other situations where strict adherence to the spec is needed. ssri.parse('sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo') // -> Integrity ``` +#### `> ssri.stringify(sri, [opts]) -> String` + +This function is identical to [`Integrity#toString()`](#integrity-to-string), +except it can be used on _any_ object that [`parse`](#parse) can handle -- that +is, a string, an `IntegrityMetadata`-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`](#parse). + +##### Example + +```javascript +// Useful for cleaning up input SRI strings: +ssri.stringify('\n\rsha512-foo\n\t\tsha384-bar') +// -> 'sha512-foo sha384-bar' + +// IntegrityMetadata-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 a string @@ -133,7 +176,7 @@ Returns the string representation of an `Integrity` object. All metadata entries will be concatenated in the string by `opts.sep`, which defaults to `' '`. If you want to serialize an object that didn't from from an `ssri` function, -use [`ssri.serialize()`](#serialize). +use [`ssri.stringify()`](#stringify). If `opts.strict` is true, the integrity string will be created using strict parsing rules. See [`ssri.parse`](#parse). @@ -146,45 +189,6 @@ const integrity = 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xp ssri.parse(integrity).toString() === integrity ``` -#### `> ssri.serialize(sri, [opts]) -> String` - -This function is identical to [`Integrity#toString()`](#integrity-to-string), -except it can be used on _any_ object that [`parse`](#parse) can handle -- that -is, a string, an `IntegrityMetadata`-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`](#parse). - -##### Example - -```javascript -// IntegrityMetadata-like: only a single entry. -ssri.serialize({ - 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.serialize({ - 'sha512': [ - { - algorithm: 'sha512', - digest:'9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==', - options: ['foo'] - } - ] -}) -// -> -// 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo' -``` - #### `> ssri.fromData(data, [opts]) -> Integrity` Creates an `Integrity` object from either string or `Buffer` data, calculating diff --git a/index.js b/index.js index d8acfba..ce02993 100644 --- a/index.js +++ b/index.js @@ -74,7 +74,7 @@ class Integrity { concat (integrity, opts) { const other = typeof integrity === 'string' ? integrity - : serialize(integrity) + : stringify(integrity, opts) return parse(`${this.toString()} ${other}`, opts) } } @@ -87,9 +87,9 @@ function parse (sri, opts) { } else if (sri.algorithm && sri.digest) { const fullSri = new Integrity() fullSri[sri.algorithm] = [sri] - return _parse(serialize(fullSri, opts), opts) + return _parse(stringify(fullSri, opts), opts) } else { - return _parse(serialize(sri, opts), opts) + return _parse(stringify(sri, opts), opts) } } @@ -107,11 +107,12 @@ function _parse (integrity, opts) { }, new Integrity()) } -module.exports.serialize = serialize -module.exports.unparse = serialize -function serialize (obj, opts) { +module.exports.stringify = stringify +function stringify (obj, opts) { if (obj.algorithm && obj.digest) { return IntegrityMetadata.prototype.toString.call(obj, opts) + } else if (typeof obj === 'string') { + return stringify(parse(obj, opts), opts) } else { return Integrity.prototype.toString.call(obj, opts) }