Sodium HMAC Utility

Common errors

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

  cause The `HMAC` constructor was provided with a `hash` object that is missing the `init` method, or the object structure is incorrect.
  fix Verify that the custom hash object passed to `new HMAC(hash)` includes all required methods: `init`, `update`, `final`, and properties: `BYTES`, `STATEBYTES`. Use `sha256` or `sha512` exports as a reference.

• Error: HMAC not initialized

  cause An `HMAC` instance's `update()` method was called before `init()` was invoked to set the secret key.
  fix Call `hmac.init(Buffer.from('your-key'))` immediately after creating the `HMAC` instance and before calling `hmac.update(data)`.

• TypeError: Data must be a Buffer or Uint8Array

  cause A non-Buffer/Uint8Array value was passed to `hmac.update()` or a static HMAC method (`HMAC.sha256`, `HMAC.sha512`).
  fix Ensure all input data, including the key and message parts, are converted to `Buffer` or `Uint8Array` instances, for example, using `Buffer.from('string')` or `b4a.from('string')`.

Warnings

• gotcha When using the streaming HMAC API (HMAC class instance), `hmac.init(key)` must always be called before any calls to `hmac.update(data)`. Failing to initialize will result in runtime errors.
  Fix: Ensure `hmac.init(key)` is invoked once after creating the HMAC instance and before processing any data chunks.
• gotcha The `HMAC` constructor expects the `hash` argument to be an object conforming to a specific interface (`init`, `update`, `final`, `BYTES`, `STATEBYTES`). Providing an object that lacks any of these properties will lead to a `TypeError`.
  Fix: When supplying a custom hash function (e.g., from `libsodium` or other crypto libraries), ensure it exposes all required methods and properties. Refer to the `sha256` or `sha512` exports as examples.
• gotcha The `final()` method returns the HMAC digest. If you intend to use the HMAC result, you must capture the return value of `hmac.final()`.
  Fix: Always assign the result of `hmac.final()` to a variable, e.g., `const output = hmac.final();`.
• gotcha All data inputs (`key`, `data` in `update`, `data` in static methods) are expected to be `Buffer` instances or `Uint8Array`s. While Node.js `Buffer` works, in browser environments, `Uint8Array` or a universal buffer polyfill like `b4a` should be used.
  Fix: Convert all string or other data types to `Buffer.from('your-data')` or `b4a.from('your-data')` before passing them to HMAC functions.

Install

• npm install sodium-hmac npm
• yarn add sodium-hmac yarn
• pnpm add sodium-hmac pnpm

Imports

• HMAC
  wrong:

  const HMAC = require('sodium-hmac').HMAC

  correct:

  import { HMAC } from 'sodium-hmac'

  While CommonJS `require` is shown in examples and is functional, prefer named ESM imports for modern JavaScript environments.
• sha256
  wrong:

  const sha256 = require('sodium-hmac').sha256

  correct:

  import { sha256 } from 'sodium-hmac'

  The `sha256` hash function is exported directly for use with the `HMAC` class or as a standalone utility.
• HMAC.sha256 (static method)
  wrong:

  const result = require('sodium-hmac').HMAC.sha256(data, key)

  correct:

  import { HMAC } from 'sodium-hmac'; const result = HMAC.sha256(data, key);

  This provides a convenient one-shot API for HMAC-SHA256, abstracting the streaming interface.

Quickstart

This quickstart demonstrates both the streaming and one-shot HMAC APIs, using built-in SHA256/SHA512 and conceptually showing how to integrate a custom hash function.

import { HMAC, sha256, sha512 } from 'sodium-hmac';
import b4a from 'b4a'; // A common Buffer-compatible utility for universal environments

const key = b4a.from('a-very-secret-key-of-at-least-32-bytes');
const dataPart1 = b4a.from('This is the first part ');
const dataPart2 = b4a.from('and this is the second part of the message.');

// 1. Using the streaming API with SHA256
const hmacSha256 = new HMAC(sha256);
hmacSha256.init(key);
hmacSha256.update(dataPart1);
hmacSha256.update(dataPart2);
const outputSha256 = hmacSha256.final();
console.log('HMAC-SHA256 (streaming):', outputSha256.toString('hex'));

// 2. Using the simple one-shot API with SHA512
const fullData = b4a.concat([dataPart1, dataPart2]);
const outputSha512 = HMAC.sha512(fullData, key);
console.log('HMAC-SHA512 (one-shot):', outputSha512.toString('hex'));

// 3. Demonstrating custom hash function integration (conceptual, requires 'sodium' or similar)
// Assuming 'sodium' is installed and provides a compatible blake2b hash interface.
/*
import sodium from 'sodium-native'; // or 'libsodium-wrappers'
const blake2b = {
  init: (state, key) => sodium.crypto_generichash_init(state, key, 64), // 64 bytes for BLAKE2b
  update: sodium.crypto_generichash_update,
  final: (state, out) => sodium.crypto_generichash_final(state, out, 64),
  BYTES: 64,
  STATEBYTES: sodium.crypto_generichash_STATEBYTES
};

const hmacBlake2b = new HMAC(blake2b);
hmacBlake2b.init(key);
hmacBlake2b.update(fullData);
const outputBlake2b = hmacBlake2b.final(b4a.alloc(blake2b.BYTES));
console.log('HMAC-BLAKE2b (custom hash):', outputBlake2b.toString('hex'));
*/