@couch-kit/core 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @couch-kit/core
 
+## 0.9.2
+
+### Patch Changes
+
+- [#85](https://github.com/faluciano/react-native-couch-kit/pull/85) [`0064a42`](https://github.com/faluciano/react-native-couch-kit/commit/0064a42e0593d2ed2734c27926c5df686dcf3b5f) Thanks [@faluciano](https://github.com/faluciano)! - **Security:** Derive public player IDs with a real SHA-256 on React Native / Hermes.
+
+  `derivePlayerId` hashes the session secret with SHA-256 via the Web Crypto API,
+  but Hermes (where the host runs) does not expose `crypto.subtle`. The previous
+  fallback used `derivePlayerIdLegacy`, which simply truncated the secret —
+  exposing the first half of the raw session token as the public `playerId`
+  broadcast in game state.
+
+  The fallback now uses a dependency-free pure-JS SHA-256 that produces the exact
+  same digest as `crypto.subtle`, so player IDs are secure and identical across
+  all host runtimes. `derivePlayerIdLegacy` is retained only for reconnect
+  migration of players who joined under the old scheme.
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -190,9 +190,9 @@ try {
 
 Validates that a string is a valid UUID format (32+ hex characters, with or without dashes).
 
-#### `derivePlayerId(secret: string): string`
+#### `derivePlayerId(secret: string): Promise<string>`
 
-Derives a stable, public player ID from a secret UUID by stripping dashes and taking the first 16 hex characters.
+Derives a stable, public player ID from a secret UUID using SHA-256, taking the first 16 hex characters of the hash. Async because it uses the Web Crypto `crypto.subtle.digest` API.
 
 ### Constants
 

package/dist/index.cjs

@@ -217,6 +217,148 @@ var MessageTypes = {
   RECONNECTED: "RECONNECTED",
   ERROR: "ERROR"
 };
+// src/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function utf8Bytes(str) {
+  const bytes = [];
+  for (let i = 0;i < str.length; i++) {
+    let code = str.charCodeAt(i);
+    if (code >= 55296 && code <= 56319 && i + 1 < str.length) {
+      const next = str.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        code = 65536 + (code - 55296 << 10) + (next - 56320);
+        i++;
+      }
+    }
+    if (code < 128) {
+      bytes.push(code);
+    } else if (code < 2048) {
+      bytes.push(192 | code >> 6, 128 | code & 63);
+    } else if (code < 65536) {
+      bytes.push(224 | code >> 12, 128 | code >> 6 & 63, 128 | code & 63);
+    } else {
+      bytes.push(240 | code >> 18, 128 | code >> 12 & 63, 128 | code >> 6 & 63, 128 | code & 63);
+    }
+  }
+  return bytes;
+}
+var rotr = (x, n) => x >>> n | x << 32 - n;
+function sha256Hex(message) {
+  const bytes = utf8Bytes(message);
+  const bitLen = bytes.length * 8;
+  bytes.push(128);
+  while (bytes.length % 64 !== 56)
+    bytes.push(0);
+  const hi = Math.floor(bitLen / 4294967296);
+  const lo = bitLen >>> 0;
+  bytes.push(hi >>> 24 & 255, hi >>> 16 & 255, hi >>> 8 & 255, hi & 255, lo >>> 24 & 255, lo >>> 16 & 255, lo >>> 8 & 255, lo & 255);
+  let h0 = 1779033703, h1 = 3144134277, h2 = 1013904242, h3 = 2773480762, h4 = 1359893119, h5 = 2600822924, h6 = 528734635, h7 = 1541459225;
+  const w = new Uint32Array(64);
+  for (let offset = 0;offset < bytes.length; offset += 64) {
+    for (let i = 0;i < 16; i++) {
+      const j = offset + i * 4;
+      w[i] = (bytes[j] << 24 | bytes[j + 1] << 16 | bytes[j + 2] << 8 | bytes[j + 3]) >>> 0;
+    }
+    for (let i = 16;i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ w[i - 15] >>> 3;
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ w[i - 2] >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 >>> 0;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let i = 0;i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const temp1 = h + S1 + ch + K[i] + w[i] >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = a & b ^ a & c ^ b & c;
+      const temp2 = S0 + maj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    h0 = h0 + a >>> 0;
+    h1 = h1 + b >>> 0;
+    h2 = h2 + c >>> 0;
+    h3 = h3 + d >>> 0;
+    h4 = h4 + e >>> 0;
+    h5 = h5 + f >>> 0;
+    h6 = h6 + g >>> 0;
+    h7 = h7 + h >>> 0;
+  }
+  const toHex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+  return toHex(h0) + toHex(h1) + toHex(h2) + toHex(h3) + toHex(h4) + toHex(h5) + toHex(h6) + toHex(h7);
+}
+
 // src/constants.ts
 var DEFAULT_HTTP_PORT = 8080;
 var DEFAULT_WS_PORT_OFFSET = 2;
@@ -253,7 +395,7 @@ async function derivePlayerId(secret) {
     const hash = await globalThis.crypto.subtle.digest("SHA-256", data);
     return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 16);
   }
