@scalebun/react-native 1.0.2 → 1.0.3

package/src/core/logger/errorClassification.ts

@@ -1,108 +1,108 @@
-/**
- * ScaleBun SDK — Error Classification
- *
- * Pure helpers that classify transport/flush failures so the SDK can decide
- * whether an error is a normal, recoverable condition (request aborted,
- * timeout, offline, backend temporarily down) or a genuine fatal integration
- * bug that the host developer must act on.
- *
- * Recoverable errors MUST NOT be logged through `console.error` — in React
- * Native that triggers a LogBox / RedBox overlay for what is really a routine
- * retry. See `internalLogger` for how levels map to console methods.
- */
-
-/** Reason codes describing why a flush/transport attempt failed. */
-export type FailureReason =
-    | 'request_aborted'
-    | 'timeout'
-    | 'offline'
-    | 'server_error'
-    | 'unknown';
-
-function nameOf(error: unknown): string {
-    if (error && typeof error === 'object' && 'name' in error) {
-        return String((error as { name?: unknown }).name ?? '');
-    }
-    return '';
-}
-
-function messageOf(error: unknown): string {
-    if (error && typeof error === 'object' && 'message' in error) {
-        return String((error as { message?: unknown }).message ?? '');
-    }
-    return typeof error === 'string' ? error : '';
-}
-
-/**
- * AbortError — the request was cancelled via an AbortController. This happens
- * on intentional cancel, app backgrounding, navigation interruption, or a
- * timeout that aborts the underlying fetch.
- */
-export function isAbortError(error: unknown): boolean {
-    if (nameOf(error) === 'AbortError') return true;
-    // Some RN/fetch polyfills surface aborts only via message text.
-    return /\baborted\b/i.test(messageOf(error));
-}
-
-/** Timeout — the SDK aborted the request because it exceeded the deadline. */
-export function isTimeoutError(error: unknown): boolean {
-    if (nameOf(error) === 'TimeoutError') return true;
-    if (error && typeof error === 'object' && (error as { isTimeout?: unknown }).isTimeout === true) {
-        return true;
-    }
-    return /\btimed?\s*out\b/i.test(messageOf(error));
-}
-
-/**
- * Network error — device offline or the backend host is unreachable. RN's
- * fetch rejects with a generic `TypeError: Network request failed`.
- */
-export function isNetworkError(error: unknown): boolean {
-    const msg = messageOf(error).toLowerCase();
-    return (
-        nameOf(error) === 'NetworkError' ||
-        msg.includes('network request failed') ||
-        msg.includes('failed to fetch') ||
-        msg.includes('network error') ||
-        msg.includes('connection') && msg.includes('refused')
-    );
-}
-
-/**
- * Recoverable flush error — the events were not delivered but can safely be
- * returned to the queue and retried later. Covers abort, timeout, offline,
- * and transient backend unavailability (HTTP 5xx / 429).
- *
- * `status` is the HTTP status when the transport returned a response (used to
- * treat 5xx and 429 as recoverable).
- */
-export function isRecoverableFlushError(error: unknown, status?: number): boolean {
-    if (isAbortError(error) || isTimeoutError(error) || isNetworkError(error)) {
-        return true;
-    }
-    if (typeof status === 'number' && (status >= 500 || status === 429)) {
-        return true;
-    }
-    return false;
-}
-
-/**
- * Fatal SDK error — not recoverable by retrying. Today this means anything we
- * could not classify as recoverable. Used to decide whether to surface via
- * `console.error`. Callers may pass a known HTTP `status` to keep client
- * errors (4xx, except 429) classified as fatal/actionable.
- */
-export function isFatalSdkError(error: unknown, status?: number): boolean {
-    return !isRecoverableFlushError(error, status);
-}
-
-/** Human-readable reason code for logs and internal status. */
-export function describeErrorReason(error: unknown, status?: number): FailureReason {
-    if (isTimeoutError(error)) return 'timeout';
-    if (isAbortError(error)) return 'request_aborted';
-    if (isNetworkError(error)) return 'offline';
-    if (typeof status === 'number' && (status >= 500 || status === 429)) {
-        return 'server_error';
-    }
-    return 'unknown';
-}
+/**
+ * ScaleBun SDK — Error Classification
+ *
+ * Pure helpers that classify transport/flush failures so the SDK can decide
+ * whether an error is a normal, recoverable condition (request aborted,
+ * timeout, offline, backend temporarily down) or a genuine fatal integration
+ * bug that the host developer must act on.
+ *
+ * Recoverable errors MUST NOT be logged through `console.error` — in React
+ * Native that triggers a LogBox / RedBox overlay for what is really a routine
+ * retry. See `internalLogger` for how levels map to console methods.
+ */
+
+/** Reason codes describing why a flush/transport attempt failed. */
+export type FailureReason =
+    | 'request_aborted'
+    | 'timeout'
+    | 'offline'
+    | 'server_error'
+    | 'unknown';
+
+function nameOf(error: unknown): string {
+    if (error && typeof error === 'object' && 'name' in error) {
+        return String((error as { name?: unknown }).name ?? '');
+    }
+    return '';
+}
+
+function messageOf(error: unknown): string {
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String((error as { message?: unknown }).message ?? '');
+    }
+    return typeof error === 'string' ? error : '';
+}
+
+/**
+ * AbortError — the request was cancelled via an AbortController. This happens
+ * on intentional cancel, app backgrounding, navigation interruption, or a
+ * timeout that aborts the underlying fetch.
+ */
+export function isAbortError(error: unknown): boolean {
+    if (nameOf(error) === 'AbortError') return true;
+    // Some RN/fetch polyfills surface aborts only via message text.
+    return /\baborted\b/i.test(messageOf(error));
+}
+
+/** Timeout — the SDK aborted the request because it exceeded the deadline. */
+export function isTimeoutError(error: unknown): boolean {
+    if (nameOf(error) === 'TimeoutError') return true;
+    if (error && typeof error === 'object' && (error as { isTimeout?: unknown }).isTimeout === true) {
+        return true;
+    }
+    return /\btimed?\s*out\b/i.test(messageOf(error));
+}
+
+/**
+ * Network error — device offline or the backend host is unreachable. RN's
+ * fetch rejects with a generic `TypeError: Network request failed`.
+ */
+export function isNetworkError(error: unknown): boolean {
+    const msg = messageOf(error).toLowerCase();
+    return (
+        nameOf(error) === 'NetworkError' ||
+        msg.includes('network request failed') ||
+        msg.includes('failed to fetch') ||
+        msg.includes('network error') ||
+        msg.includes('connection') && msg.includes('refused')
+    );
+}
+
+/**
+ * Recoverable flush error — the events were not delivered but can safely be
+ * returned to the queue and retried later. Covers abort, timeout, offline,
+ * and transient backend unavailability (HTTP 5xx / 429).
+ *
+ * `status` is the HTTP status when the transport returned a response (used to
+ * treat 5xx and 429 as recoverable).
+ */
+export function isRecoverableFlushError(error: unknown, status?: number): boolean {
+    if (isAbortError(error) || isTimeoutError(error) || isNetworkError(error)) {
+        return true;
+    }
+    if (typeof status === 'number' && (status >= 500 || status === 429)) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Fatal SDK error — not recoverable by retrying. Today this means anything we
+ * could not classify as recoverable. Used to decide whether to surface via
+ * `console.error`. Callers may pass a known HTTP `status` to keep client
+ * errors (4xx, except 429) classified as fatal/actionable.
+ */
+export function isFatalSdkError(error: unknown, status?: number): boolean {
+    return !isRecoverableFlushError(error, status);
+}
+
+/** Human-readable reason code for logs and internal status. */
+export function describeErrorReason(error: unknown, status?: number): FailureReason {
+    if (isTimeoutError(error)) return 'timeout';
+    if (isAbortError(error)) return 'request_aborted';
+    if (isNetworkError(error)) return 'offline';
+    if (typeof status === 'number' && (status >= 500 || status === 429)) {
+        return 'server_error';
+    }
+    return 'unknown';
+}

package/src/core/logger/internalLogger.ts

@@ -1,65 +1,65 @@
-export enum LogLevel {
-    DEBUG = 0,
-    INFO = 1,
-    WARN = 2,
-    ERROR = 3,
-    NONE = 4,
-}
-
-/** Public, string-based log level used in SDK init config. */
-export type LogLevelName = 'silent' | 'error' | 'warn' | 'info' | 'debug';
-
-const LEVEL_BY_NAME: Record<LogLevelName, LogLevel> = {
-    silent: LogLevel.NONE,
-    error: LogLevel.ERROR,
-    warn: LogLevel.WARN,
-    info: LogLevel.INFO,
-    debug: LogLevel.DEBUG,
-};
-
-class InternalLogger {
-    private level: LogLevel = LogLevel.WARN;
-
-    setLevel(level: LogLevel) {
-        this.level = level;
-    }
-
-    /** Set level from the public string name used in config (e.g. 'warn'). */
-    setLevelByName(name: LogLevelName) {
-        const resolved = LEVEL_BY_NAME[name];
-        if (resolved !== undefined) {
-            this.level = resolved;
-        }
-    }
-
-    /** Current numeric level — exposed for callers that branch on dev verbosity. */
-    getLevel(): LogLevel {
-        return this.level;
-    }
-
-    debug(...args: any[]) {
-        if (this.level <= LogLevel.DEBUG) {
-            console.debug('[ScaleBun:Debug]', ...args);
-        }
-    }
-
-    info(...args: any[]) {
-        if (this.level <= LogLevel.INFO) {
-            console.info('[ScaleBun:Info]', ...args);
-        }
-    }
-
-    warn(...args: any[]) {
-        if (this.level <= LogLevel.WARN) {
-            console.warn('[ScaleBun:Warn]', ...args);
-        }
-    }
-
-    error(...args: any[]) {
-        if (this.level <= LogLevel.ERROR) {
-            console.error('[ScaleBun:Error]', ...args);
-        }
-    }
-}
-
-export const logger = new InternalLogger();
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4,
+}
+
+/** Public, string-based log level used in SDK init config. */
+export type LogLevelName = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+
+const LEVEL_BY_NAME: Record<LogLevelName, LogLevel> = {
+    silent: LogLevel.NONE,
+    error: LogLevel.ERROR,
+    warn: LogLevel.WARN,
+    info: LogLevel.INFO,
+    debug: LogLevel.DEBUG,
+};
+
+class InternalLogger {
+    private level: LogLevel = LogLevel.WARN;
+
+    setLevel(level: LogLevel) {
+        this.level = level;
+    }
+
+    /** Set level from the public string name used in config (e.g. 'warn'). */
+    setLevelByName(name: LogLevelName) {
+        const resolved = LEVEL_BY_NAME[name];
+        if (resolved !== undefined) {
+            this.level = resolved;
+        }
+    }
+
+    /** Current numeric level — exposed for callers that branch on dev verbosity. */
+    getLevel(): LogLevel {
+        return this.level;
+    }
+
+    debug(...args: any[]) {
+        if (this.level <= LogLevel.DEBUG) {
+            console.debug('[ScaleBun:Debug]', ...args);
+        }
+    }
+
+    info(...args: any[]) {
+        if (this.level <= LogLevel.INFO) {
+            console.info('[ScaleBun:Info]', ...args);
+        }
+    }
+
+    warn(...args: any[]) {
+        if (this.level <= LogLevel.WARN) {
+            console.warn('[ScaleBun:Warn]', ...args);
+        }
+    }
+
+    error(...args: any[]) {
+        if (this.level <= LogLevel.ERROR) {
+            console.error('[ScaleBun:Error]', ...args);
+        }
+    }
+}
+
+export const logger = new InternalLogger();

