feat: add Hash.hmac256 for HMAC-SHA256 hashing

Amp-Thread-ID: https://ampcode.com/threads/T-019bfbdf-042d-715c-8aed-fa3b56817d66
Co-authored-by: Amp <amp@ampcode.com>

Author: jxom

.changeset/serious-chicken-whisper.md

@@ -0,0 +1,5 @@
+---
+"ox": minor
+---
+
+Added `Hash.hmac256` for computing HMAC-SHA256 hashes.

src/core/Hash.ts

@@ -1,3 +1,4 @@
+import { hmac } from '@noble/hashes/hmac'
 import { ripemd160 as noble_ripemd160 } from '@noble/hashes/ripemd160'
 import { keccak_256 as noble_keccak256 } from '@noble/hashes/sha3'
 import { sha256 as noble_sha256 } from '@noble/hashes/sha256'
@@ -73,6 +74,66 @@ export declare namespace keccak256 {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Calculates the [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC) of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ *
+ * This function is a re-export of `hmac` from [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), an audited & minimal JS hashing library.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash, Hex } from 'ox'
+ *
+ * Hash.hmac256(Hex.fromString('key'), '0xdeadbeef')
+ * // @log: '0x...'
+ * ```
+ *
+ * @example
+ * ### Configure Return Type
+ *
+ * ```ts twoslash
+ * import { Hash, Hex } from 'ox'
+ *
+ * Hash.hmac256(Hex.fromString('key'), '0xdeadbeef', { as: 'Bytes' })
+ * // @log: Uint8Array [...]
+ * ```
+ *
+ * @param key - {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} key.
+ * @param value - {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ * @param options - Options.
+ * @returns HMAC-SHA256 hash.
+ */
+export function hmac256<
+  value extends Hex.Hex | Bytes.Bytes,
+  as extends 'Hex' | 'Bytes' =
+    | (value extends Hex.Hex ? 'Hex' : never)
+    | (value extends Bytes.Bytes ? 'Bytes' : never),
+>(
+  key: Hex.Hex | Bytes.Bytes,
+  value: value | Hex.Hex | Bytes.Bytes,
+  options: hmac256.Options<as> = {},
+): hmac256.ReturnType<as> {
+  const { as = typeof value === 'string' ? 'Hex' : 'Bytes' } = options
+  const bytes = hmac(noble_sha256, Bytes.from(key), Bytes.from(value))
+  if (as === 'Bytes') return bytes as never
+  return Hex.fromBytes(bytes) as never
+}
+
+export declare namespace hmac256 {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> = {
+    /** The return type. @default 'Hex' */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Calculates the [Ripemd160](https://en.wikipedia.org/wiki/RIPEMD) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
  *

src/core/_test/Hash.test.ts

@@ -1,6 +1,109 @@
 import { Hash } from 'ox'
 import { describe, expect, test } from 'vitest'
 
+describe('hmac256', () => {
+  test('default', () => {
+    expect(
+      Hash.hmac256(
+        new Uint8Array([107, 101, 121]),
+        new Uint8Array([72, 101, 108, 108, 111]),
+      ),
+    ).toMatchInlineSnapshot(`
+      Uint8Array [
+        199,
+        11,
+        159,
+        77,
+        102,
+        91,
+        214,
+        41,
+        116,
+        175,
+        200,
+        53,
+        130,
+        222,
+        129,
+        14,
+        114,
+        164,
+        26,
+        88,
+        219,
+        130,
+        197,
+        56,
+        169,
+        215,
+        52,
+        201,
+        38,
+        109,
+        50,
+        30,
+      ]
+    `)
+
+    expect(Hash.hmac256('0x6b6579', '0x48656c6c6f')).toMatchInlineSnapshot(
+      `"0xc70b9f4d665bd62974afc83582de810e72a41a58db82c538a9d734c9266d321e"`,
+    )
+  })
+
+  test('as: Hex', () => {
+    expect(
+      Hash.hmac256(
+        new Uint8Array([107, 101, 121]),
+        new Uint8Array([72, 101, 108, 108, 111]),
+        { as: 'Hex' },
+      ),
+    ).toMatchInlineSnapshot(
+      `"0xc70b9f4d665bd62974afc83582de810e72a41a58db82c538a9d734c9266d321e"`,
+    )
+  })
+
+  test('as: Bytes', () => {
+    expect(
+      Hash.hmac256('0x6b6579', '0x48656c6c6f', { as: 'Bytes' }),
+    ).toMatchInlineSnapshot(`
+      Uint8Array [
+        199,
+        11,
+        159,
+        77,
+        102,
+        91,
+        214,
+        41,
+        116,
+        175,
+        200,
+        53,
+        130,
+        222,
+        129,
+        14,
+        114,
+        164,
+        26,
+        88,
+        219,
+        130,
+        197,
+        56,
+        169,
+        215,
+        52,
+        201,
+        38,
+        109,
+        50,
+        30,
+      ]
+    `)
+  })
+})
+
 describe('keccak256', () => {
   test('default', () => {
     expect(Hash.keccak256('0xdeadbeef')).toMatchInlineSnapshot(
@@ -429,6 +532,7 @@ test('exports', () => {
   expect(Object.keys(Hash)).toMatchInlineSnapshot(`
     [
       "keccak256",
+      "hmac256",
       "ripemd160",
       "sha256",
       "validate",