@prabhask5/stellar-engine 1.1.6 → 1.1.8

package/dist/actions/truncateTooltip.js

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview Svelte action for truncated-text tooltips.
+ *
+ * Provides a `use:truncateTooltip` directive that enforces CSS text-overflow
+ * ellipsis on the target element and shows a floating tooltip with the
+ * **full** text whenever the content is visually truncated.
+ *
+ * **Behaviour by device type:**
+ *   - **Desktop** — tooltip appears on `mouseenter`, hides on `mouseleave`.
+ *     Only shown when `scrollWidth > clientWidth` (text is actually clipped).
+ *   - **Mobile** — tooltip appears on `touchstart` (tap), dismisses on
+ *     tap-outside or after a 3-second auto-dismiss timeout.
+ *
+ * A **singleton** tooltip `<div>` is lazily appended to `document.body` and
+ * reused across all instances of the action to avoid DOM bloat.
+ *
+ * @example
+ * ```svelte
+ * <span class="my-text" use:truncateTooltip>{longText}</span>
+ * ```
+ *
+ * @see {@link truncateTooltip} for the Svelte action export
+ * @see {@link showTooltip} for the display logic
+ * @see {@link positionTooltip} for the positioning algorithm
+ */
+// =============================================================================
+//                        SINGLETON TOOLTIP STATE
+// =============================================================================
+/**
+ * The shared tooltip DOM element — lazily created by {@link getTooltip}.
+ * Only one tooltip element exists in the entire document, regardless of
+ * how many `use:truncateTooltip` instances are active.
+ */
+let tooltipEl = null;
+/**
+ * Handle for the mobile auto-dismiss `setTimeout`.
+ * Cleared on manual hide to prevent stale timeouts from
+ * dismissing a newly-shown tooltip.
+ */
+let hideTimeout = null;
+/**
+ * The DOM element that currently "owns" the visible tooltip.
+ * Used to prevent hide events from one element dismissing another's tooltip,
+ * and to implement tap-toggle behaviour on mobile (tap same element = hide).
+ */
+let currentOwner = null;
+// =============================================================================
+//                       TOOLTIP ELEMENT MANAGEMENT
+// =============================================================================
+/**
+ * Return the singleton tooltip element, creating it on first call.
+ *
+ * The element is given the CSS class `truncate-tooltip` and an ARIA
+ * `role="tooltip"` attribute for accessibility. The consuming app must
+ * provide CSS for `.truncate-tooltip` (positioning, background, etc.)
+ * and a `.visible` modifier class to control opacity/display.
+ *
+ * @returns The shared tooltip `HTMLElement`.
+ */
+function getTooltip() {
+    if (!tooltipEl) {
+        tooltipEl = document.createElement('div');
+        tooltipEl.className = 'truncate-tooltip';
+        tooltipEl.setAttribute('role', 'tooltip');
+        document.body.appendChild(tooltipEl);
+    }
+    return tooltipEl;
+}
+// =============================================================================
+//                          TRUNCATION DETECTION
+// =============================================================================
+/**
+ * Check whether an element's text content is visually truncated.
+ *
+ * Compares `scrollWidth` (full content width including overflow) against
+ * `clientWidth` (visible width). When `scrollWidth` exceeds `clientWidth`,
+ * the CSS `text-overflow: ellipsis` rule is hiding part of the text.
+ *
+ * @param el - The DOM element to test.
+ * @returns `true` if the text overflows its container.
+ *
+ * @example
+ * ```ts
+ * if (isTruncated(spanElement)) {
+ *   showTooltip(spanElement);
+ * }
+ * ```
+ */
+function isTruncated(el) {
+    return el.scrollWidth > el.clientWidth;
+}
+// =============================================================================
+//                         TOOLTIP POSITIONING
+// =============================================================================
+/**
+ * Position the tooltip relative to an anchor element.
+ *
+ * Default placement is **centred above** the anchor with an 8 px gap.
+ * Two edge-case corrections are applied:
+ *   1. If the tooltip would overflow the **top** of the viewport, it flips
+ *      to appear **below** the anchor instead.
+ *   2. The horizontal position is clamped to keep the tooltip within the
+ *      viewport (8 px padding on each side).
+ *
+ * @param tooltip - The tooltip element to reposition.
+ * @param anchor  - The element the tooltip should point at.
+ */
+function positionTooltip(tooltip, anchor) {
+    const rect = anchor.getBoundingClientRect();
+    const tooltipRect = tooltip.getBoundingClientRect();
+    /* ── Default: centred above the anchor ──── */
+    let left = rect.left + rect.width / 2 - tooltipRect.width / 2;
+    let top = rect.top - tooltipRect.height - 8;
+    /* Flip below if tooltip would overflow the top edge */
+    if (top < 4) {
+        top = rect.bottom + 8;
+    }
+    /* ── Horizontal clamping ──── */
+    const maxLeft = window.innerWidth - tooltipRect.width - 8;
+    left = Math.max(8, Math.min(left, maxLeft));
+    tooltip.style.left = `${left}px`;
+    tooltip.style.top = `${top}px`;
+}
+// =============================================================================
+//                         SHOW / HIDE LOGIC
+// =============================================================================
+/**
+ * Show the tooltip for the given anchor element.
+ *
+ * Exits early if the anchor's text is **not** truncated (no tooltip needed).
+ * Positioning is deferred to the next animation frame so that the tooltip's
+ * dimensions are accurate after its `textContent` is set.
+ *
+ * @param anchor - The element whose full text should be displayed in the tooltip.
+ */
+function showTooltip(anchor) {
+    if (!isTruncated(anchor))
+        return;
+    const tooltip = getTooltip();
+    const fullText = anchor.textContent?.trim() || '';
+    if (!fullText)
+        return;
+    /* Cancel any pending auto-dismiss from a previous mobile tap */
+    if (hideTimeout) {
+        clearTimeout(hideTimeout);
+        hideTimeout = null;
+    }
+    tooltip.textContent = fullText;
+    tooltip.classList.add('visible');
+    currentOwner = anchor;
+    /* Position after content is set so dimensions are correct */
+    requestAnimationFrame(() => {
+        positionTooltip(tooltip, anchor);
+    });
+}
+/**
+ * Hide the tooltip and reset ownership state.
+ *
+ * Safe to call even when no tooltip is visible — the function is a no-op
+ * in that case. Also clears any pending auto-dismiss timeout.
+ */
+function hideTooltip() {
+    if (tooltipEl) {
+        tooltipEl.classList.remove('visible');
+    }
+    currentOwner = null;
+    if (hideTimeout) {
+        clearTimeout(hideTimeout);
+        hideTimeout = null;
+    }
+}
+// =============================================================================
+//                         DEVICE DETECTION
+// =============================================================================
+/**
+ * Detect whether the current device supports touch input.
+ *
+ * Uses feature detection (`ontouchstart` in `window` or `maxTouchPoints`)
+ * rather than user-agent sniffing, which is more reliable across browsers
+ * and avoids false negatives on hybrid devices.
+ *
+ * @returns `true` on touch-capable devices.
+ */
+function isTouchDevice() {
+    return 'ontouchstart' in window || navigator.maxTouchPoints > 0;
+}
+// =============================================================================
+//                        SVELTE ACTION EXPORT
+// =============================================================================
+/**
+ * Svelte action that applies truncation-aware tooltips to an element.
+ *
+ * **On mount the action:**
+ *   1. Forces CSS `overflow: hidden`, `text-overflow: ellipsis`, and
+ *      `white-space: nowrap` on the node to guarantee ellipsis rendering.
+ *   2. Registers `mouseenter` / `mouseleave` handlers for desktop hover.
+ *   3. Registers `touchstart` handlers for mobile tap-to-show behaviour.
+ *   4. Registers a document-level `touchstart` listener for tap-outside
+ *      dismissal on mobile.
+ *
+ * The returned `destroy` callback cleans up all listeners and hides the
+ * tooltip if the destroyed node was its current owner.
+ *
+ * @param node - The DOM element to enhance with truncation tooltips.
+ * @returns A Svelte action lifecycle object with a `destroy` method.
+ *
+ * @example
+ * ```svelte
+ * <span class="my-text" use:truncateTooltip>{longText}</span>
+ * ```
+ */
+export function truncateTooltip(node) {
+    /* ── Apply ellipsis CSS ──── */
+    node.style.overflow = 'hidden';
+    node.style.textOverflow = 'ellipsis';
+    node.style.whiteSpace = 'nowrap';
+    // ---------------------------------------------------------------------------
+    //                    DESKTOP: HOVER HANDLERS
+    // ---------------------------------------------------------------------------
+    /**
+     * Show tooltip on mouse enter (desktop only).
+     * Skips on touch devices to avoid double-triggering with touch handlers.
+     */
+    function handleMouseEnter() {
+        if (isTouchDevice())
+            return;
+        showTooltip(node);
+    }
+    /**
+     * Hide tooltip on mouse leave, but only if this node owns the tooltip.
+     * Prevents one element's mouseleave from dismissing another's tooltip.
+     */
+    function handleMouseLeave() {
+        if (currentOwner === node) {
+            hideTooltip();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    //                    MOBILE: TAP HANDLERS
+    // ---------------------------------------------------------------------------
+    /**
+     * Toggle tooltip on tap (mobile only).
+     *
+     * Prevents default to avoid triggering navigation or text selection.
+     * Stops propagation to prevent the document-level tap-outside handler
+     * from immediately dismissing the tooltip.
+     * Auto-dismisses after 3 seconds.
+     *
+     * @param e - The touch event.
+     */
+    function handleTap(e) {
+        if (!isTouchDevice())
+            return;
+        if (!isTruncated(node))
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        /* Toggle off if already showing for this node */
+        if (currentOwner === node) {
+            hideTooltip();
+            return;
+        }
+        showTooltip(node);
+        /* Auto-dismiss after 3 s on mobile */
+        hideTimeout = setTimeout(hideTooltip, 3000);
+    }
+    /**
+     * Dismiss the tooltip when the user taps outside the anchor or tooltip
+     * (mobile only). Ignores taps on the anchor itself or inside the tooltip
+     * to prevent unintended dismissal.
+     *
+     * @param e - The document-level touch event.
+     */
+    function handleTapOutside(e) {
+        if (!currentOwner || currentOwner !== node)
+            return;
+        const target = e.target;
+        if (target === node || node.contains(target))
+            return;
+        if (tooltipEl && (target === tooltipEl || tooltipEl.contains(target)))
+            return;
+        hideTooltip();
+    }
+    // ---------------------------------------------------------------------------
+    //                 EVENT LISTENER REGISTRATION
+    // ---------------------------------------------------------------------------
+    node.addEventListener('mouseenter', handleMouseEnter);
+    node.addEventListener('mouseleave', handleMouseLeave);
+    node.addEventListener('touchstart', handleTap, { passive: false });
+    document.addEventListener('touchstart', handleTapOutside, { passive: true });
+    // ---------------------------------------------------------------------------
+    //                 SVELTE ACTION LIFECYCLE
+    // ---------------------------------------------------------------------------
+    return {
+        /**
+         * Cleanup handler — removes all event listeners and hides the tooltip
+         * if this node was the active owner. Prevents memory leaks from
+         * orphaned document-level listeners.
+         */
+        destroy() {
+            node.removeEventListener('mouseenter', handleMouseEnter);
+            node.removeEventListener('mouseleave', handleMouseLeave);
+            node.removeEventListener('touchstart', handleTap);
+            document.removeEventListener('touchstart', handleTapOutside);
+            /* Clean up tooltip if this node was the active owner */
+            if (currentOwner === node) {
+                hideTooltip();
+            }
+        }
+    };
+}
+//# sourceMappingURL=truncateTooltip.js.map

package/dist/actions/truncateTooltip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncateTooltip.js","sourceRoot":"","sources":["../../src/actions/truncateTooltip.ts"],"names":[],"mappings":"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"}

package/dist/auth/admin.d.ts

@@ -1,12 +1,49 @@
 /**
- * Admin Check
+ * @fileoverview Admin Privilege Resolution
  *
- * Delegates to config.auth.adminCheck or returns false.
+ * Provides a single entry point for determining whether a given Supabase user
+ * holds administrative privileges within the application.
+ *
+ * Architecture:
+ * - Delegates entirely to the host application's `config.auth.adminCheck` callback.
+ * - In single-user mode, every authenticated user is implicitly an admin (there is
+ *   only one user, so restricting admin access would be meaningless).
+ * - If the engine has not been initialized yet (e.g., during early bootstrap),
+ *   the function silently returns `false` rather than throwing, ensuring safe
+ *   usage in guards and UI conditionals before full initialization.
+ *
+ * Security considerations:
+ * - This is a **client-side convenience check** only. It must NOT be relied upon
+ *   as an authorization boundary -- server-side RLS policies and edge-function
+ *   guards are the true security layer.
+ * - The `adminCheck` callback is provided by the host app and can inspect any
+ *   property on the Supabase `User` object (e.g., `app_metadata.role`).
+ *
+ * @module auth/admin
  */
 import type { User } from '@supabase/supabase-js';
 /**
  * Check if a user has admin privileges.
- * Uses the adminCheck function from engine config if provided.
+ *
+ * Uses the `adminCheck` function from engine config if provided.
+ * Falls back to `false` when no check is configured or the engine
+ * is not yet initialized.
+ *
+ * @param user - The Supabase user object to evaluate, or `null` if no user
+ *               is currently authenticated.
+ * @returns `true` if the user is considered an admin, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { isAdmin } from 'stellar-engine/auth/admin';
+ *
+ * const admin = isAdmin(currentUser);
+ * if (admin) {
+ *   showAdminPanel();
+ * }
+ * ```
+ *
+ * @see {@link getEngineConfig} for how the admin check callback is registered.
  */
 export declare function isAdmin(user: User | null): boolean;
 //# sourceMappingURL=admin.d.ts.map

package/dist/auth/admin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/auth/admin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAGlD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAYlD"}
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/auth/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAOlD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAclD"}

package/dist/auth/admin.js

@@ -1,17 +1,57 @@
 /**
- * Admin Check
+ * @fileoverview Admin Privilege Resolution
  *
- * Delegates to config.auth.adminCheck or returns false.
+ * Provides a single entry point for determining whether a given Supabase user
+ * holds administrative privileges within the application.
+ *
+ * Architecture:
+ * - Delegates entirely to the host application's `config.auth.adminCheck` callback.
+ * - In single-user mode, every authenticated user is implicitly an admin (there is
+ *   only one user, so restricting admin access would be meaningless).
+ * - If the engine has not been initialized yet (e.g., during early bootstrap),
+ *   the function silently returns `false` rather than throwing, ensuring safe
+ *   usage in guards and UI conditionals before full initialization.
+ *
+ * Security considerations:
+ * - This is a **client-side convenience check** only. It must NOT be relied upon
+ *   as an authorization boundary -- server-side RLS policies and edge-function
+ *   guards are the true security layer.
+ * - The `adminCheck` callback is provided by the host app and can inspect any
+ *   property on the Supabase `User` object (e.g., `app_metadata.role`).
+ *
+ * @module auth/admin
  */
 import { getEngineConfig } from '../config';
+// =============================================================================
+// PUBLIC API
+// =============================================================================
 /**
  * Check if a user has admin privileges.
- * Uses the adminCheck function from engine config if provided.
+ *
+ * Uses the `adminCheck` function from engine config if provided.
+ * Falls back to `false` when no check is configured or the engine
+ * is not yet initialized.
+ *
+ * @param user - The Supabase user object to evaluate, or `null` if no user
+ *               is currently authenticated.
+ * @returns `true` if the user is considered an admin, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { isAdmin } from 'stellar-engine/auth/admin';
+ *
+ * const admin = isAdmin(currentUser);
+ * if (admin) {
+ *   showAdminPanel();
+ * }
+ * ```
+ *
+ * @see {@link getEngineConfig} for how the admin check callback is registered.
  */
 export function isAdmin(user) {
     try {
         const config = getEngineConfig();
-        // Single-user mode: always admin
+        /* Single-user mode: the sole user owns everything, so admin is implicit. */
         if (config.auth?.mode === 'single-user')
             return true;
         if (config.auth?.adminCheck) {
@@ -19,7 +59,7 @@ export function isAdmin(user) {
         }
     }
     catch {
-        // Engine not initialized yet
+        /* Engine not initialized yet -- safe to swallow; callers expect a boolean. */
     }
     return false;
 }

package/dist/auth/admin.js.map

@@ -1 +1 @@
-{"version":3,"file":"admin.js","sourceRoot":"","sources":["../../src/auth/admin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,iCAAiC;QACjC,IAAI,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;QACrD,IAAI,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC;YAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../../src/auth/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QAEjC,4EAA4E;QAC5E,IAAI,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;QAErD,IAAI,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC;YAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;IAChF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/auth/crypto.d.ts

@@ -1,14 +1,64 @@
 /**
- * Shared Crypto Utilities
- * SHA-256 hashing for passwords, codes, and other values.
+ * @fileoverview Shared Cryptographic Utilities
+ *
+ * Provides deterministic, one-way hashing primitives used throughout the auth
+ * subsystem for password storage, gate-code verification, and credential caching.
+ *
+ * Architecture:
+ * - Uses the Web Crypto API (`crypto.subtle`) which is available in all modern
+ *   browsers, Web Workers, and server-side runtimes (Node 15+, Deno, Bun).
+ * - Hashing is always SHA-256, producing a 64-character lowercase hex digest.
+ *   This is NOT a password-hashing algorithm (bcrypt/argon2); it is used only
+ *   for **local** cache comparisons. The server-side Supabase auth layer uses
+ *   bcrypt for actual credential storage.
+ *
+ * Security considerations:
+ * - SHA-256 is collision-resistant but NOT suitable for brute-force-resistant
+ *   password storage on its own. It is acceptable here because the hashed values
+ *   are only stored in the client-side IndexedDB for offline pre-checking and
+ *   are never transmitted to a server.
+ * - The `isAlreadyHashed` helper uses a regex heuristic (64-char hex). If a
+ *   user's actual password happens to be a 64-char hex string, it will be
+ *   misidentified as already hashed. This is an acceptable edge case given the
+ *   vanishingly low probability and the local-only usage context.
+ *
+ * @module auth/crypto
  */
 /**
- * Hash a value using SHA-256 via Web Crypto API.
- * Returns a 64-character hex string.
+ * Hash a value using SHA-256 via the Web Crypto API.
+ *
+ * Encodes the input string as UTF-8, computes the SHA-256 digest, and returns
+ * the result as a 64-character lowercase hexadecimal string.
+ *
+ * @param value - The plaintext string to hash (e.g., a password or gate code).
+ * @returns A promise that resolves to a 64-character hex string representing
+ *          the SHA-256 digest.
+ *
+ * @example
+ * ```ts
+ * const hashed = await hashValue('my-secret-password');
+ * // hashed === 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' (example)
+ * ```
+ *
+ * @see {@link isAlreadyHashed} to check whether a string is already a hex digest.
  */
 export declare function hashValue(value: string): Promise<string>;
 /**
- * Check if a stored value is already hashed (64-char hex string).
+ * Check if a stored value is already hashed (64-character hex string).
+ *
+ * Used to distinguish between legacy plaintext credentials and modern
+ * SHA-256-hashed credentials in IndexedDB, enabling backward-compatible
+ * verification without a migration step.
+ *
+ * @param value - The string to test.
+ * @returns `true` if the value matches the pattern of a SHA-256 hex digest
+ *          (exactly 64 lowercase hexadecimal characters), `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isAlreadyHashed('abc123');           // false
+ * isAlreadyHashed('e3b0c442...b855');  // true (64-char hex)
+ * ```
  */
 export declare function isAlreadyHashed(value: string): boolean;
 //# sourceMappingURL=crypto.d.ts.map

package/dist/auth/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/auth/crypto.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/auth/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/auth/crypto.js

@@ -1,10 +1,49 @@
 /**
- * Shared Crypto Utilities
- * SHA-256 hashing for passwords, codes, and other values.
+ * @fileoverview Shared Cryptographic Utilities
+ *
+ * Provides deterministic, one-way hashing primitives used throughout the auth
+ * subsystem for password storage, gate-code verification, and credential caching.
+ *
+ * Architecture:
+ * - Uses the Web Crypto API (`crypto.subtle`) which is available in all modern
+ *   browsers, Web Workers, and server-side runtimes (Node 15+, Deno, Bun).
+ * - Hashing is always SHA-256, producing a 64-character lowercase hex digest.
+ *   This is NOT a password-hashing algorithm (bcrypt/argon2); it is used only
+ *   for **local** cache comparisons. The server-side Supabase auth layer uses
+ *   bcrypt for actual credential storage.
+ *
+ * Security considerations:
+ * - SHA-256 is collision-resistant but NOT suitable for brute-force-resistant
+ *   password storage on its own. It is acceptable here because the hashed values
+ *   are only stored in the client-side IndexedDB for offline pre-checking and
+ *   are never transmitted to a server.
+ * - The `isAlreadyHashed` helper uses a regex heuristic (64-char hex). If a
+ *   user's actual password happens to be a 64-char hex string, it will be
+ *   misidentified as already hashed. This is an acceptable edge case given the
+ *   vanishingly low probability and the local-only usage context.
+ *
+ * @module auth/crypto
  */
+// =============================================================================
+// PUBLIC API
+// =============================================================================
 /**
- * Hash a value using SHA-256 via Web Crypto API.
- * Returns a 64-character hex string.
+ * Hash a value using SHA-256 via the Web Crypto API.
+ *
+ * Encodes the input string as UTF-8, computes the SHA-256 digest, and returns
+ * the result as a 64-character lowercase hexadecimal string.
+ *
+ * @param value - The plaintext string to hash (e.g., a password or gate code).
+ * @returns A promise that resolves to a 64-character hex string representing
+ *          the SHA-256 digest.
+ *
+ * @example
+ * ```ts
+ * const hashed = await hashValue('my-secret-password');
+ * // hashed === 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' (example)
+ * ```
+ *
+ * @see {@link isAlreadyHashed} to check whether a string is already a hex digest.
  */
 export async function hashValue(value) {
     const encoder = new TextEncoder();
@@ -14,7 +53,21 @@ export async function hashValue(value) {
     return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
 }
 /**
- * Check if a stored value is already hashed (64-char hex string).
+ * Check if a stored value is already hashed (64-character hex string).
+ *
+ * Used to distinguish between legacy plaintext credentials and modern
+ * SHA-256-hashed credentials in IndexedDB, enabling backward-compatible
+ * verification without a migration step.
+ *
+ * @param value - The string to test.
+ * @returns `true` if the value matches the pattern of a SHA-256 hex digest
+ *          (exactly 64 lowercase hexadecimal characters), `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isAlreadyHashed('abc123');           // false
+ * isAlreadyHashed('e3b0c442...b855');  // true (64-char hex)
+ * ```
  */
 export function isAlreadyHashed(value) {
     return /^[0-9a-f]{64}$/.test(value);

package/dist/auth/crypto.js.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/auth/crypto.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAa;IAC3C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IACzD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/auth/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAa;IAC3C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IACzD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC"}