hawk

What is hawk?

The 'hawk' npm package is a security-oriented library that provides HTTP authentication using the Hawk protocol. It is designed to help developers implement secure communication between clients and servers by ensuring message integrity and authenticity.

What are hawk's main functionalities?

Message Authentication

This feature allows you to generate an HTTP Authorization header for a request, ensuring that the request is authenticated and has not been tampered with. The code sample demonstrates how to create a Hawk client header using provided credentials.

const Hawk = require('hawk');

const credentials = {
  id: 'dh37fgj492je',
  key: 'aoijedoaijsdlaksjdl',
  algorithm: 'sha256'
};

const header = Hawk.client.header('http://example.com/resource/1?b=1&a=2', 'GET', { credentials: credentials, ext: 'some-app-data' });
console.log(header.field);

Server Authentication

This feature allows you to authenticate incoming HTTP requests on the server side. The code sample demonstrates how to set up a simple HTTP server that uses Hawk to authenticate requests.

const Hawk = require('hawk');

const credentialsFunc = function (id, callback) {
  const credentials = {
    id: id,
    key: 'aoijedoaijsdlaksjdl',
    algorithm: 'sha256'
  };
  return callback(null, credentials);
};

const server = require('http').createServer((req, res) => {
  Hawk.server.authenticate(req, credentialsFunc, {}, (err, credentials, artifacts) => {
    if (err) {
      res.writeHead(401);
      res.end('Unauthorized');
      return;
    }
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Hello ' + credentials.user);
  });
});

server.listen(8000);

Bewit (URL) Authentication

This feature allows you to generate a 'bewit' token for URL-based authentication. The code sample demonstrates how to create a bewit token that can be appended to a URL for temporary access.

const Hawk = require('hawk');

const credentials = {
  id: 'dh37fgj492je',
  key: 'aoijedoaijsdlaksjdl',
  algorithm: 'sha256'
};

const bewit = Hawk.uri.getBewit('http://example.com/resource/1?b=1&a=2', { credentials: credentials, ttlSec: 60 });
console.log(bewit);

Other packages similar to hawk

jsonwebtoken

The 'jsonwebtoken' package is used to sign and verify JSON Web Tokens (JWTs). It provides a way to securely transmit information between parties as a JSON object. Unlike Hawk, which focuses on message integrity and authentication, 'jsonwebtoken' is more about token-based authentication and authorization.

oauth2-server

The 'oauth2-server' package is a complete, framework-agnostic implementation of the OAuth2 server specification. It provides tools for implementing OAuth2 authorization flows, which is a more comprehensive and flexible approach to authentication and authorization compared to Hawk's simpler message authentication.

passport

The 'passport' package is a popular authentication middleware for Node.js. It supports a wide range of authentication strategies, including OAuth, OpenID, and JWT. While Hawk focuses on message authentication, 'passport' provides a more extensive set of tools for handling various authentication methods.

README

hawk

HTTP Holder-Of-Key Authentication Scheme.

Documentation of the protocol, and the JS API, is in https://github.com/mozilla/hawk/blob/main/API.md.

Ownership Changes

This was once hueniverse/hawk and relased as hawk. Then, after the 7.0.10 release, it was moved to the hapijs/hawk repository and released as @hapi/hawk. Hapi later de-supported the library, after releasing version 8.0.0. It has since been moved to mozilla/hawk and is again released as hawk. All of the intermediate versions are also relased as hawk.

Changes are represented in GitHub releases on this repository.

Mozilla maintains several Hawk implementations in different langauages, so it is likely to stay at Mozilla for some time.

This library is in "maintenance mode" -- no features will be added, and only security-related bugfixes will be applied.