iframe-tracking-sdk 1.0.0

package/dist/processor.d.ts

@@ -0,0 +1,84 @@
+import { TrackingEvent, LearningEventPayload } from './types';
+/**
+ * Category của từng event để backend routing/classification
+ */
+export type EventCategory = 'lifecycle' | 'vocabulary' | 'question' | 'media' | 'speaking' | 'system' | 'unknown';
+/**
+ * Cấu trúc request body chuẩn gửi lên API batch endpoint.
+ * session_id được cố ý loại bỏ (chỉ dùng local debug).
+ */
+export interface BatchRequestBody {
+    user_id: string;
+    app_id: string;
+    app_version: string;
+    events: Array<{
+        event_id: string;
+        event_name: string;
+        timestamp: number;
+        client_timestamp: number;
+        [key: string]: any;
+    }>;
+}
+/**
+ * EventProcessor - Pure business logic, không phụ thuộc browser API.
+ * Có thể sử dụng ở cả frontend (React/Vite) lẫn backend (NestJS/Node.js).
+ *
+ * @example Backend NestJS usage:
+ * ```typescript
+ * import { EventProcessor } from '@bkt/iframe-tracking-sdk/processor';
+ *
+ * // Nhận raw events từ request body
+ * const normalized = rawEvents.map(e => EventProcessor.normalize(e)).filter(Boolean);
+ * const batch = EventProcessor.buildBatchPayload(normalized);
+ * const categorized = EventProcessor.groupByCategory(normalized);
+ * ```
+ */
+export declare class EventProcessor {
+    private static readonly LIFECYCLE_EVENTS;
+    private static readonly VOCABULARY_EVENTS;
+    private static readonly QUESTION_EVENTS;
+    private static readonly MEDIA_EVENTS;
+    private static readonly SPEAKING_EVENTS;
+    private static readonly SYSTEM_EVENTS;
+    /**
+     * Normalize và validate một raw event object thành TrackingEvent đầy đủ.
+     * Trả về `null` nếu event thiếu `event_name` (invalid).
+     */
+    static normalize(raw: Partial<TrackingEvent> & {
+        event_name?: string;
+    }, defaults?: {
+        user_id?: string;
+        app_id?: string;
+    }): TrackingEvent | null;
+    /**
+     * Build batch request body theo chuẩn API `/api/progress/batch`.
+     * `session_id` được cố ý loại bỏ (không gửi lên server).
+     */
+    static buildBatchPayload(events: TrackingEvent[], appVersion?: string): BatchRequestBody;
+    /**
+     * Phân loại (classify) một sự kiện theo category.
+     */
+    static classify(eventName: string): EventCategory;
+    /**
+     * Nhóm các events theo category - hữu ích cho backend routing.
+     */
+    static groupByCategory(events: TrackingEvent[]): Record<EventCategory, TrackingEvent[]>;
+    /**
+     * Kiểm tra xem event có phải là "critical" không
+     * (cần immediate sync, không chờ batch interval).
+     */
+    static isCritical(eventName: string): boolean;
+    /**
+     * Tính điểm đúng/sai từ payload event.
+     * Trả về null nếu event không có thông tin điểm số.
+     */
+    static extractScore(event: TrackingEvent): {
+        isCorrect: boolean | null;
+        score: number | null;
+    };
+    /**
+     * Parse raw postMessage data từ Iframe thành LearningEventPayload.
+     * Dùng cho trường hợp backend cần xử lý message trực tiếp (WebSocket, etc.).
+     */
+    static parseIframeMessage(rawData: unknown): LearningEventPayload | null;
+}

package/dist/processor.js

