diff --git a/lib/constants.js b/lib/constants.js index d286b9f..cf81260 100644 --- a/lib/constants.js +++ b/lib/constants.js @@ -1,70 +1,100 @@ /** @constant */ export const DEFAULT_HEADERS = { - // Ensures that the page can't be displayed in a frame, - // regardless of where the request came from. - // It's a security feature to prevent "clickjacking" attacks, - // where an attacker might use an iframe to overlay a legitimate page over a deceptive page. + /** + * Ensures that the page can’t be displayed in a frame, + * regardless of where the request came from. + * It’s a security feature to prevent “clickjacking” attacks, + * where an attacker might use an iframe to overlay a legitimate page over a + * deceptive page. + */ 'X-Frame-Options': 'deny', - // The browser should enable the XSS filter and if a XSS attack is detected, - // rather than sanitizing the page, the browser will prevent rendering of the page entirely. + /** + * The browser should enable the XSS filter and if a XSS attack is detected, + * rather than sanitizing the page, the browser will prevent rendering of the + * page entirely. + */ 'X-XSS-Protection': '1; mode=block', - // Trust what the server says and not to perform MIME type sniffing. - // This can prevent certain security risks where the browser might interpret - // files as a different MIME type, which can be exploited in attacks. + /** + * Trust what the server says and not to perform MIME type sniffing. + * This can prevent certain security risks where the browser might interpret + * files as a different MIME type, which can be exploited in attacks. + */ 'X-Content-Type-Options': 'nosniff', - // By default, do not load content from any source (default-src 'none'). - // Images can be loaded from data: URLs (like Base64 encoded images). - // Styles can be loaded inline (style-src 'unsafe-inline'), - // which usually means from within the HTML itself rather than from external files. + /** + * By default, do not load content from any source (`default-src 'none'`), + * images can be loaded from `data:` URLs (like Base64 encoded images), + * and styles can be loaded inline (`style-src 'unsafe-inline'`), + * which usually means from within the HTML itself rather than from external + * files. + */ 'Content-Security-Policy': "default-src 'none'; img-src data:; style-src 'unsafe-inline'", - // This header is often called HSTS (HTTP Strict Transport Security). - // It's a security feature that ensures a website can only be accessed over HTTPS instead of HTTP. - // The max-age parameter specifies how long (in seconds) the browser should remember to enforce this policy. - // The includeSubDomains directive extends this rule to all subdomains of the domain sending the header. - // This ensures that even if a user tries to access the site or its subdomains via HTTP, - // their browser will automatically upgrade the request to HTTPS. + /** + * This header is often called HSTS (HTTP Strict Transport Security). + * It’s a security feature that ensures a website can only be accessed over + * HTTPS instead of HTTP. + * The `max-age` parameter specifies how long (in seconds) the browser should + * remember to enforce this policy. + * The `includeSubDomains` directive extends this rule to all subdomains of + * the domain sending the header. + * This ensures that even if a user tries to access the site or its + * subdomains via HTTP, + * their browser will automatically upgrade the request to HTTPS. + */ 'Strict-Transport-Security': 'max-age=31536000; includeSubDomains' } /** - * http request headers that are acceptable to pass from - * the client to the remote server. Only those present and true, are forwarded. - * @constant + * HTTP request headers that are acceptable to pass from the client to the + * remote server. + * Only those present and true are forwarded. + * + * @type {Readonly>} */ export const REQUEST_HEADERS = new Map([ ['Accept', true], ['Accept-Charset', true], - ['Accept-Encoding', false], // images (aside from xml/svg), don't typically benefit from compression + // No `Accept-Encoding` because images (other than from XML or SVG), don’t + // typically benefit from compression: + ['Accept-Encoding', false], ['Accept-Language', true], ['Cache-Control', true], ['If-None-Match', true], ['If-Modified-Since', true], - ['X-Forwarded-For', false], // x-forwarded-for header is not blindly passed without additional custom processing - ['Range', true] // required to support safari byte range requests for video + // `Range` is used by Safari for byte range requests on video: + ['Range', true], + // No `X-Forwarded-For` because ??? + ['X-Forwarded-For', false] ]) /** - * http response headers that are acceptable to pass from - * the remote server to the client. Only those present and true, are forwarded. - * @constant + * HTTP response headers that are acceptable to pass from the remote server to + * the client. + * Only those present and true are forwarded. + * + * @type {Readonly>} */ export const RESPONSE_HEADERS = new Map([ - ['Accept-Ranges', true], // required to support Safari byte range requests for video - ['Content-Length', true], - ['Content-Range', true], - + // `Accept-Ranges` is used by Safari for byte range requests on video: + ['Accept-Ranges', true], ['Cache-Control', true], + ['Content-Length', true], ['Content-Encoding', true], + ['Content-Range', true], ['Content-Type', true], ['ETag', true], ['Expires', true], ['Last-Modified', true], - ['Server', false], // override in response with either nothing, or ServerNameVer + // `Server` is disallowed because ??? + ['Server', false], ['Transfer-Encoding', true] ]) -/** @constant */ +/** + * MIME types that we allow. + * + * @type {ReadonlyArray} + */ export const IMAGE_MIME_TYPES = [ 'image/bmp', 'image/cgm',