-  return derivePlayerIdLegacy(secret);
+  return sha256Hex(secret).slice(0, 16);
 }
 function derivePlayerIdLegacy(secret) {
   return secret.replace(/-/g, "").slice(0, 16);

package/dist/index.js

@@ -159,6 +159,148 @@ var MessageTypes = {
   RECONNECTED: "RECONNECTED",
   ERROR: "ERROR"
 };
+// src/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function utf8Bytes(str) {
+  const bytes = [];
+  for (let i = 0;i < str.length; i++) {
+    let code = str.charCodeAt(i);
+    if (code >= 55296 && code <= 56319 && i + 1 < str.length) {
+      const next = str.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        code = 65536 + (code - 55296 << 10) + (next - 56320);
+        i++;
+      }
+    }
+    if (code < 128) {
+      bytes.push(code);
+    } else if (code < 2048) {
+      bytes.push(192 | code >> 6, 128 | code & 63);
+    } else if (code < 65536) {
+      bytes.push(224 | code >> 12, 128 | code >> 6 & 63, 128 | code & 63);
+    } else {
+      bytes.push(240 | code >> 18, 128 | code >> 12 & 63, 128 | code >> 6 & 63, 128 | code & 63);
+    }
+  }
+  return bytes;
+}
+var rotr = (x, n) => x >>> n | x << 32 - n;
+function sha256Hex(message) {
+  const bytes = utf8Bytes(message);
+  const bitLen = bytes.length * 8;
+  bytes.push(128);
+  while (bytes.length % 64 !== 56)
+    bytes.push(0);
+  const hi = Math.floor(bitLen / 4294967296);
+  const lo = bitLen >>> 0;
+  bytes.push(hi >>> 24 & 255, hi >>> 16 & 255, hi >>> 8 & 255, hi & 255, lo >>> 24 & 255, lo >>> 16 & 255, lo >>> 8 & 255, lo & 255);
+  let h0 = 1779033703, h1 = 3144134277, h2 = 1013904242, h3 = 2773480762, h4 = 1359893119, h5 = 2600822924, h6 = 528734635, h7 = 1541459225;
+  const w = new Uint32Array(64);
+  for (let offset = 0;offset < bytes.length; offset += 64) {
+    for (let i = 0;i < 16; i++) {
+      const j = offset + i * 4;
+      w[i] = (bytes[j] << 24 | bytes[j + 1] << 16 | bytes[j + 2] << 8 | bytes[j + 3]) >>> 0;
+    }
+    for (let i = 16;i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ w[i - 15] >>> 3;
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ w[i - 2] >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 >>> 0;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let i = 0;i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const temp1 = h + S1 + ch + K[i] + w[i] >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = a & b ^ a & c ^ b & c;
+      const temp2 = S0 + maj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    h0 = h0 + a >>> 0;
+    h1 = h1 + b >>> 0;
+    h2 = h2 + c >>> 0;
+    h3 = h3 + d >>> 0;
+    h4 = h4 + e >>> 0;
+    h5 = h5 + f >>> 0;
+    h6 = h6 + g >>> 0;
+    h7 = h7 + h >>> 0;
+  }
+  const toHex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+  return toHex(h0) + toHex(h1) + toHex(h2) + toHex(h3) + toHex(h4) + toHex(h5) + toHex(h6) + toHex(h7);
+}
+
 // src/constants.ts
 var DEFAULT_HTTP_PORT = 8080;
 var DEFAULT_WS_PORT_OFFSET = 2;
@@ -195,7 +337,7 @@ async function derivePlayerId(secret) {
     const hash = await globalThis.crypto.subtle.digest("SHA-256", data);
     return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 16);
   }
