{"id":16050,"library":"hawk","title":"HTTP Hawk Authentication Scheme","description":"Hawk is a Node.js library implementing the HTTP Hawk Authentication Scheme, a robust mechanism for making authenticated HTTP requests with partial cryptographic verification. It uses a message authentication code (MAC) algorithm to cover the HTTP method, request URI, host, and optionally the request payload, providing an alternative to HTTP Digest access authentication. Developed by Mozilla, the package is currently at version 9.0.2. It is in a 'maintenance mode' where no new features are added, and only security-related bug fixes are applied, with v9.0.2 announced as the final release. Key differentiators include its focus on two-legged client-server authentication (not OAuth delegation) and its history of ownership by hueniverse, then @hapi, and now Mozilla.","status":"maintenance","version":"9.0.2","language":"javascript","source_language":"en","source_url":"git://github.com/mozilla/hawk","tags":["javascript","http","authentication","scheme","hawk"],"install":[{"cmd":"npm install hawk","lang":"bash","label":"npm"},{"cmd":"yarn add hawk","lang":"bash","label":"yarn"},{"cmd":"pnpm add hawk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used for generating Hawk headers on the client-side and authenticating server responses. ESM is preferred.","wrong":"const Client = require('hawk').Client;","symbol":"Client","correct":"import { Client } from 'hawk';"},{"note":"Used for authenticating incoming Hawk requests on the server-side. ESM is preferred.","wrong":"const Server = require('hawk').Server;","symbol":"Server","correct":"import { Server } from 'hawk';"},{"note":"Directly import specific server functions like `authenticate` or `verify` for granular control and potential tree-shaking benefits, if supported by the module structure.","wrong":"import { Server } from 'hawk'; Server.authenticate(...);","symbol":"authenticate","correct":"import { authenticate } from 'hawk/server';"},{"note":"Directly import specific client functions like `header` for generating authorization headers.","wrong":"import { Client } from 'hawk'; Client.header(...);","symbol":"header","correct":"import { header } from 'hawk/client';"}],"quickstart":{"code":"import { Server, Client } from 'hawk';\nimport http from 'http';\n\nconst credentials = {\n  id: process.env.HAWK_ID ?? 'dh37fgj492je',\n  key: process.env.HAWK_KEY ?? 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',\n  algorithm: 'sha256' as const,\n};\n\nconst credentialsLookup = (id: string, callback: (err: Error | null, credentials?: typeof credentials) => void) => {\n  if (id === credentials.id) {\n    return callback(null, credentials);\n  }\n  callback(new Error('Invalid credentials id'));\n};\n\nconst server = http.createServer(async (req, res) => {\n  if (req.url === '/auth-resource') {\n    try {\n      const authResult = await Server.authenticate(req, credentialsLookup, {});\n      console.log('Server authenticated:', authResult.credentials.id);\n      res.writeHead(200, { 'Content-Type': 'application/json' });\n      res.end(JSON.stringify({ message: 'Authenticated resource access', user: authResult.credentials.user }));\n    } catch (err: any) {\n      console.error('Server authentication failed:', err.message);\n      res.writeHead(401, { 'WWW-Authenticate': 'Hawk' });\n      res.end('Authentication Required');\n    }\n  } else {\n    res.writeHead(404);\n    res.end('Not Found');\n  }\n});\n\nserver.listen(8000, '127.0.0.1', () => {\n  console.log('Server running at http://127.0.0.1:8000/');\n\n  // Client example\n  const requestOptions = {\n    host: '127.0.0.1',\n    port: 8000,\n    path: '/auth-resource',\n    method: 'GET',\n    headers: {},\n  };\n\n  const header = Client.header(requestOptions.path, requestOptions.method, { credentials });\n  requestOptions.headers = { ...requestOptions.headers, Authorization: header.field };\n\n  const clientReq = http.request(requestOptions, (clientRes) => {\n    let data = '';\n    clientRes.on('data', (chunk) => (data += chunk));\n    clientRes.on('end', () => {\n      console.log(`Client received status: ${clientRes.statusCode}`);\n      console.log(`Client received body: ${data}`);\n    });\n  });\n  clientReq.on('error', (e) => console.error(`Client request error: ${e.message}`));\n  clientReq.end();\n});\n","lang":"typescript","description":"This quickstart demonstrates a basic Hawk client-server interaction in Node.js, including server-side request authentication and client-side header generation."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 12 or newer. If using Hapi, ensure it's version 18 or newer.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.1.0"},{"fix":"Evaluate alternative authentication schemes or Hawk implementations in other languages if long-term active development and feature additions are critical for your project.","message":"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.","severity":"deprecated","affected_versions":">=9.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=9.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the client is sending the correct `id` in its Hawk credentials that the server's `credentialsLookup` function can successfully resolve.","cause":"The ID provided in the Hawk Authorization header does not match any known credentials on the server.","error":"Error: Invalid credentials id"},{"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.","cause":"The server failed to authenticate the incoming Hawk request, often due to an invalid MAC, expired timestamp, or incorrect nonce.","error":"401 Authentication Required (WWW-Authenticate: Hawk)"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'authenticate')"}],"ecosystem":"npm"}