@noble/hashes 1.4.0: HMAC

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @noble/hashes.HMAC in pkg:npm/%40noble/hashes@1.4.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40noble/hashes@1.4.0
Demonstrate these symbols/APIs:
  - @noble/hashes.HMAC

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ec7da7bcb1d2b1c8dc1be57491761fe9cc886f001935d370f8f035a7efaa74b4","contract":["assert HMAC class initializes with hash function and secret key, exposing blockLen and outputLen properties","assert HMAC update accepts string and Uint8Array data chunks with fluent method chaining","assert HMAC digest returns Uint8Array matching RFC 4231 test vectors and marks instance destroyed","assert HMAC clone forks intermediate state into independent streams producing distinct digests","assert HMAC digestInto writes authentication code directly into preallocated destination buffer","assert HMAC methods throw Error when called after destruction or when given invalid buffer lengths"],"goal":"verify @noble/hashes.HMAC in pkg:npm/%40noble/hashes@1.4.0","kind":"HOW","packages":["pkg:npm/%40noble/hashes@1.4.0"],"schemaVersion":1,"symbols":["@noble/hashes.HMAC"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40noble/hashes@1.4.0"],"schemaVersion":1,"subject":"pkg:npm/%40noble/hashes@1.4.0","symbols":["@noble/hashes.HMAC"],"verifierAdapter":"node-typescript@1"}

const { HMAC } = require('@noble/hashes/hmac');
const { sha256 } = require('@noble/hashes/sha256');
const { sha512 } = require('@noble/hashes/sha512');
const { bytesToHex, hexToBytes, utf8ToBytes, toBytes } = require('@noble/hashes/utils');

/**
 * Creates an HMAC instance using the given hash function and key.
 * @param {import('@noble/hashes/utils').CHash} hash
 * @param {string | Uint8Array} key
 * @returns {HMAC<any>}
 */
function createHMAC(hash, key) {
  return new HMAC(hash, toBytes(key));
}

/**
 * Computes HMAC digest as lowercase hex string using HMAC class.
 * @param {import('@noble/hashes/utils').CHash} hash
 * @param {string | Uint8Array} key
 * @param {string | Uint8Array} message
 * @returns {string}
 */
function computeHMACHex(hash, key, message) {
  const h = new HMAC(hash, toBytes(key));
  h.update(toBytes(message));
  return bytesToHex(h.digest());
}

/**
 * Computes HMAC streaming across multiple chunks.
 * @param {import('@noble/hashes/utils').CHash} hash
 * @param {string | Uint8Array} key
 * @param {Array<string | Uint8Array>} chunks
 * @returns {string}
 */
function computeHMACChunksHex(hash, key, chunks) {
  const h = new HMAC(hash, toBytes(key));
  for (const chunk of chunks) {
    h.update(toBytes(chunk));
  }
  return bytesToHex(h.digest());
}

module.exports = {
  HMAC,
  sha256,
  sha512,
  createHMAC,
  computeHMACHex,
  computeHMACChunksHex,
  bytesToHex,
  hexToBytes,
  utf8ToBytes,
  toBytes,
};

{
  "name": "sample-noble-hashes-hmac-class",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-noble-hashes-hmac-class",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@noble/hashes": "1.4.0"
      }
    },
    "node_modules/@noble/hashes": {
      "version": "1.4.0",
      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.4.0.tgz",
      "integrity": "sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg==",
      "license": "MIT",
      "engines": {
        "node": ">= 16"
      },
      "funding": {
        "url": "https://paulmillr.com/funding/"
      }
    }
  }
}

{
  "name": "sample-noble-hashes-hmac-class",
  "version": "1.0.0",
  "description": "Clean-room verification sample for @noble/hashes.HMAC in pkg:npm/%40noble/hashes@1.4.0",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@noble/hashes": "1.4.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify @noble/hashes.HMAC in pkg:npm/%40noble/hashes@1.4.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40noble/hashes@1.4.0"
  ],
  "symbols": [
    "@noble/hashes.HMAC"
  ]
}

import assert from 'node:assert';
import {
  HMAC,
  sha256,
  sha512,
  createHMAC,
  computeHMACHex,
  computeHMACChunksHex,
  bytesToHex,
  utf8ToBytes,
} from '../index.js';

// 1. HMAC class constructor initializes with hash and key, exposing blockLen and outputLen
const key20 = new Uint8Array(20).fill(0x0b);
const hmac256 = new HMAC(sha256, key20);
assert.strictEqual(hmac256.blockLen, 64, 'HMAC-SHA256 blockLen must be 64 bytes');
assert.strictEqual(hmac256.outputLen, 32, 'HMAC-SHA256 outputLen must be 32 bytes');

