0
# Parsing & Serialization
1

2
Core functionality for parsing SRI strings into structured objects and serializing them back to standard format. Essential for working with existing integrity metadata from browsers, package managers, and other systems.
3

4
## Capabilities
5

6
### Parse Function
7

8
Parses integrity strings or objects into structured Integrity instances for programmatic manipulation.
9

10
```javascript { .api }
11
/**
12
 * Parses sri into an Integrity data structure
13
 * @param {string|object} sri - SRI string, Hash-like object, or Integrity-like object
14
 * @param {object} opts - Optional configuration
15
 * @param {boolean} opts.single - Return single Hash instead of Integrity
16
 * @param {boolean} opts.strict - Use strict SRI spec compliance
17
 * @returns {Integrity|Hash|null} Parsed integrity object or null if invalid
18
 */
19
function parse(sri, opts);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const ssri = require('ssri');
26

27
// Parse basic integrity string
28
const integrity = ssri.parse('sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==');
29
console.log(integrity.sha512[0].algorithm); // 'sha512'
30

31
// Parse with options
32
const hash = ssri.parse('sha256-abcd1234?foo', { single: true });
33
console.log(hash.options); // ['foo']
34

35
// Parse multiple algorithms
36
const multiAlgo = ssri.parse('sha256-abc sha512-def');
37
console.log(Object.keys(multiAlgo)); // ['sha256', 'sha512']
38

39
// Strict mode (browser compatibility)
40
const strict = ssri.parse('md5-invalid sha512-valid', { strict: true });
41
// Only includes sha512 hash (md5 not in SPEC_ALGORITHMS)
42
```
43

44
### Stringify Function
45

46
Converts integrity-like objects to standard SRI string representation.
47

48
```javascript { .api }
49
/**
50
 * Converts integrity object to string representation
51
 * @param {string|object} obj - Hash, Integrity, or string to stringify
52
 * @param {object} opts - Optional configuration
53
 * @param {string} opts.sep - Separator for multiple entries (default: ' ')
54
 * @param {boolean} opts.strict - Use strict parsing rules
55
 * @returns {string} SRI string representation
56
 */
57
function stringify(obj, opts);
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const ssri = require('ssri');
64

65
// Stringify Hash-like object
66
const hashLike = {
67
  algorithm: 'sha512',
68
  digest: '9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==',
69
  options: ['foo']
70
};
71
console.log(ssri.stringify(hashLike));
72
// -> 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo'
73

74
// Stringify Integrity-like object
75
const integrityLike = {
76
  'sha512': [{
77
    algorithm: 'sha512',
78
    digest: '9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==',
79
    options: []
80
  }]
81
};
82
console.log(ssri.stringify(integrityLike));
83

84
// Custom separator
85
console.log(ssri.stringify(multiIntegrity, { sep: '\n' }));
86
// Multi-line output
87

88
// Clean up malformed input
89
console.log(ssri.stringify('\n\rsha512-foo\n\t\tsha384-bar'));
90
// -> 'sha512-foo sha384-bar'
91
```
92

93
### Hash Class Methods
94

95
Individual hash manipulation and serialization methods.
96

97
```javascript { .api }
98
/**
99
 * Hash class representing a single integrity hash
100
 */
101
class Hash {
102
  /**
103
   * Creates a hash from string representation
104
   * @param {string} hash - Hash string to parse
105
   * @param {object} opts - Parsing options
106
   */
107
  constructor(hash, opts);
108

109
  /**
110
   * Returns hex representation of the digest
111
   * @returns {string} Hex-encoded digest
112
   */
113
  hexDigest();
114

115
  /**
116
   * Serializes hash to string format
117
   * @param {object} opts - Stringification options
118
   * @param {boolean} opts.strict - Use strict spec compliance
119
   * @returns {string} Hash string representation
120
   */
121
  toString(opts);
122

123
  /**
124
   * JSON serialization (calls toString)
125
   * @returns {string} String representation for JSON
126
   */
127
  toJSON();
128

129
  /**
130
   * Checks if this hash matches another integrity value
131
   * @param {string|object} integrity - Integrity to match against
132
   * @param {object} opts - Matching options
133
   * @returns {Hash|false} Matching hash or false
134
   */
135
  match(integrity, opts);
136
}
137
```
138

139
### Integrity Class Methods
140

141
Multi-hash container manipulation and serialization methods.
142

