@noble/hashes 2.3.0: expand

# Notes: Noble Hashes HKDF Expand Key Derivation

## Search Result
`search_known_solution` returned `NO_SAFE_MATCH` for `@noble/hashes.expand` in `@noble/hashes@2.3.0`. Existing samples for `@noble/hashes` cover general hashing, HMAC, and full HKDF extraction/expansion workflow, but lack isolated contract verification specifically for the standalone `expand` primitive, its length constraints, default parameters, zero-length handling, and PRK size invariants per RFC 5869.

## Naive Model Assumption
Models and developers often assume that HKDF expansion requires all parameters explicitly passed, or that requesting a length of 0 bytes throws an error instead of returning an empty `Uint8Array`. Additionally, models often assume that passing a PRK of arbitrary size is permitted, or that the maximum expansion length is unbounded rather than restricted to `255 * HashLen`. Finally, models often forget that `@noble/hashes` prohibits importing from the root module and requires importing from `@noble/hashes/hkdf.js`.

## Failure Mode
1. Attempting to import `expand` from `@noble/hashes` throws `Error: root module cannot be imported: import submodules instead. Check out README`. Submodule `@noble/hashes/hkdf.js` must be used.
2. Passing a `prk` whose length is strictly less than `hash.outputLen` throws `Error: "prk" must be at least HashLen octets`.
3. Requesting an output length greater than `255 * hash.outputLen` throws `Error: Length must be <= 255*HashLen`.
4. Omitting `info` or passing `undefined` defaults cleanly to empty bytes, and omitting `length` defaults to 32 bytes.
5. Requesting `length = 0` produces an empty `Uint8Array` instead of throwing.

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.expand in pkg:npm/%40noble/hashes@2.3.0
Kind: HOW

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

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:b6c668c3b312fe328842ce482ba3b8ca825f3ad1348484bc6c9ca641da05ee9c","contract":["expand derives output keying material matching RFC 5869 test vector 1 with SHA-256 and multi-block expansion","expand derives multi-block output keying material matching RFC 5869 test vector 2 with SHA-256","expand defaults info to empty bytes and length to 32 when info and length are omitted or undefined","expand returns an empty Uint8Array when requested output length is 0","expand throws an error when pseudorandom key length is less than HashLen octets","expand throws an error when requested output length exceeds 255 * HashLen","expand derives deterministic output keying material across different hash functions including SHA-512"],"goal":"verify @noble/hashes.expand in pkg:npm/%40noble/hashes@2.3.0","kind":"HOW","packages":["pkg:npm/%40noble/hashes@2.3.0"],"schemaVersion":1,"symbols":["@noble/hashes.expand"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40noble/hashes@2.3.0"],"schemaVersion":1,"subject":"pkg:npm/%40noble/hashes@2.3.0","symbols":["@noble/hashes.expand"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-noble-hashes-expand",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-noble-hashes-expand",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@noble/hashes": "2.3.0"
      }
    },
    "node_modules/@noble/hashes": {
      "version": "2.3.0",
      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.3.0.tgz",
      "integrity": "sha512-oN+QwyX7VSHotibwubG3kpzbwKrfnyR6OOO+3Nk/53ADL7FmgHHz4TgrbaYKvvOw09u6QTx0oiH1cNCIOuN0CQ==",
      "license": "MIT",
      "engines": {
        "node": ">= 20.19.0"
      },
      "funding": {
        "url": "https://paulmillr.com/funding/"
      }
    }
  }
}

{
  "name": "sample-noble-hashes-expand",
  "version": "1.0.0",
  "type": "module",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@noble/hashes": "2.3.0"
  }
}

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

import { expand } from '@noble/hashes/hkdf.js';
import { sha256, sha512 } from '@noble/hashes/sha2.js';
import { utf8ToBytes, hexToBytes, bytesToHex } from '@noble/hashes/utils.js';

export {
  expand,
  sha256,
  sha512,
  utf8ToBytes,
  hexToBytes,
  bytesToHex
};

/**
 * Expands a pseudorandom key (PRK) into output keying material (OKM) using HKDF-Expand (RFC 5869).
 *
 * @param {import('@noble/hashes/utils.js').CHash} hash - Underlying cryptographic hash function (e.g. sha256).
 * @param {Uint8Array} prk - Pseudorandom key with length at least HashLen octets.
 * @param {Uint8Array|undefined} [info] - Context/application specific info; if undefined, defaults to empty bytes.
 * @param {number} [length=32] - Desired output keying material length in bytes (0 <= length <= 255 * HashLen).
 * @returns {Uint8Array} Derived output keying material of requested length.
 */
export function expandKey(hash, prk, info, length = 32) {
  return expand(hash, prk, info, length);
}

import assert from 'node:assert';
import {
  expand,
  sha256,
  sha512,
  utf8ToBytes,
  hexToBytes,
  bytesToHex,
  expandKey
} from '../src/index.mjs';

