HTTP Hawk Authentication Scheme

Common errors

• Error: Invalid credentials id

  cause The ID provided in the Hawk Authorization header does not match any known credentials on the server.
  fix Ensure the client is sending the correct `id` in its Hawk credentials that the server's `credentialsLookup` function can successfully resolve.

• 401 Authentication Required (WWW-Authenticate: Hawk)

  cause The server failed to authenticate the incoming Hawk request, often due to an invalid MAC, expired timestamp, or incorrect nonce.
  fix Check client-side clock synchronization, ensure credentials (id, key, algorithm) are correct, and verify that the request details (URI, method, payload) used for MAC generation precisely match the server's expectations. Look for 'mac' or 'timestamp' errors in server logs.

• TypeError: Cannot read properties of undefined (reading 'authenticate')

  cause Occurs when trying to use `Hawk.Server.authenticate` or `Hawk.Client.header` in a CommonJS (`require`) environment where the main `hawk` export might not directly expose `Client` or `Server` in a nested manner, or if the imports are incorrect for ESM.
  fix For ESM, use `import { Server, Client } from 'hawk';`. For CJS, ensure `const Hawk = require('hawk');` and then use `Hawk.Server.authenticate` or `Hawk.Client.header`. Alternatively, import specific modules like `require('hawk/server')` or `require('hawk/client')` if the package structure allows.

Warnings

• breaking Version 8.0.0 dropped support for Node.js versions older than 12 and Hapi framework versions older than 18. Ensure your environment meets these minimum requirements.
  Fix: Upgrade your Node.js runtime to version 12 or newer. If using Hapi, ensure it's version 18 or newer.
• breaking Version 7.1.0 removed browser exports. If you were using Hawk directly in a browser environment, this version will break your application. The library is primarily for server-side Node.js applications.
  Fix: For browser usage, consider alternative client-side authentication mechanisms or adapt your build process to bundle compatible older versions, though this is not recommended due to security implications.
• deprecated The `hawk` library is in 'maintenance mode' and version 9.0.2 is explicitly stated as the 'final release'. No new features will be added, and only security-related bug fixes will be applied. Users should plan for eventual migration if active development or new features are required.
  Fix: Evaluate alternative authentication schemes or Hawk implementations in other languages if long-term active development and feature additions are critical for your project.
• gotcha The package underwent several ownership and npm package name changes (from `hueniverse/hawk` to `@hapi/hawk` to `mozilla/hawk` published as `hawk`). Be mindful of which package version and name you are installing and importing to avoid compatibility issues.
  Fix: Always use `npm install hawk` and verify that the installed package's `package.json` points to the `mozilla/hawk` repository for the latest maintenance version.
• gotcha Version 9.0.0 dropped the requirement for `@hapi/sntp` for time synchronization. While this removes an unmaintained dependency, applications that relied on `sntp` for clock skew management may need to implement an alternative time synchronization workaround if strict clock synchronization is critical.
  Fix: If time synchronization is a critical component for your application's security, consider implementing an external NTP client or a similar mechanism to ensure client and server clocks are synchronized.

Install

• npm install hawk npm
• yarn add hawk yarn
• pnpm add hawk pnpm

Imports

• Client
  wrong:

  const Client = require('hawk').Client;

  correct:

  import { Client } from 'hawk';

  Used for generating Hawk headers on the client-side and authenticating server responses. ESM is preferred.
• Server
  wrong:

  const Server = require('hawk').Server;

  correct:

  import { Server } from 'hawk';

  Used for authenticating incoming Hawk requests on the server-side. ESM is preferred.
• authenticate
  wrong:

  import { Server } from 'hawk'; Server.authenticate(...);

  correct:

  import { authenticate } from 'hawk/server';

  Directly import specific server functions like `authenticate` or `verify` for granular control and potential tree-shaking benefits, if supported by the module structure.
• header
  wrong:

  import { Client } from 'hawk'; Client.header(...);

  correct:

  import { header } from 'hawk/client';

  Directly import specific client functions like `header` for generating authorization headers.

Quickstart

This quickstart demonstrates a basic Hawk client-server interaction in Node.js, including server-side request authentication and client-side header generation.

import { Server, Client } from 'hawk';
import http from 'http';

const credentials = {
  id: process.env.HAWK_ID ?? 'dh37fgj492je',
  key: process.env.HAWK_KEY ?? 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',
  algorithm: 'sha256' as const,
};

const credentialsLookup = (id: string, callback: (err: Error | null, credentials?: typeof credentials) => void) => {
  if (id === credentials.id) {
    return callback(null, credentials);
  }
  callback(new Error('Invalid credentials id'));
};

const server = http.createServer(async (req, res) => {
  if (req.url === '/auth-resource') {
    try {
      const authResult = await Server.authenticate(req, credentialsLookup, {});
      console.log('Server authenticated:', authResult.credentials.id);
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ message: 'Authenticated resource access', user: authResult.credentials.user }));
    } catch (err: any) {
      console.error('Server authentication failed:', err.message);
      res.writeHead(401, { 'WWW-Authenticate': 'Hawk' });
      res.end('Authentication Required');
    }
  } else {
    res.writeHead(404);
    res.end('Not Found');
  }
});

server.listen(8000, '127.0.0.1', () => {
  console.log('Server running at http://127.0.0.1:8000/');

  // Client example
  const requestOptions = {
    host: '127.0.0.1',
    port: 8000,
    path: '/auth-resource',
    method: 'GET',
    headers: {},
  };

  const header = Client.header(requestOptions.path, requestOptions.method, { credentials });
  requestOptions.headers = { ...requestOptions.headers, Authorization: header.field };

  const clientReq = http.request(requestOptions, (clientRes) => {
    let data = '';
    clientRes.on('data', (chunk) => (data += chunk));
    clientRes.on('end', () => {
      console.log(`Client received status: ${clientRes.statusCode}`);
      console.log(`Client received body: ${data}`);
    });
  });
  clientReq.on('error', (e) => console.error(`Client request error: ${e.message}`));
  clientReq.end();
});