Registry / http-networking / hawk
library0.1jsnpmunverified

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.

npm install hawk
INSTALL
IMPORT
SIG · HAWK
H
hawk
http-networkingjavascriptv0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
import { Client } from 'hawk';
const Client = require('hawk').Client;
Used for generating Hawk headers on the client-side and authenticating server responses. ESM is preferred.
Server
import { Server } from 'hawk';
const Server = require('hawk').Server;
Used for authenticating incoming Hawk requests on the server-side. ESM is preferred.
authenticate
import { authenticate } from 'hawk/server';
import { Server } from 'hawk'; Server.authenticate(...);
Directly import specific server functions like `authenticate` or `verify` for granular control and potential tree-shaking benefits, if supported by the module structure.
header
import { header } from 'hawk/client';
import { Client } from 'hawk'; Client.header(...);
Directly import specific client functions like `header` for generating authorization headers.

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(); });
Debug
Known issues
breakingVersion 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.
affects: >=8.0.0
breakingVersion 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.
affects: >=7.1.0
deprecatedThe `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.
affects: >=9.0.2
gotchaThe 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.
affects: all
gotchaVersion 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.
affects: >=9.0.0
Errors
Common errors & fixes
Error: Invalid credentials id
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)
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')
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.
Upgrade
Version history
0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources