tinyhmacmd5 0.1.1 → 0.1.3

package/README.md

@@ -1,10 +1,17 @@
+English | [中文](README-zh.md)
+
 # Tiny HMAC MD5
 
-A tiny JavaScript HMAC-MD5 implementation.
+A tiny, fully compliant HMAC-MD5 implementation for JavaScript:  
+[`browser.min.js`](browser.min.js) is only **1051 bytes**.
 
-The minified browser bundle ([`browser.min.js`](browser.min.js)) is only 1057 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
+- **TypeScript‑ready**: [`main.d.ts`](main.d.ts)
+- **0 dependencies**
 
-Preview: https://bddjr.github.io/tinyhmacmd5/
+**Live demo**: https://bddjr.github.io/tinyhmacmd5/
 
 > [!WARNING]  
 > MD5 is cryptographically broken and unsafe for security-sensitive applications.  
@@ -14,6 +21,7 @@ Preview: https://bddjr.github.io/tinyhmacmd5/
 
 ### npm
 
+
 ```
 npm i tinyhmacmd5
 ```
@@ -22,6 +30,10 @@ npm i tinyhmacmd5
 import md5 from "tinyhmacmd5";
 ```
 
+### Other Package Managers
+
+You can also use other package managers (e.g. `pnpm` or `yarn`) in place of `npm`.
+
 ### jsDelivr
 
 See https://www.jsdelivr.com/package/npm/tinyhmacmd5
@@ -30,13 +42,21 @@ See https://www.jsdelivr.com/package/npm/tinyhmacmd5
 <script src="https://cdn.jsdelivr.net/npm/tinyhmacmd5"></script>
 ```
 
+### Inline
+
+You can embed [`browser.min.js`](browser.min.js) directly into your script.
+
+It will define the `md5` function using `var`.
+
 ---
 
 ## Example
 
