tinyhmacmd5 0.1.5 → 0.1.7

package/README.md

@@ -2,15 +2,18 @@ English | [中文](README-zh.md)
 
 # Tiny HMAC MD5
 
-A tiny, fully compliant HMAC-MD5 implementation for JavaScript:  
-[`browser.min.js`](browser.min.js) is only **1045 bytes**.
+A tiny and reliable HMAC-MD5 implementation for JavaScript: [`browser.min.js`](browser.min.js) is only **997 bytes**.
 
 - **Input type**: `string` (UTF‑8), `Uint8Array` or `Uint8ClampedArray`
-- **Output type**: hex `string` or raw `Uint8Array`
-- **Supports inputs ≥ 512 MiB**: Full 64‑bit length padding per RFC 1321
+- **Output type**: hex `string` or bytes `Uint8Array`
+- **Supports inputs ≥ 512 MiB**: The input length theoretically supports 0 to $2^{53}-1$ (`Number.MAX_SAFE_INTEGER`).
 - **TypeScript‑ready**: [`main.d.ts`](main.d.ts)
 - **0 dependencies**
 
+`tinyhmacmd5` does not simply aim for the smallest possible size.  
+Its goal is to balance code size and runtime performance, so some performance-oriented implementations are intentionally retained.  
+As a result, the final size is not the smallest theoretically achievable.
+
 **Live demo**: https://bddjr.github.io/tinyhmacmd5/
 
 > [!WARNING]  
@@ -42,10 +45,11 @@ See https://www.jsdelivr.com/package/npm/tinyhmacmd5
 <script src="https://cdn.jsdelivr.net/npm/tinyhmacmd5"></script>
 ```
 
-### Inline
+It will define the `md5` function using `var`.
 
-You can embed [`browser.min.js`](browser.min.js) directly into your script.
+### Inline
 
+You can embed [`browser.min.js`](browser.min.js) directly into your script.  
 It will define the `md5` function using `var`.
 
 ---
@@ -53,20 +57,18 @@ It will define the `md5` function using `var`.
 ## Example
 
 > [!NOTE]  
-> This library does not validate input types.  
-> Please ensure the input type matches the definitions in [`main.d.ts`](main.d.ts).  
-> TypeScript will catch mismatches at compile time (unless you use `any`).  
-> Invalid types may produce an incorrect MD5 hash.
+> Please ensure that the input type matches the definition in [`main.d.ts`](main.d.ts).  
+> Invalid types may return an incorrect MD5 hash.
 
 HMAC-MD5:
 
 ```js
-// string to hex
+// string (UTF-8) to hex
 // returns "c87fdc912df24da05a6e3fed927e9d89"
 md5("Hello world!👋", "HMAC key 🔑")
 
-// string to bytes
-// returns Uint8Array<ArrayBuffer>
+// string (UTF-8) to bytes
+// returns Uint8Array(16)
 md5("Hello world!👋", "HMAC key 🔑", true)
 
 // bytes to hex
@@ -74,19 +76,19 @@ md5("Hello world!👋", "HMAC key 🔑", true)
 md5(Uint8Array.of(1, 2, 3), Uint8Array.of(4, 5, 6))
 
 // bytes to bytes
-// returns Uint8Array<ArrayBuffer>
+// returns Uint8Array(16)
 md5(Uint8Array.of(1, 2, 3), Uint8Array.of(4, 5, 6), true)
 ```
 
 MD5: (when `key` is `null` or `undefined`)
 
 ```js
-// string to hex
+// string (UTF-8) to hex
 // returns "3ac851eecf9e37be7565bf073a73c9dc"
 md5("Hello world!👋")
 
-// string to bytes
-// returns Uint8Array<ArrayBuffer>
+// string (UTF-8) to bytes
+// returns Uint8Array(16)
 md5("Hello world!👋", null, true)
 
 // bytes to hex
@@ -94,10 +96,40 @@ md5("Hello world!👋", null, true)
 md5(Uint8Array.of(1, 2, 3))
 
 // bytes to bytes