const hmac512 = new HMAC(sha512, key20);
assert.strictEqual(hmac512.blockLen, 128, 'HMAC-SHA512 blockLen must be 128 bytes');
assert.strictEqual(hmac512.outputLen, 64, 'HMAC-SHA512 outputLen must be 64 bytes');

// 2. HMAC update accepts string and Uint8Array with method chaining
const chainInstance = new HMAC(sha256, key20);
const chainedRef = chainInstance.update(utf8ToBytes('Hi ')).update('There');
assert.strictEqual(chainedRef, chainInstance, 'update returns this instance for method chaining');

// 3. RFC 4231 TC1: HMAC-SHA256 test vector
const tc1Digest = chainedRef.digest();
assert(tc1Digest instanceof Uint8Array, 'digest returns Uint8Array');
assert.strictEqual(tc1Digest.length, 32, 'HMAC-SHA256 digest length is 32');
assert.strictEqual(
  bytesToHex(tc1Digest),
  'b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7',
  'HMAC-SHA256 produces expected digest matching RFC 4231 TC1'
);

// RFC 4231 TC2: key = "Jefe", data = "what do ya want for nothing?"
const tc2Key = 'Jefe';
const tc2Data = 'what do ya want for nothing?';
assert.strictEqual(
  computeHMACHex(sha256, tc2Key, tc2Data),
  '5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843',
  'HMAC-SHA256 RFC 4231 TC2 produces expected hex digest'
);
assert.strictEqual(
  computeHMACHex(sha512, tc2Key, tc2Data),
  '164b7a7bfcf819e2e395fbe73b56e0a387bd64222e831fd610270cd7ea2505549758bf75c05a994a6d034f65f8f0e6fdcaeab1a34d4a6b4b636e070a38bce737',
  'HMAC-SHA512 RFC 4231 TC2 produces expected 64-byte hex digest'
);

// 4. HMAC clone forks intermediate state into independent streams
const baseHmac = new HMAC(sha256, tc2Key);
baseHmac.update('shared-prefix:');
const branchAlpha = baseHmac.clone();
const branchBeta = baseHmac.clone();

branchAlpha.update('route-alpha');
branchBeta.update('route-beta');

const digestAlpha = bytesToHex(branchAlpha.digest());
const digestBeta = bytesToHex(branchBeta.digest());
assert.notStrictEqual(digestAlpha, digestBeta, 'Cloned HMAC branches produce distinct digests');
assert.strictEqual(
  digestAlpha,
  computeHMACHex(sha256, tc2Key, 'shared-prefix:route-alpha'),
  'Branch Alpha matches independent computation'
);
assert.strictEqual(
  digestBeta,
  computeHMACHex(sha256, tc2Key, 'shared-prefix:route-beta'),
  'Branch Beta matches independent computation'
);

// 5. HMAC digestInto writes directly into preallocated buffer
const outBuffer = new Uint8Array(32);
const hmacInto = new HMAC(sha256, tc2Key);
hmacInto.update('shared-prefix:route-alpha');
hmacInto.digestInto(outBuffer);
assert.strictEqual(bytesToHex(outBuffer), digestAlpha, 'digestInto fills buffer with exact HMAC digest');

// 6. Error handling: methods throw after destruction or on invalid arguments
assert.throws(() => {
  hmacInto.update('more data');
}, /Hash instance has been destroyed/i, 'update throws on destroyed HMAC instance');

assert.throws(() => {
  hmacInto.digest();
}, /Hash instance has been destroyed/i, 'digest throws on destroyed HMAC instance');

const shortBuf = new Uint8Array(16);
const freshHmac = new HMAC(sha256, tc2Key);
assert.throws(() => {
  freshHmac.digestInto(shortBuf);
}, /Uint8Array expected of length/i, 'digestInto throws on insufficient buffer length');

assert.throws(() => {
  new HMAC(() => {}, tc2Key);
}, /Hash should be wrapped by utils.wrapConstructor/i, 'HMAC constructor rejects invalid hash function');

// 7. Streaming helper verification
const chunksResult = computeHMACChunksHex(sha256, tc2Key, ['what do ', 'ya want ', 'for nothing?']);
assert.strictEqual(chunksResult, computeHMACHex(sha256, tc2Key, tc2Data), 'computeHMACChunksHex matches one-shot');

console.log('All @noble/hashes.HMAC contract assertions passed.');