3 * Copyright(c) 2014-2017 Douglas Christopher Wilson
14 module.exports = contentDisposition
15 module.exports.parse = parse
18 * Module dependencies.
22 var basename = require('path').basename
23 var Buffer = require('safe-buffer').Buffer
26 * RegExp to match non attr-char, *after* encodeURIComponent (i.e. not including "%")
30 var ENCODE_URL_ATTR_CHAR_REGEXP = /[\x00-\x20"'()*,/:;<=>?@[\\\]{}\x7f]/g // eslint-disable-line no-control-regex
33 * RegExp to match percent encoding escape.
37 var HEX_ESCAPE_REGEXP = /%[0-9A-Fa-f]{2}/
38 var HEX_ESCAPE_REPLACE_REGEXP = /%([0-9A-Fa-f]{2})/g
41 * RegExp to match non-latin1 characters.
45 var NON_LATIN1_REGEXP = /[^\x20-\x7e\xa0-\xff]/g
48 * RegExp to match quoted-pair in RFC 2616
50 * quoted-pair = "\" CHAR
51 * CHAR = <any US-ASCII character (octets 0 - 127)>
55 var QESC_REGEXP = /\\([\u0000-\u007f])/g // eslint-disable-line no-control-regex
58 * RegExp to match chars that must be quoted-pair in RFC 2616
62 var QUOTE_REGEXP = /([\\"])/g
65 * RegExp for various RFC 2616 grammar
67 * parameter = token "=" ( token | quoted-string )
68 * token = 1*<any CHAR except CTLs or separators>
69 * separators = "(" | ")" | "<" | ">" | "@"
70 * | "," | ";" | ":" | "\" | <">
71 * | "/" | "[" | "]" | "?" | "="
72 * | "{" | "}" | SP | HT
73 * quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
74 * qdtext = <any TEXT except <">>
75 * quoted-pair = "\" CHAR
76 * CHAR = <any US-ASCII character (octets 0 - 127)>
77 * TEXT = <any OCTET except CTLs, but including LWS>
78 * LWS = [CRLF] 1*( SP | HT )
80 * CR = <US-ASCII CR, carriage return (13)>
81 * LF = <US-ASCII LF, linefeed (10)>
82 * SP = <US-ASCII SP, space (32)>
83 * HT = <US-ASCII HT, horizontal-tab (9)>
84 * CTL = <any US-ASCII control character (octets 0 - 31) and DEL (127)>
85 * OCTET = <any 8-bit sequence of data>
89 var PARAM_REGEXP = /;[\x09\x20]*([!#$%&'*+.0-9A-Z^_`a-z|~-]+)[\x09\x20]*=[\x09\x20]*("(?:[\x20!\x23-\x5b\x5d-\x7e\x80-\xff]|\\[\x20-\x7e])*"|[!#$%&'*+.0-9A-Z^_`a-z|~-]+)[\x09\x20]*/g // eslint-disable-line no-control-regex
90 var TEXT_REGEXP = /^[\x20-\x7e\x80-\xff]+$/
91 var TOKEN_REGEXP = /^[!#$%&'*+.0-9A-Z^_`a-z|~-]+$/
94 * RegExp for various RFC 5987 grammar
96 * ext-value = charset "'" [ language ] "'" value-chars
97 * charset = "UTF-8" / "ISO-8859-1" / mime-charset
98 * mime-charset = 1*mime-charsetc
99 * mime-charsetc = ALPHA / DIGIT
100 * / "!" / "#" / "$" / "%" / "&"
101 * / "+" / "-" / "^" / "_" / "`"
103 * language = ( 2*3ALPHA [ extlang ] )
106 * extlang = *3( "-" 3ALPHA )
107 * value-chars = *( pct-encoded / attr-char )
108 * pct-encoded = "%" HEXDIG HEXDIG
109 * attr-char = ALPHA / DIGIT
110 * / "!" / "#" / "$" / "&" / "+" / "-" / "."
111 * / "^" / "_" / "`" / "|" / "~"
115 var EXT_VALUE_REGEXP = /^([A-Za-z0-9!#$%&+\-^_`{}~]+)'(?:[A-Za-z]{2,3}(?:-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8}|)'((?:%[0-9A-Fa-f]{2}|[A-Za-z0-9!#$&+.^_`|~-])+)$/
118 * RegExp for various RFC 6266 grammar
120 * disposition-type = "inline" | "attachment" | disp-ext-type
121 * disp-ext-type = token
122 * disposition-parm = filename-parm | disp-ext-parm
123 * filename-parm = "filename" "=" value
124 * | "filename*" "=" ext-value
125 * disp-ext-parm = token "=" value
126 * | ext-token "=" ext-value
127 * ext-token = <the characters in token, followed by "*">
131 var DISPOSITION_TYPE_REGEXP = /^([!#$%&'*+.0-9A-Z^_`a-z|~-]+)[\x09\x20]*(?:$|;)/ // eslint-disable-line no-control-regex
134 * Create an attachment Content-Disposition header.
136 * @param {string} [filename]
137 * @param {object} [options]
138 * @param {string} [options.type=attachment]
139 * @param {string|boolean} [options.fallback=true]
144 function contentDisposition (filename, options) {
145 var opts = options || {}
148 var type = opts.type || 'attachment'
151 var params = createparams(filename, opts.fallback)
153 // format into string
154 return format(new ContentDisposition(type, params))
158 * Create parameters object from filename and fallback.
160 * @param {string} [filename]
161 * @param {string|boolean} [fallback=true]
166 function createparams (filename, fallback) {
167 if (filename === undefined) {
173 if (typeof filename !== 'string') {
174 throw new TypeError('filename must be a string')
177 // fallback defaults to true
178 if (fallback === undefined) {
182 if (typeof fallback !== 'string' && typeof fallback !== 'boolean') {
183 throw new TypeError('fallback must be a string or boolean')
186 if (typeof fallback === 'string' && NON_LATIN1_REGEXP.test(fallback)) {
187 throw new TypeError('fallback must be ISO-8859-1 string')
190 // restrict to file base name
191 var name = basename(filename)
193 // determine if name is suitable for quoted string
194 var isQuotedString = TEXT_REGEXP.test(name)
196 // generate fallback name
197 var fallbackName = typeof fallback !== 'string'
198 ? fallback && getlatin1(name)
200 var hasFallback = typeof fallbackName === 'string' && fallbackName !== name
202 // set extended filename parameter
203 if (hasFallback || !isQuotedString || HEX_ESCAPE_REGEXP.test(name)) {
204 params['filename*'] = name
207 // set filename parameter
208 if (isQuotedString || hasFallback) {
209 params.filename = hasFallback
218 * Format object to Content-Disposition header.
220 * @param {object} obj
221 * @param {string} obj.type
222 * @param {object} [obj.parameters]
227 function format (obj) {
228 var parameters = obj.parameters
231 if (!type || typeof type !== 'string' || !TOKEN_REGEXP.test(type)) {
232 throw new TypeError('invalid type')
235 // start with normalized type
236 var string = String(type).toLowerCase()
239 if (parameters && typeof parameters === 'object') {
241 var params = Object.keys(parameters).sort()
243 for (var i = 0; i < params.length; i++) {
246 var val = param.substr(-1) === '*'
247 ? ustring(parameters[param])
248 : qstring(parameters[param])
250 string += '; ' + param + '=' + val
258 * Decode a RFC 6987 field value (gracefully).
260 * @param {string} str
265 function decodefield (str) {
266 var match = EXT_VALUE_REGEXP.exec(str)
269 throw new TypeError('invalid extended field value')
272 var charset = match[1].toLowerCase()
273 var encoded = match[2]
277 var binary = encoded.replace(HEX_ESCAPE_REPLACE_REGEXP, pdecode)
281 value = getlatin1(binary)
284 value = Buffer.from(binary, 'binary').toString('utf8')
287 throw new TypeError('unsupported charset in extended field')
294 * Get ISO-8859-1 version of string.
296 * @param {string} val
301 function getlatin1 (val) {
302 // simple Unicode -> ISO-8859-1 transformation
303 return String(val).replace(NON_LATIN1_REGEXP, '?')
307 * Parse Content-Disposition header string.
309 * @param {string} string
314 function parse (string) {
315 if (!string || typeof string !== 'string') {
316 throw new TypeError('argument string is required')
319 var match = DISPOSITION_TYPE_REGEXP.exec(string)
322 throw new TypeError('invalid type format')
326 var index = match[0].length
327 var type = match[1].toLowerCase()
334 // calculate index to start at
335 index = PARAM_REGEXP.lastIndex = match[0].substr(-1) === ';'
340 while ((match = PARAM_REGEXP.exec(string))) {
341 if (match.index !== index) {
342 throw new TypeError('invalid parameter format')
345 index += match[0].length
346 key = match[1].toLowerCase()
349 if (names.indexOf(key) !== -1) {
350 throw new TypeError('invalid duplicate parameter')
355 if (key.indexOf('*') + 1 === key.length) {
356 // decode extended value
357 key = key.slice(0, -1)
358 value = decodefield(value)
360 // overwrite existing value
365 if (typeof params[key] === 'string') {
369 if (value[0] === '"') {
370 // remove quotes and escapes
372 .substr(1, value.length - 2)
373 .replace(QESC_REGEXP, '$1')
379 if (index !== -1 && index !== string.length) {
380 throw new TypeError('invalid parameter format')
383 return new ContentDisposition(type, params)
387 * Percent decode a single character.
389 * @param {string} str
390 * @param {string} hex
395 function pdecode (str, hex) {
396 return String.fromCharCode(parseInt(hex, 16))
400 * Percent encode a single character.
402 * @param {string} char
407 function pencode (char) {
408 return '%' + String(char)
415 * Quote a string for HTTP.
417 * @param {string} val
422 function qstring (val) {
423 var str = String(val)
425 return '"' + str.replace(QUOTE_REGEXP, '\\$1') + '"'
429 * Encode a Unicode string for HTTP (RFC 5987).
431 * @param {string} val
436 function ustring (val) {
437 var str = String(val)
439 // percent encode as UTF-8
440 var encoded = encodeURIComponent(str)
441 .replace(ENCODE_URL_ATTR_CHAR_REGEXP, pencode)
443 return 'UTF-8\'\'' + encoded
447 * Class for parsed Content-Disposition header for v8 optimization
450 * @param {string} type
451 * @param {object} parameters
455 function ContentDisposition (type, parameters) {
457 this.parameters = parameters