package/src/crypto/hmacSha256.ts

@@ -1,106 +1,106 @@
-/**
- * Pure-JS HMAC-SHA256 (Phase 5.4) — no native module, so it runs identically on the
- * Old and New RN architectures and in Node. Output matches Node's
- * `crypto.createHmac('sha256', key).update(msg).digest('hex')` (asserted in tests).
- *
- * Used to sign the /batch envelope so the backend can tamper-detect the payload.
- */
-
-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,
-]);
-
-const rotr = (x: number, n: number) => (x >>> n) | (x << (32 - n));
-
-/** Manual UTF-8 encode (no TextEncoder dependency — matches Node's utf8 byte output). */
-function utf8(str: string): Uint8Array {
-  const out: number[] = [];
-  for (let i = 0; i < str.length; i++) {
-    const c = str.charCodeAt(i);
-    if (c < 0x80) out.push(c);
-    else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
-    else if (c >= 0xd800 && c <= 0xdbff) {
-      const c2 = str.charCodeAt(++i);
-      const cp = 0x10000 + ((c & 0x3ff) << 10) + (c2 & 0x3ff);
-      out.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 0x3f), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
-    } else {
-      out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
-    }
-  }
-  return new Uint8Array(out);
-}
-
-function sha256(msg: Uint8Array): Uint8Array {
-  const H = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
-  const l = msg.length;
-  const bitLen = l * 8;
-  const withOne = l + 1;
-  const pad = (56 - (withOne % 64) + 64) % 64;
-  const total = withOne + pad + 8;
-  const m = new Uint8Array(total);
-  m.set(msg);
-  m[l] = 0x80;
-  const hi = Math.floor(bitLen / 0x100000000);
-  const lo = bitLen >>> 0;
-  m[total - 8] = (hi >>> 24) & 0xff; m[total - 7] = (hi >>> 16) & 0xff; m[total - 6] = (hi >>> 8) & 0xff; m[total - 5] = hi & 0xff;
-  m[total - 4] = (lo >>> 24) & 0xff; m[total - 3] = (lo >>> 16) & 0xff; m[total - 2] = (lo >>> 8) & 0xff; m[total - 1] = lo & 0xff;
-
-  const w = new Uint32Array(64);
-  for (let off = 0; off < total; off += 64) {
-    for (let i = 0; i < 16; i++) {
-      w[i] = ((m[off + i * 4] << 24) | (m[off + i * 4 + 1] << 16) | (m[off + i * 4 + 2] << 8) | m[off + i * 4 + 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 = H[0], b = H[1], c = H[2], d = H[3], e = H[4], f = H[5], g = H[6], h = H[7];
-    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 t1 = (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 t2 = (S0 + maj) >>> 0;
-      h = g; g = f; f = e; e = (d + t1) >>> 0; d = c; c = b; b = a; a = (t1 + t2) >>> 0;
-    }
-    H[0] = (H[0] + a) >>> 0; H[1] = (H[1] + b) >>> 0; H[2] = (H[2] + c) >>> 0; H[3] = (H[3] + d) >>> 0;
-    H[4] = (H[4] + e) >>> 0; H[5] = (H[5] + f) >>> 0; H[6] = (H[6] + g) >>> 0; H[7] = (H[7] + h) >>> 0;
-  }
-  const out = new Uint8Array(32);
-  for (let i = 0; i < 8; i++) { out[i * 4] = (H[i] >>> 24) & 0xff; out[i * 4 + 1] = (H[i] >>> 16) & 0xff; out[i * 4 + 2] = (H[i] >>> 8) & 0xff; out[i * 4 + 3] = H[i] & 0xff; }
-  return out;
-}
-
-function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
-  const out = new Uint8Array(a.length + b.length);
-  out.set(a); out.set(b, a.length);
-  return out;
-}
-
-function toHex(bytes: Uint8Array): string {
-  let s = '';
-  for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0');
-  return s;
-}
-
-/** HMAC-SHA256(key, message) → lowercase hex. */
-export function hmacSha256Hex(key: string, message: string): string {
-  let k = utf8(key);
-  if (k.length > 64) k = sha256(k);
-  const block = new Uint8Array(64);
-  block.set(k);
-  const ipad = new Uint8Array(64);
-  const opad = new Uint8Array(64);
-  for (let i = 0; i < 64; i++) { ipad[i] = block[i] ^ 0x36; opad[i] = block[i] ^ 0x5c; }
-  const inner = sha256(concat(ipad, utf8(message)));
-  return toHex(sha256(concat(opad, inner)));
-}
+/**
+ * Pure-JS HMAC-SHA256 (Phase 5.4) — no native module, so it runs identically on the
+ * Old and New RN architectures and in Node. Output matches Node's
+ * `crypto.createHmac('sha256', key).update(msg).digest('hex')` (asserted in tests).
+ *
+ * Used to sign the /batch envelope so the backend can tamper-detect the payload.
+ */
+
+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,
+]);
+
+const rotr = (x: number, n: number) => (x >>> n) | (x << (32 - n));
+
+/** Manual UTF-8 encode (no TextEncoder dependency — matches Node's utf8 byte output). */
+function utf8(str: string): Uint8Array {
+  const out: number[] = [];
+  for (let i = 0; i < str.length; i++) {
+    const c = str.charCodeAt(i);
+    if (c < 0x80) out.push(c);
+    else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
+    else if (c >= 0xd800 && c <= 0xdbff) {
+      const c2 = str.charCodeAt(++i);
+      const cp = 0x10000 + ((c & 0x3ff) << 10) + (c2 & 0x3ff);
+      out.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 0x3f), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
+    } else {
+      out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+    }
+  }
+  return new Uint8Array(out);
+}
+
+function sha256(msg: Uint8Array): Uint8Array {
+  const H = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+  const l = msg.length;
+  const bitLen = l * 8;
+  const withOne = l + 1;
+  const pad = (56 - (withOne % 64) + 64) % 64;
+  const total = withOne + pad + 8;
+  const m = new Uint8Array(total);
+  m.set(msg);
+  m[l] = 0x80;
+  const hi = Math.floor(bitLen / 0x100000000);
+  const lo = bitLen >>> 0;
+  m[total - 8] = (hi >>> 24) & 0xff; m[total - 7] = (hi >>> 16) & 0xff; m[total - 6] = (hi >>> 8) & 0xff; m[total - 5] = hi & 0xff;
+  m[total - 4] = (lo >>> 24) & 0xff; m[total - 3] = (lo >>> 16) & 0xff; m[total - 2] = (lo >>> 8) & 0xff; m[total - 1] = lo & 0xff;
+
+  const w = new Uint32Array(64);
+  for (let off = 0; off < total; off += 64) {
+    for (let i = 0; i < 16; i++) {
+      w[i] = ((m[off + i * 4] << 24) | (m[off + i * 4 + 1] << 16) | (m[off + i * 4 + 2] << 8) | m[off + i * 4 + 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 = H[0], b = H[1], c = H[2], d = H[3], e = H[4], f = H[5], g = H[6], h = H[7];
+    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 t1 = (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 t2 = (S0 + maj) >>> 0;
+      h = g; g = f; f = e; e = (d + t1) >>> 0; d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    H[0] = (H[0] + a) >>> 0; H[1] = (H[1] + b) >>> 0; H[2] = (H[2] + c) >>> 0; H[3] = (H[3] + d) >>> 0;
+    H[4] = (H[4] + e) >>> 0; H[5] = (H[5] + f) >>> 0; H[6] = (H[6] + g) >>> 0; H[7] = (H[7] + h) >>> 0;
+  }
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 8; i++) { out[i * 4] = (H[i] >>> 24) & 0xff; out[i * 4 + 1] = (H[i] >>> 16) & 0xff; out[i * 4 + 2] = (H[i] >>> 8) & 0xff; out[i * 4 + 3] = H[i] & 0xff; }
+  return out;
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a); out.set(b, a.length);
+  return out;
+}
+
+function toHex(bytes: Uint8Array): string {
+  let s = '';
+  for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0');
+  return s;
+}
+
+/** HMAC-SHA256(key, message) → lowercase hex. */
+export function hmacSha256Hex(key: string, message: string): string {
+  let k = utf8(key);
+  if (k.length > 64) k = sha256(k);
+  const block = new Uint8Array(64);
+  block.set(k);
+  const ipad = new Uint8Array(64);
+  const opad = new Uint8Array(64);
+  for (let i = 0; i < 64; i++) { ipad[i] = block[i] ^ 0x36; opad[i] = block[i] ^ 0x5c; }
+  const inner = sha256(concat(ipad, utf8(message)));
+  return toHex(sha256(concat(opad, inner)));
+}