-> [!WARNING]  
-> Please make sure on your own that the types of input parameters conform to the definitions in [`main.d.ts`](main.d.ts).  
-> If you pass wrong types, it may not throw an error and may produce incorrect results.
+> [!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.
 
 HMAC-MD5:
 
@@ -58,7 +78,7 @@ md5(Uint8Array.of(1, 2, 3), Uint8Array.of(4, 5, 6))
 md5(Uint8Array.of(1, 2, 3), Uint8Array.of(4, 5, 6), true)
 ```
 
-MD5:
+MD5: (when `key` is `null` or `undefined`)
 
 ```js
 // string to hex
@@ -80,6 +100,52 @@ md5(Uint8Array.of(1, 2, 3), null, true)
 
 ---
 
+## Runtime Environment
+
+Environments that support [Nullish coalescing assignment (`??=`)](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing_assignment) :
+
+- Chrome ≥ 85 (2020-08-25)
+- Edge ≥ 85 (2020-08-27)
+- Firefox ≥ 79 (2020-07-28)
+- Safari ≥ 14 (2020-09-16)
+
+---
+
+## 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.
+
+Then I found `blueimp-md5`. Its `md5.min.js` is only 3750 bytes, even smaller than `js-md5`.
+
+But I felt `blueimp-md5` was still far too bloated. It has some completely unnecessary design choices—it repeatedly parses strings and creates new ones, adding a lot of unnecessary overhead.
+
+So I decided to adapt it, use a more modern implementation, and shrink the size even further. That's how `tinyhmacmd5` was born.
+
+During the adaptation, I discovered that `blueimp-md5` did not correctly handle the 64-bit length field required by MD5 when the input bit-length exceeded 32 bits. It wrote only the low 32 bits and ignored the high 32 bits. I fixed this bug.
+
+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 (1051 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!
+
+---
+
+## License
+
+The MIT License  
+See: [`LICENSE`](LICENSE)
+
+---
+
 ## Clone
 
 ```

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,i=[],u=(u,d,h=0,c=l(d),g,s,w,y,A=[r,t,n,e],v=[...A])=>{for(u[c-1]=0|8*d/o,u[c-2]=0|8*d,u[a(d/4)]|=128<<d%4*8;h<u.length;h+=16){for(y=c=0;c<64;)A[3&y]=0|((g=0|(g=A[3&++y],s=A[3&++y],w=A[3&++y],((d=c>>4<<2)?d>4?d>8?s^(g|~w):g^s^w:g&w|s&~w:g&s|~g&w)+(0|u[h+(c*(29521>>d)+(1296>>d)&15)])+(s=31&"',16%).4$+07&*/5".charCodeAt(d+c%4),i[63-c++]??=0|o*f.abs(f.sin(c)))+A[y+1&3]))<<s|g>>>32-s)+A[y+2&3];for(y=4;y;)v[--y]=A[y]=0|v[y]+A[y]}return A},d=(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]=d(r,o*t),l=new Uint8Array(t);if(o){let[r,n]=d(e,0),o=[];for(n>64&&(r=u(r,n));t;)f[--t]=909522486^r[t],o[t]=1549556828^r[t];t=16,(f=u(f,64+a)).unshift(...o),a=80}for(f=u(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=1732584193,e=271733878,n=~r,t=~e,o=2**32,f=Math,a=f.floor,l=r=>16*a((r+8)/64)+16,i=[],u=(u,d,h=0,c=l(d),g,s,w,y,A=[r,t,n,e],v=[...A])=>{for(u[c-1]=0|8*d/o,u[c-2]=0|8*d,u[a(d/4)]|=128<<d%4*8;h<u.length;h+=16){for(y=c=0;c<64;)A[3&y]=0|((g=0|(g=A[3&++y],s=A[3&++y],w=A[3&++y],((d=c>>4<<2)?d>4?d>8?s^(g|~w):g^s^w:g&w|s&~w:g&s|~g&w)+(0|u[h+(c*(29521>>d)+(1296>>d)&15)])+(s="',16%).4$+07&*/5".charCodeAt(d+c%4),i[63-c++]??=0|o*f.abs(f.sin(c)))+A[y+1&3]))<<s|g>>>64-s)+A[y+2&3];for(y=4;y;)v[--y]=A[y]=0|v[y]+A[y]}return A},d=(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]=d(r,o*t),l=new Uint8Array(t);if(o){let[r,n]=d(e,0),o=[];for(n>64&&(r=u(r,n));t;)o[--t]=1785358954^(f[t]=909522486^r[t]);t=16,(f=u(f,64+a)).unshift(...o),a=80}for(f=u(f,a);t;)l[--t]=f[t>>2]>>>t%4*8;return n?l:l.reduce((r,e)=>r+(e>>4&&"")+e.toString(16),"")}}

package/main.js

@@ -64,21 +64,21 @@ let binlMD5 = (
             (l = j >> 4 << 2)
               ? l > 4
                 ? l > 8
-                  ? t1 ^ (t0 | ~t2)  // Round 4: II
-                  : t0 ^ t1 ^ t2     // Round 3: HH
-                : t0 & t2 | t1 & ~t2 // Round 2: GG
-              : t0 & t1 | ~t0 & t2   // Round 1: FF
+                  ? t1 ^ (t0 | ~t2)  // Round 4: I
+                  : t0 ^ t1 ^ t2     // Round 3: H
+                : t0 & t2 | t1 & ~t2 // Round 2: G
+              : t0 & t1 | ~t0 & t2   // Round 1: F
           ) +
           (
             0 | x[i + (j * (0x7351 >> l) + (0x0510 >> l) & 15)]
           ) +
           (
-            t1 = "',16%).4$+07&*/5".charCodeAt(l + j % 4) & 31,
+            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 >>> 32 - t1) + output[oi + 2 & 3]
+        0 | (t0 << t1 | t0 >>> 64 - t1) + output[oi + 2 & 3]
       )
     }
     for (oi = 4; oi;) {
@@ -106,7 +106,8 @@ let inputToBinl = (
       ? input = new TextEncoder().encode(input)
       : input
   ).length,
-  // Using Array would fail to handle large files, so Int32Array must be used.
+  // Using `Array` to process inputs over 512 MiB could throw a `RangeError`,
+  // so I replaced it with `Int32Array`.
   output = new Int32Array(toBinlLen(j * 4 + byteLen)),
   i = 0,
 ) => {
@@ -162,8 +163,8 @@ var md5 = (data, key, raw) => {
       bkey = binlMD5(bkey, keyByteLen)
     }
     for (; i;) {
-      bdata[--i] = 0x36363636 ^ bkey[i] // ipad
-      opad[i] = 0x5c5c5c5c ^ bkey[i]
+      // (0x36363636 ^ 0x5c5c5c5c) == 0x6a6a6a6a
+      opad[--i] = 0x6a6a6a6a ^ (bdata[i] = 0x36363636 ^ bkey[i])
     }
     i = 16
     bdata = binlMD5(bdata, 64 + dataByteLen)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tinyhmacmd5",
-  "version": "0.1.1",
-  "description": "A tiny JavaScript HMAC-MD5 implementation. The minified browser bundle is only 1057 bytes.",
+  "version": "0.1.3",
+  "description": "A tiny, fully compliant HMAC-MD5 implementation for JavaScript: browser.min.js is only 1051 bytes.",
   "author": "bddjr",
   "license": "MIT",
   "type": "module",
@@ -16,14 +16,21 @@
   "homepage": "https://bddjr.github.io/tinyhmacmd5/",
   "keywords": [
     "md5",
+    "hash",
     "hmac",
     "hmacmd5",
     "hmac-md5",
     "tiny",
     "hex",
     "crypto",
+    "encryption",
+    "cryptography",
     "blueimp",
-    "blueimp-md5"
+    "blueimp-md5",
+    "js-md5",
+    "crypto-js",
+    "javascript",
+    "typescript"
   ],
   "repository": {
     "type": "git",
@@ -37,6 +44,9 @@
   },
   "scripts": {
     "build": "tsc && node scripts/build.mjs && es-check es2021 --module --checkFeatures main.js browser.min.js",
-    "test": "pnpm build && node scripts/test.mjs"
+    "build:unchanged": "node scripts/build-unchanged.mjs",
+    "test": "pnpm build && pnpm test:only",
+    "test:only": "node scripts/test.mjs",
+    "test:unchanged": "pnpm build:unchanged && pnpm test:only"
   }
 }