assert-headers - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

bin/assert-headers/getConfiguration.js

 const { readFile } = require('fs')
 
-module.exports = function getConfiguration(configurationPath) {
+module.exports = function getConfiguration (configurationPath) {
   return new Promise((resolve, reject) => {
@@ -5,0 +5,0 @@ try {

bin/assert-headers/getConfiguration.spec.js

@@ -12,3 +12,3 @@ /* global describe, expect, test */
   })
-  
+
   test('rejects if the file can not be parsed', async () => {
@@ -15,0 +15,0 @@ await expect(getConfiguration(path.join(__dirname, './__fixtures__/badConfiguration.json')))

bin/assert-headers/index.js

@@ -9,3 +9,2 @@ #!/usr/bin/env node
 const pkg = require('../../package.json')
-const assertHeaders = require('../../lib/assertHeaders')
 
@@ -24,6 +23,6 @@ const EXIT_CODES = {
 
-let opts = {
+const opts = {
   configurationPath: path.join(process.cwd(), './headersSchema.json'),
   silentMode: false,
-  url: undefined,
+  url: undefined
 }
@@ -30,0 +29,0 @@

lib/fromUrl.js

@@ -8,3 +8,3 @@ const http = require('http')
 
-module.exports = function fromUrl(url, configuration) {
+module.exports = function fromUrl (url, configuration) {
   const {
@@ -11,0 +11,0 @@ origin = 'http://a.com',

lib/fromUrl.spec.js

@@ -12,3 +12,3 @@ /* global describe, expect, test */
       schema: {
-        'x-content-type-options': 'nosniff',
+        'x-content-type-options': 'nosniff'
       }
@@ -34,3 +34,3 @@ }
       schema: {
-        'x-content-type-options': 'nosniff',
+        'x-content-type-options': 'nosniff'
       }
@@ -57,3 +57,3 @@ }
       schema: {
-        'x-content-type-options': 'nosniff',
+        'x-content-type-options': 'nosniff'
       }
@@ -75,2 +75,2 @@ }
   })
-})
+})

package.json

 {
   "name": "assert-headers",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Assert HTTP headers",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

README.md

 # assert-headers-node
 
-Configuration:
+Assert HTTP headers
 
-- accept both json and yml, but mostly follow json schema syntax
-- use the "schema" parameter of the main object, so other configuration can be passed in down the road
-  - allow schema to exclude or error if header is present
-  - header can be required
-  - header allowed values can be listed
-  - header values can disallowed somehow
-- allow the user-agent to be defined here
-- alow the origin to be defined here
+## Usage
 
-Usage:
+### CLI
 
-- export a function that accepts (headers, schema)
-- export a method `fromUrl` (url, options) which will make a GET call using native APIs to retrieve the headers
-  - apply a standard user-agent
-  - bin script will call this method
-- bin script
-  - calls fromUrl method
-  - outputs to stdout the collective errors
-  - formats output similar to Mocha
-  - `--version` will show version number and platform (Node vs. Python)
-  - `--silent` to only exit with error codes:
-    - 0 - Success
-    - 1 - Uncaught error
-    - 2 - Assertion failed
-    - 3 - Configuration error
-- Document streaming a .csv to the CLI to get output without erring
+#### Global usage
+
+```bash
+npm i -g assert-headers
+# Assume headersSchema.json in current working directory
+assert-headers https://example.com
+```
+
+or with specified configuration
+
+```bash
+assert-headers --config ./customConfiguration.json https://example.com
+```
+
+or using npx
+
+```bash
+npx assert-headers https://example.com
+```
+
+in silent mode
+
+```bash
+npx assert-headers --silent --config ./customConfiguration.json https://example.com
+```
+
+to see what version you are running
+
+```bash
+assert-headers --version
+```
+
+##### Advanced CLI Usage
+
+TODO: Add example of how to stream a column of a .csv into the tool
+
+TODO: Show how the exit codes can be used in smoke tests
+
+#### CLI Configuration
+
+`assert-headers` currently accepts configuration in JSON format. It allows specifying a schema for the headers, but also the outgoing origin and user-agent headers for the request. Below is an example configuration:
+
+```json
+{
+  "user-agent": "assert-headers-node",
+  "origin": "https://example.com",
+  "schema": {
+    "cache-control": false,
+    "strict-transport-security": true,
+    "x-content-type-options": "nosniff",
+    "x-frame-options": {
+      "DENY": true,
+      "SAMEORIGIN": false
+    }
+  }
+}
+```
+
+TODO: Allow yml configuration
+
+**Schema Explanation:**
+
+1. `"disallowed-header-name": false` - It is considered an error if this header is defined
+1. `"required-header-name": true` - It is considered an error if this header is missing (or `undefined`)
+1. `"strict-header-name": "only good value"` - It is considered an error if this header does not have this value
+1. `"enumerated-header-name": { "good header value": true, "another good value": true }` - It is considered an error if this header contains a value other than one marked `true`.
+1. `"enumerated-header-name": { "bad header value": false, "another bad value": false }` - It is considered an error if this header contains a value not marked `true`
+1. If no enumerated header values are marked `true`, all listed values are considered invalid values. It is highly recommended to ONLY use `true` and `false` for enumerated values
+
+### assertHeader
+
+```js
+const assertHeader = require('assert-header')
+
+const headers = {
+  'strict-transport-security': 'max-age=31536000; includeSubDomains',
+  'x-content-type-options': 'nosniff',
+  'x-frame-options': 'DENY'
+}
+const schema = {
+  'cache-control': false,
+  'strict-transport-security': true,
+  'x-content-type-options': 'nosniff',
+  'x-frame-options': {
+    // if any are true, the header value must match a true schema value
+    DENY: true
+  }
+}
+
+try {
+  assertHeaders(headers, schema)
+} catch (err) {
+  console.error('OOPS!', err.message)
+  if (err.errors) {
+    err.errors.forEach((assertionError) => {
+      console.error(`The header ${assertionError.headerName} was bad!`)
+    })
+  }
+}
+```
+
+This can also be used inside a test library for validating HTTP response headers.
+
+### assertHeader.fromUrl
+
+```js
+const assertHeader = require('assert-header')
+
+(async () => {
+  const configuration {
+    'user-agent': 'Custom User Agent name',
+    origin: 'https://my-domain.com',
+    schema: {
+      'cache-control': false,
+      'strict-transport-security': true,
+      'x-content-type-options': 'nosniff',
+      'x-frame-options': {
+        // if any are true, the header value must match a true schema value
+        DENY: true
+      }
+    }
+  }
+
+  await assertHeader.fromUrl('https://example.com/my-test-page', configuration)
+})()
+```

No alert changes

Improved metrics

Total package byte prevSize

19061

increased by18.94%

Number of package files

17

increased by6.25%

Number of lines in readme file

135

increased by335.48%

No dependency changes