@@ -0,0 +1,179 @@
+/**
+ * EventProcessor - Pure business logic, không phụ thuộc browser API.
+ * Có thể sử dụng ở cả frontend (React/Vite) lẫn backend (NestJS/Node.js).
+ *
+ * @example Backend NestJS usage:
+ * ```typescript
+ * import { EventProcessor } from '@bkt/iframe-tracking-sdk/processor';
+ *
+ * // Nhận raw events từ request body
+ * const normalized = rawEvents.map(e => EventProcessor.normalize(e)).filter(Boolean);
+ * const batch = EventProcessor.buildBatchPayload(normalized);
+ * const categorized = EventProcessor.groupByCategory(normalized);
+ * ```
+ */
+export class EventProcessor {
+    static LIFECYCLE_EVENTS = new Set([
+        'session_start', 'session_end',
+        'course_start', 'course_finish',
+        'unit_start', 'unit_finish', 'unit_submit', 'unit_restart'
+    ]);
+    static VOCABULARY_EVENTS = new Set([
+        'word_click', 'word_view', 'word_answer',
+        'flashcard_flip', 'flashcard_know'
+    ]);
+    static QUESTION_EVENTS = new Set([
+        'question_view', 'question_answer',
+        'drag_drop_interaction', 'text_input_change',
+        'show_solution', 'question_next', 'question_prev',
+        'image_view'
+    ]);
+    static MEDIA_EVENTS = new Set([
+        'audio_play', 'audio_pause', 'audio_completed',
+        'video_play', 'video_pause', 'video_seek', 'video_completed'
+    ]);
+    static SPEAKING_EVENTS = new Set([
+        'pronunciation_record', 'pronunciation_score'
+    ]);
+    static SYSTEM_EVENTS = new Set([
+        'client_error', 'network_latency_check'
+    ]);
+    /**
+     * Normalize và validate một raw event object thành TrackingEvent đầy đủ.
+     * Trả về `null` nếu event thiếu `event_name` (invalid).
+     */
+    static normalize(raw, defaults) {
+        const eventName = raw.event_name || raw.payload?.event_name;
+        if (!eventName)
+            return null;
+        const now = Date.now();
+        const randomChars = Math.random().toString(36).substring(2, 10);
+        return {
+            event_id: raw.event_id || `evt_${now}_${randomChars}`,
+            user_id: raw.user_id || defaults?.user_id || '',
+            app_id: raw.app_id || defaults?.app_id || '',
+            event_name: eventName,
+            payload: raw.payload || { event_name: eventName },
+            timestamp: raw.timestamp || now,
+            client_timestamp: raw.client_timestamp || now,
+            status: 'pending',
+            retry_count: raw.retry_count || 0,
+            created_at: raw.created_at || now,
+            ...(raw.session_id ? { session_id: raw.session_id } : {}),
+            ...(raw.signature ? { signature: raw.signature } : {}),
+        };
+    }
+    /**
+     * Build batch request body theo chuẩn API `/api/progress/batch`.
+     * `session_id` được cố ý loại bỏ (không gửi lên server).
+     */
+    static buildBatchPayload(events, appVersion = '1.0.0') {
+        if (events.length === 0)
+            throw new Error('[EventProcessor] Cannot build batch from empty events array');
+        return {
+            user_id: events[0].user_id,
+            app_id: events[0].app_id,
+            app_version: appVersion,
+            events: events.map(e => {
+                // Flatten payload fields vào event, loại bỏ event_name trùng lặp
+                const { event_name: _en, ...payloadRest } = e.payload;
+                return {
+                    event_id: e.event_id,
+                    event_name: e.event_name,
+                    timestamp: e.timestamp,
+                    client_timestamp: e.client_timestamp,
+                    ...payloadRest, // word_id, score, is_correct, duration_ms, ...
+                };
+            })
+        };
+    }
+    /**
+     * Phân loại (classify) một sự kiện theo category.
+     */
+    static classify(eventName) {
+        if (this.LIFECYCLE_EVENTS.has(eventName))
+            return 'lifecycle';
+        if (this.VOCABULARY_EVENTS.has(eventName))
+            return 'vocabulary';
+        if (this.QUESTION_EVENTS.has(eventName))
+            return 'question';
+        if (this.MEDIA_EVENTS.has(eventName))
+            return 'media';
+        if (this.SPEAKING_EVENTS.has(eventName))
+            return 'speaking';
+        if (this.SYSTEM_EVENTS.has(eventName))
+            return 'system';
+        return 'unknown';
+    }
+    /**
+     * Nhóm các events theo category - hữu ích cho backend routing.
+     */
+    static groupByCategory(events) {
+        const groups = {
+            lifecycle: [],
+            vocabulary: [],
+            question: [],
+            media: [],
+            speaking: [],
+            system: [],
+            unknown: []
+        };
+        for (const event of events) {
+            const cat = this.classify(event.event_name);
+            groups[cat].push(event);
+        }
+        return groups;
+    }
+    /**
+     * Kiểm tra xem event có phải là "critical" không
+     * (cần immediate sync, không chờ batch interval).
+     */
+    static isCritical(eventName) {
+        const criticalEvents = new Set([
+            'session_end',
+            'course_finish',
+            'unit_finish',
+            'unit_submit',
+            'unit_restart',
+            'pronunciation_score',
+            'client_error',
+        ]);
+        return criticalEvents.has(eventName);
+    }
+    /**
+     * Tính điểm đúng/sai từ payload event.
+     * Trả về null nếu event không có thông tin điểm số.
+     */
+    static extractScore(event) {
+        const p = event.payload;
+        // is_correct field trực tiếp
+        if (typeof p.is_correct === 'boolean') {
+            return { isCorrect: p.is_correct, score: p.score ?? null };
+        }
+        // result field: "correct" | "incorrect"
+        if (p.result === 'correct')
+            return { isCorrect: true, score: p.score ?? null };
+        if (p.result === 'incorrect')
+            return { isCorrect: false, score: p.score ?? null };
+        // pronunciation_score: overall_score >= 80 là đúng
+        if (event.event_name === 'pronunciation_score' && typeof p.overall_score === 'number') {
+            return { isCorrect: p.overall_score >= 80, score: p.overall_score };
+        }
+        return { isCorrect: null, score: p.score ?? p.overall_score ?? null };
+    }
+    /**
+     * Parse raw postMessage data từ Iframe thành LearningEventPayload.
+     * Dùng cho trường hợp backend cần xử lý message trực tiếp (WebSocket, etc.).
+     */
+    static parseIframeMessage(rawData) {
+        if (!rawData || typeof rawData !== 'object')
+            return null;
+        const data = rawData;
+        if (data['type'] !== 'LEARNING_EVENT')
+            return null;
+        const payload = data['payload'];
+        if (!payload || typeof payload !== 'object' || !payload['event_name'])
+            return null;
+        return payload;
+    }
+}

