http-referrer-policy 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# HTTP Referrer Policy
+[![npm version](https://img.shields.io/npm/v/http-referrer-policy.svg?style=flat-square)](https://npmjs.com/package/http-referrer-policy)
+[![npm license](https://img.shields.io/npm/l/http-referrer-policy.svg?style=flat-square)](https://npmjs.com/package/http-referrer-policy)
+[![npm downloads](https://img.shields.io/npm/dm/http-referrer-policy.svg?style=flat-square)](https://npmjs.com/package/http-referrer-policy)
+
+## Installation
+
+```
+npm install --save http-referrer-policy
+```
+
+## Usage
+
+```js
+const referrerPolicy = require( 'http-referrer-policy' )
+```
+
+```js
+import referrerPolicy from 'http-referrer-policy'
+```
+
+## API
+
+### Constants
+
+- readonly string `referrerPolicy.default` - Default policy directive ('strict-origin-when-cross-origin')
+- readonly array\<string\> `referrerPolicy.directives` - List of supported referrer policy directives
+
+### Methods
+
+#### `referrerPolicy.select( directives, fallback )`
+
+Select the most restrictive policy from a given `Referrer-Policy` value,
+returning the fallback policy if no value is given or selected.
+If no fallback policy is given, `referrerPolicy.default` is returned.
+
+- string `directives`: `Referrer-Policy` header field value
+- string `fallback`: Optional. Fallback policy directive.
+
+Returns `string`
+
+#### `referrerPolicy.url( from, to, directives, fallback )`
+
+Constructs the value of a `Referer` header based on
+the policy directive and navigation endpoint URLs.
+
+- string|URL `from`: Current (referring) URL.
+- string|URL `to`: URL being navigated to.
+- string `directives`: `Referer-Policy` directive.
+- string `fallback`: Optional. Fallback policy directive.
+
+Returns `string`
+
+## Resources
+
+- Specification: [W3C / webappsec-referrer-policy](https://w3c.github.io/webappsec-referrer-policy/#referrer-policies)
+- MDN: [Headers / Referrer-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy)

package/lib/referrer-policy.js

@@ -0,0 +1,152 @@
+const policyDirectives = [
+  'no-referrer',
+  'no-referrer-when-downgrade',
+  'same-origin',
+  'origin',
+  'strict-origin',
+  'origin-when-cross-origin',
+  'strict-origin-when-cross-origin',
+  'unsafe-url',
+]
+
+function _isDowngrade( ref, dst ) {
+  switch( ref.protocol ) {
+    case 'https:': return dst.protocol != 'https:' && dst.protocol != 'wss:'
+    case 'wss:': return dst.protocol != 'https:' && dst.protocol != 'wss:'
+    default: return false
+  }
+}
+
+class ReferrerPolicy {
+
+  /**
+   * The default referrer policy as per specification is 'strict-origin-when-cross-origin'.
+   * @see https://w3c.github.io/webappsec-referrer-policy/#referrer-policies
+   * @type {String}
+   */
+  static get default() { return 'strict-origin-when-cross-origin' }
+
+  /**
+   * Set of supported directives
+   * @type {Array<String>}
+   */
+  static directives = policyDirectives.slice()
+
+  /**
+   * Select the most restrictive policy from a given `Referrer-Policy` value,
+   * using the fallback policy if no policy is resolved.
+   * If no fallback policy is given, `ReferrerPolicy.default` is used.
+   * @param {String|null} value
+   * @param {String} [fallback]
+   * @returns {String}
+   */
+  static select( value, fallback ) {
+
+    if( fallback != null && typeof fallback != 'string' ) {
+      throw new TypeError( 'Referrer-policy fallback must be a string' )
+    }
+
+    // The empty string "" corresponds to no referrer policy, causing a fallback to a
+    // referrer policy defined elsewhere, or in the case where no such higher-level
+    // policy is available, falling back to the default referrer policy.
+    if( value == null || value == '' ) {
+      return fallback || ReferrerPolicy.default
+    }
+
+    if( typeof value != 'string' ) {
+      throw new TypeError( 'Referrer-policy must be a string' )
+    }
+
+    var directives = value.split( /\s*,\s*/g )
+    var selected = ''
+
+    // Multiple fallback policies can be specified in the Referrer-Policy header,
+    // with increasing preference; the first policy being the least desired.
+    for( let directive of directives ) {
+      directive = directive.trim().toLowerCase()
+      // Use this directive, if we understand it
+      if( policyDirectives.includes( directive ) ) {
+        selected = directive
+      }
+    }
+
+    return selected || fallback || ReferrerPolicy.default
+
+  }
+
+  /**
+   * Construct the value of a `Referer` header based on
+   * the policy directive and navigation endpoint URLs.
+   * @param {String|URL} from - Current URL
+   * @param {String|URL} to - Destination URL
+   * @param {String} [value] - Referrer-Policy header value
+   * @param {String} [fallback] - Fallback policy directive
+   * @returns {String}
+   */
+  static url( from, to, value, fallback ) {
+
+    const directive = ReferrerPolicy.select( value, fallback )
+
+    // Do not include any referrer information
+    if( directive == 'no-referrer' ) return '';
+
+    var ref = new URL( from )
+    var dst = new URL( to )
+
+    // Always strip auth
+    ref.username = ''
+    ref.password = ''
+
+    var isSameOrigin = ref.origin == dst.origin
+    var isDowngrade = _isDowngrade( ref, dst )
+
+    switch( directive ) {
+
+      // Send only the origin in the `Referer` header.
+      case 'origin':
+        return ref.origin
+
+      // Send only the origin when the protocol security level stays the same (HTTPS->HTTPS).
+      // Don't send the `Referer` header to less secure destinations (HTTPS->HTTP).
+      case 'strict-origin':
+        return ref.protocol == dst.protocol ? ref.origin : ''
+
+      // Send the origin, path, and query string for same-origin requests.
+      // Don't send the `Referer` header for cross-origin requests.
+      case 'same-origin':
+        return isSameOrigin ? ref.toString() : ''
+
+      // When performing a same-origin request to the same protocol level
+      // (HTTP->HTTP, HTTPS->HTTPS), send the origin, path, and query string.
+      // Send only the origin for cross origin requests and requests to
+      // less secure destinations (HTTPS->HTTP).
+      case 'origin-when-cross-origin':
+        return isSameOrigin ? ref.toString() : ref.origin
+
+      // Send the origin, path, and query string when performing a same-origin request.
+      // For cross-origin requests send the origin (only) when the protocol security level stays same (HTTPS->HTTPS).
+      // Don't send the `Referer` header to less secure destinations (HTTPS->HTTP).
+      case 'strict-origin-when-cross-origin':
+        return isSameOrigin ? ref.toString() : ( !isDowngrade ? ref.origin : '' )
+
+      // Send the origin, path, and query string in `Referer` when the protocol
+      // security level stays the same or improves.
+      case 'no-referrer-when-downgrade':
+        return !isDowngrade ? ref.toString() : ''
+
+      // Send the origin, path, and query string when
+      // performing any request, regardless of security.
+      case 'unsafe-url':
+        return ref.toString()
+
+      default:
+        throw new Error( 'Invalid or unsupported referrer policy' )
+
+    }
+
+  }
+
+}
+
+export default ReferrerPolicy
+export { ReferrerPolicy as 'module.exports' }

package/package.json

@@ -0,0 +1,21 @@
+{
+  "type": "module",
+  "name": "http-referrer-policy",
+  "description": "HTTP Referrer-Policy",
+  "version": "1.0.0",
+  "main": "lib/referrer-policy.js",
+  "homepage": "https://codeberg.org/jhermsmeier/node-http-referrer-policy",
+  "bugs": {
+    "url": "https://codeberg.org/jhermsmeier/node-http-referrer-policy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/jhermsmeier/node-http-referrer-policy.git"
+  },
+  "scripts": {
+    "test": "control"
+  },
+  "devDependencies": {
+    "@jhermsmeier/control": "2.0.4"
+  }
+}