-// returns Uint8Array<ArrayBuffer>
+// returns Uint8Array(16)
 md5(Uint8Array.of(1, 2, 3), null, true)
 ```
 
+`ArrayBuffer` must be wrapped in a `Uint8Array` before use as input;  
+otherwise, it will return an incorrect MD5 hash.
+
+```js
+let data = new ArrayBuffer(8)
+
+// MD5: bytes to hex
+md5(new Uint8Array(data))
+```
+
+You can also input a `Uint8ClampedArray`, which has the same effect as using a `Uint8Array`.
+
+```js
+// MD5: bytes to hex
+// returns "5289df737df57326fcdd22597afb1fac"
+md5(Uint8ClampedArray.of(1, 2, 3))
+```
+
+**[⚠️Unsafe]** You can also input a `number[]`, but every element must be an integer in the range `0 ≤ x ≤ 255`;  
+otherwise, it will return an incorrect MD5 hash.
+
+```js
+let data = [0, 1, 127, 255]
+
+// MD5: bytes to hex
+// returns "b23d6235d525eed4c4b8d741d4c2a5a1"
+//@ts-ignore
+md5(data)
+```
+
 ---
 
 ## Runtime Environment
@@ -109,14 +141,12 @@ Environments that support [Nullish coalescing assignment (`??=`)](https://develo
 - Firefox ≥ 79 (2020-07-28)
 - Safari ≥ 14 (2020-09-16)
 
+Not recommended for use in environments that support `node:crypto`, as `node:crypto` already provides HMAC-MD5.
+
 ---
 
 ## Why I Made This Project
 
-> [!NOTE]  
-> AI-translated from Chinese.  
-> [查看原文](README-zh.md#为什么做这个项目)
-
 I initially used HMAC-MD5 just to call a certain website's API. That site signs the request body with `crypto-js`'s HMAC-MD5 to make reverse engineering harder.
 
 But I only needed HMAC-MD5. Depending on `crypto-js` felt way too bloated. The Web Crypto API doesn't support HMAC-MD5, so I had no choice but to drag in a dependency.
@@ -131,12 +161,14 @@ During the adaptation, I discovered that `blueimp-md5` did not correctly handle
 
 I also found that using `Array` to process inputs over 512 MiB could throw a `RangeError`, so I replaced it with `Int32Array`.
 
-I demonstrated in practice that HMAC-MD5 can be implemented in an extremely small footprint (1045 bytes) while also improving reliability.
+I demonstrated in practice that HMAC-MD5 can be implemented in an extremely small footprint (997 bytes) while also improving reliability.
 
 Maybe not many people care about saving just a few KB, but `tinyhmacmd5` exists precisely to "explore the unknown".
 
 INVINCIBLE EXPERIMENT!
 
+[查看原文](README-zh.md#为什么做这个项目)
+
 ---
 
 ## License

package/browser.min.js

@@ -1,2 +1,2 @@
 /** @license https://bddjr.github.io/tinyhmacmd5/lic */
-{let r=1732584193,e=271733878,n=~r,t=~e,o=2**32,f=Math,a=f.floor,l=r=>16*a((r+8)/64)+16,c=[],d=(d,i,u=0,g=l(i),h,s,w,y,A=[r,t,n,e],v=[...A])=>{for(d[g-1]=0|8*i/o,d[g-2]=0|8*i,d[a(i/4)]|=128<<i%4*8;u<d.length;u+=16){for(y=g=0;g<64;)A[3&y]=0|((h=0|(h=A[3&++y],s=A[3&++y],w=A[3&++y],((i=g>>4<<2)?i>4?i>8?s^(h|~w):h^s^w:h&w|s&~w:h&s|~h&w)+(0|d[u+(g*(29521>>i)+(1296>>i)&15)])+(s="',16%).4$+07&*/5".charCodeAt(i+g%4),c[63-g++]??=0|o*f.abs(f.sin(g)))+A[y+1&3]))<<s|h>>>64-s)+A[y+2&3];for(y=4;y;)v[--y]=A[y]=0|v[y]+A[y]}return A},i=(r,e,n=("string"==typeof r?r=(new TextEncoder).encode(r):r).length,t=new Int32Array(l(4*e+n)),o=0)=>{for(;o<n;)t[e++]=r[o++]|r[o++]<<8|r[o++]<<16|r[o++]<<24;return[t,n]};var md5=(r,e,n)=>{var t=16,o=null!=e,[f,a]=i(r,o*t),l=new Uint8Array(t);if(o){let[r,n]=i(e,0),o=[];for(n>64&&(r=d(r,n));t;)o[--t]=1785358954^(f[t]=909522486^r[t]);t=16,f=o.concat(d(f,64+a)),a=80}for(f=d(f,a);t;)l[--t]=f[t>>2]>>>t%4*8;return n?l:l.reduce((r,e)=>r+(e>>4&&"")+e.toString(16),"")}}
+{let r=[],n=Math,t=n.floor,e=r=>16*t((r+72)/64),o=(o,f,a=0,l=e(f),c=1732584193,i=271733878,d,g,h=[c,~i,~c,i],u=[...h])=>{for(o[l-1]=0|f/2**29,o[t(f/4)]|=128<<(o[l-2]=f<<3);a<o.length;){for(l=0;l<64;)h[g&=3]=0|((i=0|h[g]+(c=h[3&++g],i=h[3&++g],d=h[3&++g],(f=l>>4<<2)?f>4?f>8?i^(c|~d):c^i^d:c&d|i&~d:c&i|~c&d)+(0|o[a+(l*(29521>>f)+(1296>>f)&15)])+(d="',16%).4$+07&*/5".charCodeAt(3&l|f),r[63-l++]??=0|2**32*n.abs(n.sin(l))))<<d|i>>>64-d)+c;for(;g;a+=4)u[--g]=h[g]=0|u[g]+h[g]}return h},f=(r,n,t=("string"==typeof r?r=(new TextEncoder).encode(r):r).length,o=new Int32Array(e(4*n+t)),f=0)=>{for(;f<t;)o[n++]=r[f++]|r[f++]<<8|r[f++]<<16|r[f++]<<24;return[o,t]};var md5=(r,n,t)=>{var e=16,a=null!=n,[l,c]=f(r,a*e),i=[],d=t?new Uint8Array(e):"";if(a){let[r,t]=f(n,0);for(t>64&&(r=o(r,t));e;)i[--e]=1785358954^(l[e]=909522486^r[e]);e=16,l=i.concat(o(l,64+c)),c=80}for(l=o(l,c);e;t?d[e]=i:d=(i>>4&&"")+i.toString(16)+d)i=l[--e>>2]>>8*e&255;return d}}

package/main.js

@@ -2,22 +2,16 @@
 
 // Adapted from https://github.com/blueimp/JavaScript-MD5
 
-let A = 1732584193
-  , D = 271733878
-  , C = ~A
-  , B = ~D
-
-let $2_32 = 2 ** 32
+/** @type {number[]} MD5 constants cached in memory */
+let K = []
 
 let $Math = Math
 
 let floor = $Math.floor
 
 /** @param {number} byteLen */
-let toBinlLen = (byteLen) => floor((byteLen + 8) / 64) * 16 + 16
-
-/** @type {number[]} MD5 constants cached in memory */
-let K = []
+// `byteLen` may be >= 2**32, so cannot use `>>>` as a replacement for `floor`
+let toBinlLen = (byteLen) => floor((byteLen + 72) / 64) * 16
 
 /**
  * Calculate the MD5 of an array of little-endian words, and a byte length.
@@ -25,9 +19,6 @@ let K = []
  * @param {Int32Array | number[]} x Array of little-endian words
  * @param {number} l Byte length
  * 
- * @param {number} [j]
- * @param {number} [t0]
- * @param {number} [t1]
  * @param {number} [t2]
  * @param {number} [oi]
  * 
@@ -39,24 +30,25 @@ let binlMD5 = (
   // var:
   i = 0,
   j = toBinlLen(l),
-  t0,
-  t1,
+  t0 = 1732584193,
+  t1 = 271733878,
   t2,
   oi,
-  output = [A, B, C, D],
+  output = [t0, ~t1, ~t0, t1],
   oldOutput = [...output],
 ) => {
   // console.time("binlMD5")
 
   // append padding
-  x[j - 1] = 0 | l * 8 / $2_32;
-  x[j - 2] = 0 | l * 8;
-  x[floor(l / 4)] |= 0x80 << l % 4 * 8;
-
-  for (; i < x.length; i += 16) {
-    for (oi = j = 0; j < 64;) {
-      output[oi & 3] = (
-        t0 = 0 | (
+  // `l` may be >= 2**32, so cannot use `>>>` as a replacement for `floor`
+  x[j - 1] = 0 | l / 2 ** 29;
+  x[floor(l / 4)] |= 0x80 << (x[j - 2] = l << 3);
+
+  for (; i < x.length;) {
+    for (j = 0; j < 64;) {
+      output[oi &= 3] = 0 | (
+        (t1 = 0 | (
+          output[oi] +
           (
             t0 = output[++oi & 3],
             t1 = output[++oi & 3],
@@ -73,15 +65,13 @@ let binlMD5 = (
             0 | x[i + (j * (0x7351 >> l) + (0x0510 >> l) & 15)]
           ) +
           (
-            t1 = "',16%).4$+07&*/5".charCodeAt(l + j % 4),
-            K[63 - j++] ??= 0 | $2_32 * $Math.abs($Math.sin(j))
-          ) +
-          output[oi + 1 & 3]
-        ),
-        0 | (t0 << t1 | t0 >>> 64 - t1) + output[oi + 2 & 3]
-      )
+            t2 = "',16%).4$+07&*/5".charCodeAt(j & 3 | l),
+            K[63 - j++] ??= 0 | 2 ** 32 * $Math.abs($Math.sin(j))
+          )
+        )) << t2 | t1 >>> 64 - t2
+      ) + t0
     }
-    for (oi = 4; oi;) {
+    for (; oi; i += 4) {
       oldOutput[--oi] = output[oi] = 0 | oldOutput[oi] + output[oi]
     }
   }
@@ -139,34 +129,40 @@ var md5 = (data, key, raw) => {
   var i = 16
     , hasKey = key != null
     , [bdata, dataByteLen] = inputToBinl(data, /**@type {*}*/(hasKey) * i)
-    , out = new Uint8Array(i)
+
+  /** @type {*} */
+  var temp = []
+
+  /** @type {*} */
+  var out = raw ? new Uint8Array(i) : ''
 
   if (hasKey) {
     // HMAC
     let [bkey, keyByteLen] = inputToBinl(key, 0)
-    let opad = []
     if (keyByteLen > 64) {
       bkey = binlMD5(bkey, keyByteLen)
     }
     for (; i;) {
       // (0x36363636 ^ 0x5c5c5c5c) == 0x6a6a6a6a
-      opad[--i] = 0x6a6a6a6a ^ (bdata[i] = 0x36363636 ^ bkey[i])
+      temp[--i] = 0x6a6a6a6a ^ (bdata[i] = 0x36363636 ^ bkey[i])
     }
     i = 16
-    bdata = opad.concat(binlMD5(bdata, 64 + dataByteLen))
+    bdata = temp.concat(binlMD5(bdata, 64 + dataByteLen))
     dataByteLen = 80
   }
 
   bdata = binlMD5(bdata, dataByteLen)
 
-  // binl to bytes
-  for (; i;) {
-    out[--i] = bdata[i >> 2] >>> i % 4 * 8
+  // binl to bytes or hex
+  for (; i;
+    raw
+      ? out[i] = temp
+      : out = (temp >> 4 && '') + temp.toString(16) + out
+  ) {
+    temp = bdata[--i >> 2] >> i * 8 & 0xff
   }
 
-  return raw
-    ? out
-    : out.reduce((p, v) => p + (v >> 4 && '') + v.toString(16), '')
+  return out
 }
 
 export default md5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tinyhmacmd5",
-  "version": "0.1.5",
-  "description": "A tiny, fully compliant HMAC-MD5 implementation for JavaScript: browser.min.js is only 1045 bytes.",
+  "version": "0.1.7",
+  "description": "A tiny and reliable HMAC-MD5 implementation for JavaScript: browser.min.js is only 997 bytes.",
   "author": "bddjr",
   "license": "MIT",
   "type": "module",
@@ -17,20 +17,35 @@
   "keywords": [
     "md5",
     "hash",
+    "hashing",
     "hmac",
     "hmacmd5",
     "hmac-md5",
     "tiny",
+    "tiny-hmac-md5",
+    "small",
+    "lightweight",
+    "minimal",
     "hex",
     "crypto",
     "encryption",
     "cryptography",
+    "message-digest",
+    "cryptographic-hash",
+    "web",
+    "pure-javascript",
+    "esm",
+    "javascript",
+    "typescript",
+    "frontend",
+    "front-end",
     "blueimp",
     "blueimp-md5",
     "js-md5",
     "crypto-js",
-    "javascript",
-    "typescript"
+    "tiny-hashes",
+    "tiny-js-md5",
+    "spark-md5"
   ],
   "repository": {
     "type": "git",