package/dist/react-hook.d.ts

@@ -0,0 +1,21 @@
+import { RefObject } from 'react';
+import { IframeHostTrackerConfig, TrackingEvent } from './types';
+export interface UseIframeHostTrackingResult {
+    iframeRef: RefObject<HTMLIFrameElement | null>;
+    isReady: boolean;
+    syncing: boolean;
+    events: TrackingEvent[];
+    flush: () => Promise<void>;
+    handleIframeLoad: () => void;
+    clearLogs: () => void;
+    clearQueue: () => Promise<void>;
+    /** Update optional local sessionId + hmacSecret for backward-compatible hosts */
+    updateCredentials: (sessionId: string, hmacSecret: string) => void;
+    /** Re-initiate handshake with the iframe */
+    reinitiateHandshake: () => void;
+    onEventReceived?: (event: TrackingEvent) => void;
+}
+export declare function useIframeHostTracking(config: Omit<IframeHostTrackerConfig, 'onEventReceived' | 'onEventSynced' | 'onSyncStatusChange'> & {
+    onEventReceived?: (event: TrackingEvent) => void;
+    onSessionRefreshNeeded?: (eventName: string) => void;
+}): UseIframeHostTrackingResult;

package/dist/react-hook.js

@@ -0,0 +1,142 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { IframeHostTracker } from './host';
+export function useIframeHostTracking(config) {
+    const iframeRef = useRef(null);
+    const trackerRef = useRef(null);
+    const [isReady, setIsReady] = useState(false);
+    const [syncing, setSyncing] = useState(false);
+    const [events, setEvents] = useState([]);
+    // Dùng ref để tránh stale closure — luôn gọi phiên bản callback mới nhất
+    const onEventReceivedRef = useRef(config.onEventReceived);
+    useEffect(() => {
+        onEventReceivedRef.current = config.onEventReceived;
+    }, [config.onEventReceived]);
+    // Refresh logs from database
+    const refreshLogs = useCallback(async () => {
+        if (!trackerRef.current)
+            return;
+        try {
+            const db = trackerRef.current.getDB();
+            const allEvents = await db.getAllEvents(100);
+            setEvents(allEvents);
+        }
+        catch (e) {
+            if (config.debug)
+                console.error('[Tracking Hook] Failed to load events from DB:', e);
+        }
+    }, [config.debug]);
+    // Handle iframe onload
+    const handleIframeLoad = useCallback(() => {
+        const iframe = iframeRef.current;
+        if (iframe && iframe.contentWindow && trackerRef.current) {
+            if (config.debug)
+                console.log('[Tracking Hook] Iframe loaded. Initiating secure handshake...');
+            trackerRef.current.initiateHandshake(iframe.contentWindow);
+        }
+    }, [config.debug]);
+    // Flush events
+    const flush = useCallback(async () => {
+        if (trackerRef.current) {
+            await trackerRef.current.flush();
+            await refreshLogs();
+        }
+    }, [refreshLogs]);
+    // Clear UI Logs
+    const clearLogs = useCallback(() => {
+        setEvents([]);
+    }, []);
+    // Clear local IndexedDB queue
+    const clearQueue = useCallback(async () => {
+        if (trackerRef.current) {
+            await trackerRef.current.clearQueue();
+            setEvents([]);
+        }
+    }, []);
+    // Update optional local sessionId + hmacSecret on the underlying tracker instance
+    const updateCredentials = useCallback((sessionId, hmacSecret) => {
+        if (trackerRef.current) {
+            trackerRef.current.updateCredentials(sessionId, hmacSecret);
+        }
+    }, []);
+    // Re-initiate handshake with the iframe (e.g., after credentials refresh)
+    const reinitiateHandshake = useCallback(() => {
+        const iframe = iframeRef.current;
+        if (iframe && iframe.contentWindow && trackerRef.current) {
+            if (config.debug)
+                console.log('[Tracking Hook] Re-initiating handshake after credential refresh...');
+            trackerRef.current.initiateHandshake(iframe.contentWindow);
+        }
+    }, [config.debug]);
+    // Initialize tracker on mount, recreate if dynamic credentials change
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        if (config.debug)
+            console.log('[Tracking Hook] Initializing IframeHostTracker...');
+        const tracker = new IframeHostTracker({
+            ...config,
+            onSessionRefreshNeeded: config.onSessionRefreshNeeded,
+            onEventReceived: (event) => {
+                if (config.debug)
+                    console.log('[Tracking Hook] Event received:', event.event_name);
+                // Gọi qua ref để luôn dùng callback mới nhất (tránh stale closure)
+                onEventReceivedRef.current?.(event);
+                refreshLogs();
+            },
+            onEventSynced: (ids) => {
+                if (config.debug)
+                    console.log('[Tracking Hook] Events synced:', ids);
+                refreshLogs();
+            },
+            onSyncStatusChange: (status) => {
+                setSyncing(status === 'syncing');
+            }
+        });
+        trackerRef.current = tracker;
+        tracker.start();
+        // Load initial events from IndexedDB
+        refreshLogs();
+        // Check if iframe is already loaded
+        const iframe = iframeRef.current;
+        if (iframe && iframe.contentWindow) {
+            tracker.initiateHandshake(iframe.contentWindow);
+        }
+        // Set up handshake completion checker
+        const checkHandshakeInterval = setInterval(() => {
+            // Accessing private variable safely via class status
+            if (tracker && tracker.isHandshakeComplete) {
+                setIsReady(true);
+            }
+            else {
+                setIsReady(false);
+            }
+        }, 1000);
+        return () => {
+            clearInterval(checkHandshakeInterval);
+            tracker.stop();
+            trackerRef.current = null;
+        };
+    }, [
+        config.iframeUrl,
+        config.userId,
+        config.sessionId,
+        config.hmacSecret,
+        config.apiEndpoint,
+        config.appId,
+        config.sectionId,
+        config.trustedOrigins.join(','),
+        refreshLogs
+    ]);
+    return {
+        iframeRef,
+        isReady,
+        syncing,
+        events,
+        flush,
+        handleIframeLoad,
+        clearLogs,
+        clearQueue,
+        updateCredentials,
+        reinitiateHandshake,
+    };
+}