-  return derivePlayerIdLegacy(secret);
+  return sha256Hex(secret).slice(0, 16);
 }
 function derivePlayerIdLegacy(secret) {
   return secret.replace(/-/g, "").slice(0, 16);

package/lib/constants.d.ts

@@ -40,8 +40,11 @@ export declare function isValidSecret(secret: string): boolean;
  * Takes the first 16 hex characters of the SHA-256 hash, producing
  * a deterministic ID that cannot be reversed to recover the secret.
  *
- * Falls back to {@link derivePlayerIdLegacy} when the Web Crypto API
- * (`crypto.subtle`) is unavailable (e.g. React Native / Hermes).
+ * Uses the Web Crypto API (`crypto.subtle`) when available (browser / Node),
+ * and a dependency-free pure-JS SHA-256 fallback otherwise (e.g. React Native
+ * / Hermes, which does not expose `crypto.subtle`). Both paths produce the
+ * same digest, so the derived ID is identical across host runtimes and never
+ * leaks any part of the secret.
  */
 export declare function derivePlayerId(secret: string): Promise<string>;
 /**

package/lib/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,0DAA0D;AAC1D,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,8FAA8F;AAC9F,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,QAAgB,CAAC;AAExD,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAwBnC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAepE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAKxD,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,0DAA0D;AAC1D,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,8FAA8F;AAC9F,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,QAAgB,CAAC;AAExD,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAwBnC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBpE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD"}

package/lib/sha256.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dependency-free SHA-256 implementation.
+ *
+ * Couch Kit derives public player IDs from a secret using SHA-256. Browsers and
+ * Node expose this via the Web Crypto API (`crypto.subtle.digest`), but React
+ * Native / Hermes — where the host actually runs — does **not** provide
+ * `crypto.subtle` by default. This pure-JS implementation is used as the
+ * fallback so the host still produces a proper one-way hash instead of leaking
+ * part of the secret. It is byte-for-byte compatible with
+ * `crypto.subtle.digest("SHA-256", ...)`, so player IDs are stable regardless
+ * of which runtime the host uses.
+ */
+/**
+ * Compute the SHA-256 digest of a UTF-8 string.
+ *
+ * @param message - The string to hash.
+ * @returns Lowercase hex-encoded 256-bit digest (64 characters).
+ */
+export declare function sha256Hex(message: string): string;
+//# sourceMappingURL=sha256.d.ts.map

package/lib/sha256.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256.d.ts","sourceRoot":"","sources":["../src/sha256.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoDH;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmGjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/core",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -50,6 +50,6 @@
     "clean": "rm -rf dist lib"
   },
   "devDependencies": {
-    "typescript": "^5.4.0"
+    "typescript": "^6.0.0"
   }
 }

package/src/constants.ts

@@ -1,5 +1,8 @@
 /** Shared constants for Couch Kit protocol defaults. */
 
+import { sha256Hex } from "./sha256";
+
+
 /** Default HTTP port for the static file server. */
 export const DEFAULT_HTTP_PORT = 8080;
 