143
```javascript { .api }
144
/**
145
 * Integrity class representing multiple hashes organized by algorithm
146
 */
147
class Integrity {
148
  /**
149
   * Serializes integrity to string format
150
   * @param {object} opts - Stringification options
151
   * @param {string} opts.sep - Separator for multiple entries
152
   * @param {boolean} opts.strict - Use strict spec compliance
153
   * @returns {string} Integrity string representation
154
   */
155
  toString(opts);
156

157
  /**
158
   * JSON serialization (calls toString)
159
   * @returns {string} String representation for JSON
160
   */
161
  toJSON();
162

163
  /**
164
   * Checks if integrity object is empty
165
   * @returns {boolean} True if no hashes present
166
   */
167
  isEmpty();
168

169
  /**
170
   * Concatenates with another integrity value
171
   * @param {string|object} integrity - Integrity to concatenate
172
   * @param {object} opts - Concatenation options
173
   * @returns {Integrity} New combined integrity object
174
   */
175
  concat(integrity, opts);
176

177
  /**
178
   * Safely merges another integrity value
179
   * @param {string|object} integrity - Integrity to merge
180
   * @param {object} opts - Merge options
181
   * @throws {Error} If conflicting hashes for same algorithm
182
   */
183
  merge(integrity, opts);
184

185
  /**
186
   * Checks if integrity matches another value
187
   * @param {string|object} integrity - Integrity to match against
188
   * @param {object} opts - Matching options
189
   * @returns {Hash|false} Matching hash or false
190
   */
191
  match(integrity, opts);
192

193
  /**
194
   * Selects best algorithm from available hashes
195
   * @param {object} opts - Selection options
196
   * @param {function} opts.pickAlgorithm - Custom algorithm picker
197
   * @param {string[]} hashes - Limit to these algorithms
198
   * @returns {string|null} Selected algorithm or null
199
   */
200
  pickAlgorithm(opts, hashes);
201

202
  /**
203
   * Returns hex digest (assumes single-hash integrity)
204
   * @returns {string} Hex-encoded digest
205
   */
206
  hexDigest();
207
}
208
```
209

210
## Data Structures
211

212
### Parsed Integrity Structure
213

214
```javascript { .api }
215
// Example parsed integrity object structure:
216
{
217
  'sha1': [{
218
    source: 'sha1-deadbeef',
219
    algorithm: 'sha1',
220
    digest: 'deadbeef',
221
    options: []
222
  }],
223
  'sha512': [
224
    {
225
      source: 'sha512-c0ffee',
226
      algorithm: 'sha512', 
227
      digest: 'c0ffee',
228
      options: []
229
    },
230
    {
231
      source: 'sha512-bad1dea?foo',
232
      algorithm: 'sha512',
233
      digest: 'bad1dea', 
234
      options: ['foo']
235
    }
236
  ]
237
}
238
```
239

240
### Hash Properties
241

242
```javascript { .api }
243
interface Hash {
244
  source: string;      // Original hash string
245
  algorithm: string;   // Hash algorithm name
246
  digest: string;      // Base64 digest value
247
  options: string[];   // Array of option strings
248
  get isHash(): true;  // Type discriminator getter
249
}
250
```
251

252
### Integrity Properties
253

254
```javascript { .api }
255
interface Integrity {
256
  [algorithm: string]: Hash[];  // Hashes grouped by algorithm
257
  get isIntegrity(): true;     // Type discriminator getter
258
}
259
```
260

261
## Algorithm Support
262

263
### Standard Algorithms (Strict Mode)
264

265
```javascript { .api }
266
const SPEC_ALGORITHMS = ['sha512', 'sha384', 'sha256'];
267
```
268

269
### Extended Algorithms (Permissive Mode)
270

271
Any algorithm supported by Node.js crypto module when not in strict mode, including:
272
- sha1, sha224, sha256, sha384, sha512
273
- sha3-256, sha3-384, sha3-512
274
- md5 (not recommended for security)
275
- And others available via `crypto.getHashes()`
276

277
## Error Handling
278

279
Both `parse()` and `stringify()` are designed to be forgiving:
280

281
- `parse()` returns `null` for completely invalid input
282
- Invalid individual hashes within a string are silently skipped
283
- `stringify()` handles malformed input by cleaning and normalizing
284
- Strict mode filtering occurs without throwing errors
285

286
For more robust error handling, use verification functions which can throw detailed errors when configured with `{ error: true }`.