tinyhmacmd5 0.1.6 → 0.1.7

package/README.md

@@ -2,16 +2,17 @@ English | [中文](README-zh.md)
 
 # Tiny HMAC MD5
 
-A tiny, fully compliant HMAC-MD5 implementation for JavaScript:  
-[`browser.min.js`](browser.min.js) is only **1017 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**
 
-The goal of `tinyhmacmd5` is to strike a balance between size and performance, rather than sacrificing performance for the sake of minimizing size. Therefore, some performance-oriented optimizations are intentionally retained, and the final size is not the smallest theoretically achievable.
+`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/
 
@@ -44,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`.
 
 ---
@@ -55,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
@@ -76,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
@@ -96,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
@@ -117,10 +147,6 @@ Not recommended for use in environments that support `node:crypto`, as `node:cry
 
 ## 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.
@@ -135,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 (1017 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,n=271733878,t=[],e=Math,o=e.floor,f=r=>16*o((r+72)/64),a=(a,l,c=0,i=f(l),d,g,h,u,s=[r,~n,~r,n],w=[...s])=>{for(a[i-1]=0|l/2**29,a[i-2]=0|8*l,a[o(l/4)]|=128<<8*l;c<a.length;){for(i=0;i<64;)s[u&=3]=0|((d=0|(d=s[3&++u],g=s[3&++u],h=s[3&++u],((l=i>>4<<2)?l>4?l>8?g^(d|~h):d^g^h:d&h|g&~h:d&g|~d&h)+(0|a[c+(i*(29521>>l)+(1296>>l)&15)])+(g="',16%).4$+07&*/5".charCodeAt(l+i%4),t[63-i++]??=0|2**32*e.abs(e.sin(i)))+s[u+1&3]))<<g|d>>>64-g)+s[u+2&3];for(;u;c+=4)w[--u]=s[u]=0|w[u]+s[u]}return s},l=(r,n,t=("string"==typeof r?r=(new TextEncoder).encode(r):r).length,e=new Int32Array(f(4*n+t)),o=0)=>{for(;o<t;)e[n++]=r[o++]|r[o++]<<8|r[o++]<<16|r[o++]<<24;return[e,t]};var md5=(r,n,t)=>{var e=16,o=null!=n,[f,c]=l(r,o*e),i=[],d=t?new Uint8Array(e):"";if(o){let[r,t]=l(n,0);for(t>64&&(r=a(r,t));e;)i[--e]=1785358954^(f[e]=909522486^r[e]);e=16,f=i.concat(a(f,64+c)),c=80}for(f=a(f,c);e;t?d[e]=i:d=(i>>4&&"")+i.toString(16)+d)i=f[--e>>2]>>8*e&255;return d}}
+{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,9 +2,6 @@
 
 // Adapted from https://github.com/blueimp/JavaScript-MD5
 
-let A = 1732584193
-  , D = 271733878
-
 /** @type {number[]} MD5 constants cached in memory */
 let K = []
 
@@ -22,9 +19,6 @@ let toBinlLen = (byteLen) => floor((byteLen + 72) / 64) * 16
  * @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]
  * 
@@ -36,11 +30,11 @@ let binlMD5 = (
   // var:
   i = 0,
   j = toBinlLen(l),
-  t0,
-  t1,
+  t0 = 1732584193,
+  t1 = 271733878,
   t2,
   oi,
-  output = [A, ~D, ~A, D],
+  output = [t0, ~t1, ~t0, t1],
   oldOutput = [...output],
 ) => {
   // console.time("binlMD5")
@@ -48,13 +42,13 @@ let binlMD5 = (
   // append padding
   // `l` may be >= 2**32, so cannot use `>>>` as a replacement for `floor`
   x[j - 1] = 0 | l / 2 ** 29;
-  x[j - 2] = 0 | l * 8;
-  x[floor(l / 4)] |= 0x80 << l * 8;
+  x[floor(l / 4)] |= 0x80 << (x[j - 2] = l << 3);
 
   for (; i < x.length;) {
     for (j = 0; j < 64;) {
-      output[oi &= 3] = (
-        t0 = 0 | (
+      output[oi &= 3] = 0 | (
+        (t1 = 0 | (
+          output[oi] +
           (
             t0 = output[++oi & 3],
             t1 = output[++oi & 3],
@@ -71,13 +65,11 @@ let binlMD5 = (
             0 | x[i + (j * (0x7351 >> l) + (0x0510 >> l) & 15)]
           ) +
           (
-            t1 = "',16%).4$+07&*/5".charCodeAt(l + j % 4),
+            t2 = "',16%).4$+07&*/5".charCodeAt(j & 3 | l),
             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 | t1 >>> 64 - t2
+      ) + t0
     }
     for (; oi; i += 4) {
       oldOutput[--oi] = output[oi] = 0 | oldOutput[oi] + output[oi]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tinyhmacmd5",
-  "version": "0.1.6",
-  "description": "A tiny, fully compliant HMAC-MD5 implementation for JavaScript: browser.min.js is only 1017 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",