@@ -82,8 +85,11 @@ export function isValidSecret(secret: string): boolean {
  * Takes the first 16 hex characters of the SHA-256 hash, producing
  * a deterministic ID that cannot be reversed to recover the secret.
  *
- * Falls back to {@link derivePlayerIdLegacy} when the Web Crypto API
- * (`crypto.subtle`) is unavailable (e.g. React Native / Hermes).
+ * Uses the Web Crypto API (`crypto.subtle`) when available (browser / Node),
+ * and a dependency-free pure-JS SHA-256 fallback otherwise (e.g. React Native
+ * / Hermes, which does not expose `crypto.subtle`). Both paths produce the
+ * same digest, so the derived ID is identical across host runtimes and never
+ * leaks any part of the secret.
  */
 export async function derivePlayerId(secret: string): Promise<string> {
   if (
@@ -98,8 +104,10 @@ export async function derivePlayerId(secret: string): Promise<string> {
       .slice(0, 16);
   }
 
-  // Web Crypto unavailable (React Native / Hermes) — fall back to legacy derivation
-  return derivePlayerIdLegacy(secret);
+  // Web Crypto unavailable (React Native / Hermes) — use the pure-JS SHA-256
+  // fallback. This still produces a secure one-way hash (unlike the deprecated
+  // legacy derivation, which exposed the first half of the secret).
+  return sha256Hex(secret).slice(0, 16);
 }
 
 /**

package/src/sha256.ts

@@ -0,0 +1,169 @@
+/**
+ * Dependency-free SHA-256 implementation.
+ *
+ * Couch Kit derives public player IDs from a secret using SHA-256. Browsers and
+ * Node expose this via the Web Crypto API (`crypto.subtle.digest`), but React
+ * Native / Hermes — where the host actually runs — does **not** provide
+ * `crypto.subtle` by default. This pure-JS implementation is used as the
+ * fallback so the host still produces a proper one-way hash instead of leaking
+ * part of the secret. It is byte-for-byte compatible with
+ * `crypto.subtle.digest("SHA-256", ...)`, so player IDs are stable regardless
+ * of which runtime the host uses.
+ */
+
+/** Round constants (first 32 bits of the fractional parts of the cube roots of the first 64 primes). */
+// prettier-ignore
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+/** Encode a JS string as UTF-8 bytes without relying on the global `TextEncoder`. */
+function utf8Bytes(str: string): number[] {
+  const bytes: number[] = [];
+  for (let i = 0; i < str.length; i++) {
+    let code = str.charCodeAt(i);
+    // Combine surrogate pairs into a single code point.
+    if (code >= 0xd800 && code <= 0xdbff && i + 1 < str.length) {
+      const next = str.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+        i++;
+      }
+    }
+    if (code < 0x80) {
+      bytes.push(code);
+    } else if (code < 0x800) {
+      bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    } else if (code < 0x10000) {
+      bytes.push(
+        0xe0 | (code >> 12),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+    } else {
+      bytes.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+    }
+  }
+  return bytes;
+}
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+/**
+ * Compute the SHA-256 digest of a UTF-8 string.
+ *
+ * @param message - The string to hash.
+ * @returns Lowercase hex-encoded 256-bit digest (64 characters).
+ */
+export function sha256Hex(message: string): string {
+  const bytes = utf8Bytes(message);
+  const bitLen = bytes.length * 8;
+
+  // Padding: append 0x80, then zeros, then the 64-bit big-endian length.
+  bytes.push(0x80);
+  while (bytes.length % 64 !== 56) bytes.push(0);
+  // 64-bit length. JS bitwise ops are 32-bit, so split high/low words.
+  const hi = Math.floor(bitLen / 0x100000000);
+  const lo = bitLen >>> 0;
+  bytes.push(
+    (hi >>> 24) & 0xff,
+    (hi >>> 16) & 0xff,
+    (hi >>> 8) & 0xff,
+    hi & 0xff,
+    (lo >>> 24) & 0xff,
+    (lo >>> 16) & 0xff,
+    (lo >>> 8) & 0xff,
+    lo & 0xff,
+  );
+
+  // Initial hash values (fractional parts of square roots of first 8 primes).
+  let h0 = 0x6a09e667,
+    h1 = 0xbb67ae85,
+    h2 = 0x3c6ef372,
+    h3 = 0xa54ff53a,
+    h4 = 0x510e527f,
+    h5 = 0x9b05688c,
+    h6 = 0x1f83d9ab,
+    h7 = 0x5be0cd19;
+
+  const w = new Uint32Array(64);
+
+  for (let offset = 0; offset < bytes.length; offset += 64) {
+    for (let i = 0; i < 16; i++) {
+      const j = offset + i * 4;
+      w[i] =
+        ((bytes[j] << 24) |
+          (bytes[j + 1] << 16) |
+          (bytes[j + 2] << 8) |
+          bytes[j + 3]) >>>
+        0;
+    }
+    for (let i = 16; i < 64; i++) {
+      const s0 =
+        rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 =
+        rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+
+    let a = h0,
+      b = h1,
+      c = h2,
+      d = h3,
+      e = h4,
+      f = h5,
+      g = h6,
+      h = h7;
+
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const temp1 = (h + S1 + ch + K[i] + w[i]) >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (S0 + maj) >>> 0;
+
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temp1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) >>> 0;
+    }
+
+    h0 = (h0 + a) >>> 0;
+    h1 = (h1 + b) >>> 0;
+    h2 = (h2 + c) >>> 0;
+    h3 = (h3 + d) >>> 0;
+    h4 = (h4 + e) >>> 0;
+    h5 = (h5 + f) >>> 0;
+    h6 = (h6 + g) >>> 0;
+    h7 = (h7 + h) >>> 0;
+  }
+
+  const toHex = (n: number): string => (n >>> 0).toString(16).padStart(8, "0");
+  return (
+    toHex(h0) +
+    toHex(h1) +
+    toHex(h2) +
+    toHex(h3) +
+    toHex(h4) +
+    toHex(h5) +
+    toHex(h6) +
+    toHex(h7)
+  );
+}