node_modules/basic-auth/README.md

   1 # basic-auth
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Node.js Version][node-version-image]][node-version-url]
   6 [![Build Status][travis-image]][travis-url]
   7 [![Test Coverage][coveralls-image]][coveralls-url]
   8
   9 Generic basic auth Authorization header field parser for whatever.
  10
  11 ## Installation
  12
  13 This is a [Node.js](https://nodejs.org/en/) module available through the
  14 [npm registry](https://www.npmjs.com/). Installation is done using the
  15 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  16
  17 ```
  18 $ npm install basic-auth
  19 ```
  20
  21 ## API
  22
  23 <!-- eslint-disable no-unused-vars -->
  24
  25 ```js
  26 var auth = require('basic-auth')
  27 ```
  28
  29 ### auth(req)
  30
  31 Get the basic auth credentials from the given request. The `Authorization`
  32 header is parsed and if the header is invalid, `undefined` is returned,
  33 otherwise an object with `name` and `pass` properties.
  34
  35 ### auth.parse(string)
  36
  37 Parse a basic auth authorization header string. This will return an object
  38 with `name` and `pass` properties, or `undefined` if the string is invalid.
  39
  40 ## Example
  41
  42 Pass a Node.js request object to the module export. If parsing fails
  43 `undefined` is returned, otherwise an object with `.name` and `.pass`.
  44
  45 <!-- eslint-disable no-unused-vars, no-undef -->
  46
  47 ```js
  48 var auth = require('basic-auth')
  49 var user = auth(req)
  50 // => { name: 'something', pass: 'whatever' }
  51 ```
  52
  53 A header string from any other location can also be parsed with
  54 `auth.parse`, for example a `Proxy-Authorization` header:
  55
  56 <!-- eslint-disable no-unused-vars, no-undef -->
  57
  58 ```js
  59 var auth = require('basic-auth')
  60 var user = auth.parse(req.getHeader('Proxy-Authorization'))
  61 ```
  62
  63 ### With vanilla node.js http server
  64
  65 ```js
  66 var http = require('http')
  67 var auth = require('basic-auth')
  68 var compare = require('tsscmp')
  69
  70 // Create server
  71 var server = http.createServer(function (req, res) {
  72   var credentials = auth(req)
  73
  74   // Check credentials
  75   // The "check" function will typically be against your user store
  76   if (!credentials || !check(credentials.name, credentials.pass)) {
  77     res.statusCode = 401
  78     res.setHeader('WWW-Authenticate', 'Basic realm="example"')
  79     res.end('Access denied')
  80   } else {
  81     res.end('Access granted')
  82   }
  83 })
  84
  85 // Basic function to validate credentials for example
  86 function check (name, pass) {
  87   var valid = true
  88
  89   // Simple method to prevent short-circut and use timing-safe compare
  90   valid = compare(name, 'john') && valid
  91   valid = compare(pass, 'secret') && valid
  92
  93   return valid
  94 }
  95
  96 // Listen
  97 server.listen(3000)
  98 ```
  99
 100 # License
 101
 102 [MIT](LICENSE)
 103
 104 [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/basic-auth/master
 105 [coveralls-url]: https://coveralls.io/r/jshttp/basic-auth?branch=master
 106 [downloads-image]: https://badgen.net/npm/dm/basic-auth
 107 [downloads-url]: https://npmjs.org/package/basic-auth
 108 [node-version-image]: https://badgen.net/npm/node/basic-auth
 109 [node-version-url]: https://nodejs.org/en/download
 110 [npm-image]: https://badgen.net/npm/v/basic-auth
 111 [npm-url]: https://npmjs.org/package/basic-auth
 112 [travis-image]: https://badgen.net/travis/jshttp/basic-auth/master
 113 [travis-url]: https://travis-ci.org/jshttp/basic-auth