package/dist/security.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cryptographic security and verification helpers.
+ */
+/**
+ * Generate a cryptographically secure UUID-v4.
+ */
+export declare function generateNonce(): string;
+/**
+ * Sort object keys alphabetically recursively to maintain signature consistency.
+ */
+export declare function sortObjectKeys(obj: any): any;
+/**
+ * Generate a canonical string representation for an event to be signed.
+ * canonical_string = event_name + "|" + event_id + "|" + timestamp + "|" + JSON.stringify(payload_sorted)
+ */
+export declare function buildCanonicalString(eventName: string, eventId: string, timestamp: number, payload: any): string;
+/**
+ * Generate browser-native HMAC-SHA256 signature in Hex format.
+ */
+export declare function signHmacSha256(secret: string, canonicalString: string): Promise<string>;
+/**
+ * Verify browser-native HMAC-SHA256 signature.
+ */
+export declare function verifyHmacSha256(secret: string, canonicalString: string, signatureHex: string): Promise<boolean>;

package/dist/security.js

@@ -0,0 +1,191 @@
+/**
+ * Cryptographic security and verification helpers.
+ */
+/**
+ * Generate a cryptographically secure UUID-v4.
+ */
+export function generateNonce() {
+    if (typeof window !== 'undefined' && window.crypto && window.crypto.randomUUID) {
+        return window.crypto.randomUUID();
+    }
+    // Fallback if randomUUID is not available (e.g. in some older environments)
+    const array = new Uint32Array(4);
+    if (typeof window !== 'undefined' && window.crypto) {
+        window.crypto.getRandomValues(array);
+    }
+    else {
+        // Basic Node/SSR fallback
+        for (let i = 0; i < 4; i++) {
+            array[i] = Math.floor(Math.random() * 0xffffffff);
+        }
+    }
+    let hex = '';
+    for (let i = 0; i < 4; i++) {
+        hex += array[i].toString(16).padStart(8, '0');
+    }
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+/**
+ * Sort object keys alphabetically recursively to maintain signature consistency.
+ */
+export function sortObjectKeys(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(sortObjectKeys);
+    }
+    const sorted = {};
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+        sorted[key] = sortObjectKeys(obj[key]);
+    }
+    return sorted;
+}
+/**
+ * Generate a canonical string representation for an event to be signed.
+ * canonical_string = event_name + "|" + event_id + "|" + timestamp + "|" + JSON.stringify(payload_sorted)
+ */
+export function buildCanonicalString(eventName, eventId, timestamp, payload) {
+    const sortedPayload = sortObjectKeys(payload);
+    return `${eventName}|${eventId}|${timestamp}|${JSON.stringify(sortedPayload)}`;
+}
+/**
+ * Generate browser-native HMAC-SHA256 signature in Hex format.
+ */
+export async function signHmacSha256(secret, canonicalString) {
+    // Use browser-native Web Crypto API if available (faster & built-in)
+    if (typeof window !== 'undefined' && window.crypto && window.crypto.subtle) {
+        try {
+            const encoder = new TextEncoder();
+            const keyData = encoder.encode(secret);
+            const messageData = encoder.encode(canonicalString);
+            const cryptoKey = await window.crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+            const signatureBuffer = await window.crypto.subtle.sign('HMAC', cryptoKey, messageData);
+            const hashArray = Array.from(new Uint8Array(signatureBuffer));
+            return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+        }
+        catch (e) {
+            // Fall back to pure JS if Web Crypto fails unexpectedly
+        }
+    }
+    // Fallback: Pure JS HMAC-SHA256 (for insecure contexts like HTTP on IP)
+    const signatureBuffer = hmacSha256Pure(secret, canonicalString);
+    const hashArray = Array.from(signatureBuffer);
+    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+// Pure JS SHA-256 and HMAC-SHA256 helper functions
+function sha256Pure(bytes) {
+    function rightRotate(value, amount) {
+        return (value >>> amount) | (value << (32 - amount));
+    }
+    const hash = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+        0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19
+    ]);
+    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 len = bytes.length;
+    const paddedLen = ((len + 8 + 64) >>> 6) << 6;
+    const padded = new Uint8Array(paddedLen);
+    padded.set(bytes);
+    padded[len] = 0x80;
+    const view = new DataView(padded.buffer);
+    const bitLen = len * 8;
+    view.setUint32(paddedLen - 4, bitLen & 0xffffffff);
+    view.setUint32(paddedLen - 8, Math.floor(bitLen / 0x100000000));
+    const w = new Uint32Array(64);
+    for (let i = 0; i < paddedLen; i += 64) {
+        for (let t = 0; t < 16; t++) {
+            w[t] = view.getUint32(i + t * 4);
+        }
+        for (let t = 16; t < 64; t++) {
+            const s0 = rightRotate(w[t - 15], 7) ^ rightRotate(w[t - 15], 18) ^ (w[t - 15] >>> 3);
+            const s1 = rightRotate(w[t - 2], 17) ^ rightRotate(w[t - 2], 19) ^ (w[t - 2] >>> 10);
+            w[t] = (w[t - 16] + s0 + w[t - 7] + s1) | 0;
+        }
+        let a = hash[0];
+        let b = hash[1];
+        let c = hash[2];
+        let d = hash[3];
+        let e = hash[4];
+        let f = hash[5];
+        let g = hash[6];
+        let h = hash[7];
+        for (let t = 0; t < 64; t++) {
+            const s1 = rightRotate(e, 6) ^ rightRotate(e, 11) ^ rightRotate(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const temp1 = (h + s1 + ch + k[t] + w[t]) | 0;
+            const s0 = rightRotate(a, 2) ^ rightRotate(a, 13) ^ rightRotate(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;
+        }
+        hash[0] = (hash[0] + a) | 0;
+        hash[1] = (hash[1] + b) | 0;
+        hash[2] = (hash[2] + c) | 0;
+        hash[3] = (hash[3] + d) | 0;
+        hash[4] = (hash[4] + e) | 0;
+        hash[5] = (hash[5] + f) | 0;
+        hash[6] = (hash[6] + g) | 0;
+        hash[7] = (hash[7] + h) | 0;
+    }
+    const result = new Uint8Array(32);
+    const resultView = new DataView(result.buffer);
+    for (let i = 0; i < 8; i++) {
+        resultView.setUint32(i * 4, hash[i]);
+    }
+    return result;
+}
+function hmacSha256Pure(secret, message) {
+    const encoder = new TextEncoder();
+    let key = encoder.encode(secret);
+    const msgBytes = encoder.encode(message);
+    const blockValues = 64;
+    if (key.length > blockValues) {
+        key = new Uint8Array(sha256Pure(key));
+    }
+    const paddedKey = new Uint8Array(blockValues);
+    paddedKey.set(key);
+    const ipad = new Uint8Array(blockValues);
+    const opad = new Uint8Array(blockValues);
+    for (let i = 0; i < blockValues; i++) {
+        ipad[i] = paddedKey[i] ^ 0x36;
+        opad[i] = paddedKey[i] ^ 0x5c;
+    }
+    const innerInput = new Uint8Array(blockValues + msgBytes.length);
+    innerInput.set(ipad, 0);
+    innerInput.set(msgBytes, blockValues);
+    const innerHash = sha256Pure(innerInput);
+    const outerInput = new Uint8Array(blockValues + 32);
+    outerInput.set(opad, 0);
+    outerInput.set(innerHash, blockValues);
+    return sha256Pure(outerInput);
+}
+/**
+ * Verify browser-native HMAC-SHA256 signature.
+ */
+export async function verifyHmacSha256(secret, canonicalString, signatureHex) {
+    try {
+        const computedHex = await signHmacSha256(secret, canonicalString);
+        return computedHex === signatureHex;
+    }
+    catch (e) {
+        return false;
+    }
+}