// ---------------------------------------------------------------------------
// 1. Contract: expand derives output keying material matching RFC 5869 test vector 1 with SHA-256 and multi-block expansion
// ---------------------------------------------------------------------------
{
  const prk = hexToBytes('077709362c2e32df0ddc3f0dc47bba6390b6c73bb50f9c3122ec844ad7c2b3e5');
  const info = hexToBytes('f0f1f2f3f4f5f6f7f8f9');
  const length = 42;
  const expectedOkm = '3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865';

  const okm = expand(sha256, prk, info, length);
  assert.strictEqual(bytesToHex(okm), expectedOkm, 'RFC 5869 test case 1 OKM match');

  const helperOkm = expandKey(sha256, prk, info, length);
  assert.strictEqual(bytesToHex(helperOkm), expectedOkm, 'helper expandKey match');
}

// ---------------------------------------------------------------------------
// 2. Contract: expand derives multi-block output keying material matching RFC 5869 test vector 2 with SHA-256
// ---------------------------------------------------------------------------
{
  const prk = hexToBytes('06a6b88c5853361a06104c9ceb35b45cef760014904671014a193f40c15fc244');
  const info = hexToBytes('b0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff');
  const length = 82;
  const expectedOkm = 'b11e398dc80327a1c8e7f78c596a49344f012eda2d4efad8a050cc4c19afa97c59045a99cac7827271cb41c65e590e09da3275600c2f09b8367793a9aca3db71cc30c58179ec3e87c14c01d5c1f3434f1d87';

  const okm = expand(sha256, prk, info, length);
  assert.strictEqual(bytesToHex(okm), expectedOkm, 'RFC 5869 test case 2 OKM match');
}

// ---------------------------------------------------------------------------
// 3. Contract: expand defaults info to empty bytes and length to 32 when info and length are omitted or undefined
// ---------------------------------------------------------------------------
{
  const prk = new Uint8Array(sha256.outputLen);
  prk.fill(1);

  const okmDefault = expand(sha256, prk);
  assert.strictEqual(okmDefault.length, 32, 'default output length is 32');

  const okmExplicit = expand(sha256, prk, undefined, 32);
  assert.deepStrictEqual(okmDefault, okmExplicit, 'undefined info and explicit 32 matches default call');

  const okmEmptyBuffer = expand(sha256, prk, new Uint8Array(0), 32);
  assert.deepStrictEqual(okmDefault, okmEmptyBuffer, 'empty Uint8Array info matches undefined info');
}

// ---------------------------------------------------------------------------
// 4. Contract: expand returns an empty Uint8Array when requested output length is 0
// ---------------------------------------------------------------------------
{
  const prk = new Uint8Array(sha256.outputLen);
  const okmZero = expand(sha256, prk, undefined, 0);
  assert.strictEqual(okmZero.length, 0, 'zero length produces empty array');
  assert.ok(okmZero instanceof Uint8Array, 'result is Uint8Array instance');
}

// ---------------------------------------------------------------------------
// 5. Contract: expand throws an error when pseudorandom key length is less than HashLen octets
// ---------------------------------------------------------------------------
{
  const shortPrk = new Uint8Array(sha256.outputLen - 1);
  assert.throws(
    () => expand(sha256, shortPrk, undefined, 32),
    { message: '"prk" must be at least HashLen octets' },
    'expand should throw when prk is shorter than HashLen'
  );
}

// ---------------------------------------------------------------------------
// 6. Contract: expand throws an error when requested output length exceeds 255 * HashLen
// ---------------------------------------------------------------------------
{
  const prk = new Uint8Array(sha256.outputLen);
  const maxLen = 255 * sha256.outputLen;
  assert.throws(
    () => expand(sha256, prk, undefined, maxLen + 1),
    { message: 'Length must be <= 255*HashLen' },
    'expand should throw when length exceeds 255 * HashLen'
  );
}

// ---------------------------------------------------------------------------
// 7. Contract: expand derives deterministic output keying material across different hash functions including SHA-512
// ---------------------------------------------------------------------------
{
  const prk512 = new Uint8Array(sha512.outputLen);
  prk512.fill(0x42);
  const info512 = utf8ToBytes('sha512 context info');
  const okm512 = expand(sha512, prk512, info512, 100);
  assert.strictEqual(okm512.length, 100, 'SHA-512 expansion produces 100 bytes');

  assert.throws(
    () => expand(sha512, new Uint8Array(sha512.outputLen - 1), info512, 64),
    { message: '"prk" must be at least HashLen octets' },
    'SHA-512 rejects PRK shorter than 64 octets'
  );

  assert.throws(
    () => expand(sha512, prk512, info512, 255 * 64 + 1),
    { message: 'Length must be <= 255*HashLen' },
    'SHA-512 rejects length exceeding 255 * 64 octets'
  );
}

console.log('All expand contract tests passed successfully.');