@hexclave/shared 1.0.3 → 1.0.5

package/src/utils/telemetry.tsx

@@ -0,0 +1,37 @@
+import { Attributes, AttributeValue, Span, trace } from "@opentelemetry/api";
+import { getEnvVariable } from "./env";
+import { HexclaveAssertionError } from "./errors";
+
+const tracer = trace.getTracer('stack-tracer');
+
+export function withTraceSpan<P extends any[], T>(optionsOrDescription: string | { description: string, attributes?: Record<string, AttributeValue> }, fn: (...args: P) => Promise<T>): (...args: P) => Promise<T> {
+  return async (...args: P) => {
+    return await traceSpan(optionsOrDescription, (span) => fn(...args));
+  };
+}
+
+export async function traceSpan<T>(optionsOrDescription: string | { description: string, attributes?: Record<string, AttributeValue> }, fn: (span: Span) => Promise<T>): Promise<T> {
+  let options = typeof optionsOrDescription === 'string' ? { description: optionsOrDescription } : optionsOrDescription;
+  return await tracer.startActiveSpan(`STACK: ${options.description}`, async (span) => {
+    if (options.attributes) {
+      for (const [key, value] of Object.entries(options.attributes)) {
+        span.setAttribute(key, value);
+      }
+    }
+    try {
+      return await fn(span);
+    } finally {
+      span.end();
+    }
+  });
+}
+
+export function log(message: string, attributes: Attributes) {
+  const span = trace.getActiveSpan();
+  if (span) {
+    span.addEvent(message, attributes);
+    // Telemetry is not initialized while seeding, so we don't want to throw an error
+  } else if (getEnvVariable('STACK_SEED_MODE', 'false') !== 'true') {
+    throw new HexclaveAssertionError('No active span found');
+  }
+}

package/src/utils/turnstile-browser.ts

@@ -0,0 +1,106 @@
+import { HexclaveAssertionError } from "./errors";
+import { TurnstileAction } from "./turnstile";
+
+export type TurnstileWidgetId = string;
+export type TurnstileTheme = "auto" | "light" | "dark";
+export type TurnstileAppearance = "always" | "execute" | "interaction-only";
+export type TurnstileExecution = "render" | "execute";
+export type TurnstileSize = "invisible" | "flexible" | "normal" | "compact";
+
+export type TurnstileConfig = {
+  sitekey: string,
+  action: TurnstileAction,
+  theme?: TurnstileTheme,
+  appearance?: TurnstileAppearance,
+  execution?: TurnstileExecution,
+  size?: TurnstileSize,
+  callback: (token: string) => void,
+  "error-callback": (errorCode?: string) => void,
+  "expired-callback": () => void,
+  "timeout-callback"?: () => void,
+};
+
+export type TurnstileApi = {
+  render: (container: HTMLElement, config: TurnstileConfig) => TurnstileWidgetId,
+  execute?: (widgetId: TurnstileWidgetId) => void,
+  remove: (widgetId: TurnstileWidgetId) => void,
+  reset?: (widgetId: TurnstileWidgetId) => void,
+};
+
+const TURNSTILE_SCRIPT_BASE_URL = "https://challenges.cloudflare.com/turnstile/v0/api.js";
+const TURNSTILE_SCRIPT_LOAD_TIMEOUT_MS = 30_000;
+
+export function isTurnstileApi(value: unknown): value is TurnstileApi {
+  return typeof value === "object"
+    && value !== null
+    && "render" in value
+    && "remove" in value;
+}
+
+export function getTurnstileApi(): TurnstileApi | undefined {
+  if (typeof window === "undefined") {
+    return undefined;
+  }
+
+  const maybeTurnstile = Reflect.get(window, "turnstile");
+  return isTurnstileApi(maybeTurnstile) ? maybeTurnstile : undefined;
+}
+
+let turnstileScriptPromise: Promise<void> | null = null;
+
+export function loadTurnstileScript(): Promise<void> {
+  if (typeof window === "undefined") {
+    return Promise.reject(new HexclaveAssertionError("Turnstile can only be loaded in the browser"));
+  }
+
+  if (getTurnstileApi()) {
+    return Promise.resolve();
+  }
+
+  turnstileScriptPromise ??= new Promise<void>((resolve, reject) => {
+    const rejectAndReset = (err: Error) => {
+      turnstileScriptPromise = null;
+      reject(err);
+    };
+
+    const timeout = setTimeout(() => {
+      rejectAndReset(new Error("Turnstile script load timed out"));
+    }, TURNSTILE_SCRIPT_LOAD_TIMEOUT_MS);
+
+    const resolveAndClearTimeout = () => {
+      clearTimeout(timeout);
+      resolve();
+    };
+
+    const existingScript = document.querySelector<HTMLScriptElement>(`script[src^="${TURNSTILE_SCRIPT_BASE_URL}"]`);
+    if (existingScript) {
+      // If the Turnstile API is already available (script loaded before our loader ran),
+      // resolve immediately — the load event may have already fired.
+      if (getTurnstileApi()) {
+        resolveAndClearTimeout();
+        return;
+      }
+      existingScript.addEventListener("load", () => resolveAndClearTimeout(), { once: true });
+      existingScript.addEventListener("error", () => {
+        existingScript.remove();
+        clearTimeout(timeout);
+        rejectAndReset(new Error("Failed to load Turnstile"));
+      }, { once: true });
+      return;
+    }
+
+    const script = document.createElement("script");
+    script.src = `${TURNSTILE_SCRIPT_BASE_URL}?render=explicit`;
+    script.async = true;
+    script.defer = true;
+    script.onload = () => resolveAndClearTimeout();
+    script.onerror = () => {
+      script.remove();
+      clearTimeout(timeout);
+      rejectAndReset(new Error("Failed to load Turnstile"));
+    };
+    document.head.append(script);
+  });
+
+  return turnstileScriptPromise;
+}

package/src/utils/turnstile-flow.test.ts

@@ -0,0 +1,101 @@
+// @vitest-environment jsdom
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const loadTurnstileScriptMock = vi.fn(() => Promise.resolve());
+const renderMock = vi.fn();
+const executeMock = vi.fn();
+const removeMock = vi.fn();
+const captureErrorMock = vi.fn();
+
+vi.mock("./turnstile-browser", () => ({
+  loadTurnstileScript: loadTurnstileScriptMock,
+  getTurnstileApi: () => ({
+    render: renderMock,
+    execute: executeMock,
+    remove: removeMock,
+  }),
+}));
+
+vi.mock("./errors", async () => {
+  const actual = await vi.importActual<typeof import("./errors")>("./errors");
+  return {
+    ...actual,
+    captureError: captureErrorMock,
+  };
+});
+
+describe("withBotChallengeFlow", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadTurnstileScriptMock.mockResolvedValue(undefined);
+    renderMock.mockImplementation((_container, config: {
+      callback: (token: string) => void,
+    }) => {
+      config.callback("invisible-token");
+      return "widget-id";
+    });
+    executeMock.mockImplementation(() => {});
+    removeMock.mockImplementation(() => {});
+  });
+
+  it("throws a bot challenge execution error when the phase-2 visible challenge fails", async () => {
+    const { BotChallengeExecutionFailedError, withBotChallengeFlow } = await import("./turnstile-flow");
+
+    loadTurnstileScriptMock
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(new Error("cloudflare unavailable"));
+
+    const execute = vi.fn(async ({ token, phase }: { token?: string, phase?: "invisible" | "visible" }) => {
+      if (token === "invisible-token" && phase === "invisible") {
+        return { requiresChallenge: true };
+      }
+      return { requiresChallenge: false };
+    });
+
+    await expect(withBotChallengeFlow({
+      visibleSiteKey: "visible-site-key",
+      invisibleSiteKey: "invisible-site-key",
+      action: "sign_up_with_credential",
+      execute,
+      isChallengeRequired: (result) => result.requiresChallenge,
+    })).rejects.toBeInstanceOf(BotChallengeExecutionFailedError);
+
+    expect(execute).toHaveBeenCalledTimes(1);
+    expect(execute).toHaveBeenCalledWith({
+      token: "invisible-token",
+      phase: "invisible",
+    });
+    expect(captureErrorMock).toHaveBeenCalledWith(
+      "turnstile-flow-visible-challenge-failed",
+      expect.any(Error),
+    );
+  });
+
+  it("marks the challenge as unavailable when both phase-1 challenge attempts fail", async () => {
+    const { withBotChallengeFlow } = await import("./turnstile-flow");
+
+    loadTurnstileScriptMock
+      .mockRejectedValueOnce(new Error("invisible unavailable"))
+      .mockRejectedValueOnce(new Error("visible unavailable"));
+
+    const execute = vi.fn(async ({ unavailable }: { unavailable?: true }) => ({
+      unavailable,
+    }));
+
+    await expect(withBotChallengeFlow({
+      visibleSiteKey: "visible-site-key",
+      invisibleSiteKey: "invisible-site-key",
+      action: "sign_up_with_credential",
+      execute,
+      isChallengeRequired: () => false,
+    })).resolves.toEqual({ unavailable: true });
+
+    expect(execute).toHaveBeenCalledTimes(1);
+    expect(execute).toHaveBeenCalledWith({ unavailable: true });
+    expect(captureErrorMock).toHaveBeenCalledWith(
+      "turnstile-flow-all-challenges-failed",
+      expect.any(Error),
+    );
+  });
+});

package/src/utils/turnstile-flow.ts

@@ -0,0 +1,266 @@
+import { HexclaveAssertionError, captureError } from "./errors";
+import { loadTurnstileScript, getTurnstileApi } from "./turnstile-browser";
+import type { TurnstileAction } from "./turnstile";
+
+export class BotChallengeUserCancelledError extends Error {
+  constructor() {
+    super("User cancelled the bot challenge");
+    this.name = "BotChallengeUserCancelledError";
+  }
+}
+
+export class BotChallengeExecutionFailedError extends Error {
+  constructor(message = "Bot challenge could not be completed", options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "BotChallengeExecutionFailedError";
+  }
+}
+
+
+// ── Invisible challenge ────────────────────────────────────────────────
+
+const INVISIBLE_TIMEOUT_MS = 30_000;
+
+export async function executeTurnstileInvisible(siteKey: string, action: TurnstileAction): Promise<string> {
+  await loadTurnstileScript();
+  const api = getTurnstileApi();
+  if (!api) throw new HexclaveAssertionError("Turnstile API not available after loadTurnstileScript() resolved");
+
+  const container = document.createElement("div");
+  Object.assign(container.style, { position: "fixed", left: "-9999px", top: "-9999px" });
+  document.body.appendChild(container);
+
+  let widgetId: string | undefined;
+  try {
+    return await new Promise<string>((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error("Turnstile invisible challenge timed out")),
+        INVISIBLE_TIMEOUT_MS,
+      );
+      const settle = (fn: () => void) => {
+        clearTimeout(timeout);
+        fn();
+      };
+
+      widgetId = api.render(container, {
+        sitekey: siteKey,
+        action,
+        size: "invisible",
+        execution: "execute",
+        appearance: "execute",
+        callback: (t) => settle(() => resolve(t)),
+        "error-callback": () => settle(() => reject(new Error("Turnstile invisible verification failed"))),
+        "expired-callback": () => settle(() => reject(new Error("Turnstile token expired"))),
+        "timeout-callback": () => settle(() => reject(new Error("Turnstile challenge timed out"))),
+      });
+
+      api.execute?.(widgetId);
+    });
+  } finally {
+    if (widgetId != null) {
+      try {
+        api.remove(widgetId);
+      } catch (e) {
+        captureError("turnstile-widget-remove", e instanceof Error ? e : new HexclaveAssertionError("Non-Error thrown during Turnstile widget removal", { cause: e }));
+      }
+    }
+    container.remove();
+  }
+}
+
+
+// ── Visible challenge overlay ──────────────────────────────────────────
+
+const VISIBLE_TIMEOUT_MS = 120_000;
+const OVERLAY_Z_INDEX = "999999";
+
+// Module-level singleton: only one visible overlay can be active at a time.
+// If a second challenge is requested while one is showing (e.g. user clicks another
+// auth flow), the previous overlay is cancelled with BotChallengeUserCancelledError
+// and cleaned up before the new one renders.
+let activeOverlay: { cleanup: () => void, reject: (err: Error) => void } | null = null;
+
+function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  style: Partial<CSSStyleDeclaration>,
+  props?: Record<string, string>,
+): HTMLElementTagNameMap[K] {
+  const element = document.createElement(tag);
+  Object.assign(element.style, style);
+  if (props) {
+    for (const [k, v] of Object.entries(props)) {
+      element.setAttribute(k, v);
+    }
+  }
+  return element;
+}
+
+export function showTurnstileVisibleChallenge(siteKey: string, action: TurnstileAction): Promise<string> {
+  if (activeOverlay) {
+    activeOverlay.reject(new BotChallengeUserCancelledError());
+    activeOverlay.cleanup();
+    activeOverlay = null;
+  }
+
+  return new Promise<string>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(new Error("Visible Turnstile challenge timed out"));
+    }, VISIBLE_TIMEOUT_MS);
+
+    const overlay = el("div", {
+      position: "fixed", inset: "0", zIndex: OVERLAY_Z_INDEX,
+      display: "flex", alignItems: "center", justifyContent: "center",
+      background: "rgba(0,0,0,0.5)", backdropFilter: "blur(2px)",
+    }, { "data-stack-turnstile-overlay": "true" });
+
+    const card = el("div", {
+      background: "white", borderRadius: "12px", padding: "24px",
+      maxWidth: "400px", width: "90%", textAlign: "center",
+      boxShadow: "0 4px 24px rgba(0,0,0,0.18)",
+      fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+    });
+
+    const title = el("p", { margin: "0 0 16px", fontSize: "16px", fontWeight: "600", color: "#333" });
+    title.textContent = "Please complete the security check";
+
+    const widgetContainer = el("div", { display: "flex", justifyContent: "center", minHeight: "65px" });
+
+    const errorText = el("p", { margin: "8px 0 0", fontSize: "14px", color: "#dc2626", display: "none" });
+
+    const cancelBtn = el("button", {
+      marginTop: "16px", padding: "8px 20px", border: "1px solid #ddd",
+      borderRadius: "6px", background: "transparent", cursor: "pointer",
+      fontSize: "14px", color: "#666",
+    });
+    cancelBtn.textContent = "Cancel";
+    cancelBtn.onmouseover = () => {
+      cancelBtn.style.background = "#f5f5f5";
+    };
+    cancelBtn.onmouseout = () => {
+      cancelBtn.style.background = "transparent";
+    };
+
+    card.append(title, widgetContainer, errorText, cancelBtn);
+    overlay.appendChild(card);
+    document.body.appendChild(overlay);
+
+    function cleanup() {
+      clearTimeout(timeout);
+      overlay.remove();
+      if (activeOverlay?.cleanup === cleanup) {
+        activeOverlay = null;
+      }
+    }
+
+    activeOverlay = { cleanup, reject };
+    cancelBtn.onclick = () => {
+      cleanup();
+      reject(new BotChallengeUserCancelledError());
+    };
+
+    loadTurnstileScript().then(() => {
+      const api = getTurnstileApi();
+      if (!api) {
+        cleanup();
+        reject(new HexclaveAssertionError("Turnstile API not available after loadTurnstileScript() resolved"));
+        return;
+      }
+
+      api.render(widgetContainer, {
+        sitekey: siteKey,
+        action,
+        appearance: "always",
+        execution: "render",
+        size: "flexible",
+        callback: (token) => {
+          cleanup();
+          resolve(token);
+        },
+        "error-callback": (errorCode) => {
+          errorText.textContent = errorCode ? `Verification error: ${errorCode}` : "Verification failed. Please try again.";
+          errorText.style.display = "block";
+        },
+        "expired-callback": () => {
+          errorText.textContent = "Challenge expired. Please solve it again.";
+          errorText.style.display = "block";
+        },
+      });
+    }).catch((err) => {
+      cleanup();
+      reject(err);
+    });
+  });
+}
+
+
+// ── Flow orchestrator ──────────────────────────────────────────────────
+
+export type BotChallengeExecuteParams = {
+  token?: string,
+  phase?: "invisible" | "visible",
+  unavailable?: true,
+};
+
+export type WithBotChallengeFlowOptions<T> = {
+  visibleSiteKey: string,
+  invisibleSiteKey: string,
+  action: TurnstileAction,
+  execute: (challenge: BotChallengeExecuteParams) => Promise<T>,
+  isChallengeRequired: (result: T) => boolean,
+};
+
+// We use separate invisible + visible flows (rather than Turnstile's "managed" mode) because:
+// 1. Managed mode auto-decides visibility, but we need deterministic server-side logic:
+//    invisible-fail → require visible challenge → fail = block.
+// 2. Invisible + visible use different site keys so the server can tell which phase passed.
+// 3. Managed mode doesn't expose an API to programmatically trigger a retry with a
+//    different widget type, which our two-phase challenge escalation requires.
+export async function withBotChallengeFlow<T>(options: WithBotChallengeFlowOptions<T>): Promise<T> {
+  // Server safe: no Turnstile in SSR — just call execute with no turnstile params
+  if (typeof window === "undefined") {
+    return await options.execute({});
+  }
+
+  // Phase 1: invisible token
+  let invisibleToken: string | undefined;
+  let usedVisibleFallback = false;
+  try {
+    invisibleToken = await executeTurnstileInvisible(options.invisibleSiteKey, options.action);
+  } catch {
+    try {
+      invisibleToken = await showTurnstileVisibleChallenge(options.visibleSiteKey, options.action);
+      usedVisibleFallback = true;
+    } catch (e) {
+      if (e instanceof BotChallengeUserCancelledError) throw e;
+      // Both challenges failed (for example Cloudflare is unreachable) — tell the
+      // server explicitly so it can distinguish challenge infra outages from a
+      // user submitting an invalid visible challenge.
+      captureError("turnstile-flow-all-challenges-failed", e instanceof Error ? e : new HexclaveAssertionError("Non-Error thrown during Turnstile challenge", { cause: e }));
+      return await options.execute({ unavailable: true });
+    }
+  }
+
+  const firstResult = await options.execute({
+    token: invisibleToken,
+    phase: invisibleToken ? (usedVisibleFallback ? "visible" : "invisible") : undefined,
+  });
+
+  if (!options.isChallengeRequired(firstResult)) {
+    return firstResult;
+  }
+
+  // Phase 2: visible challenge (single retry)
+  let visibleToken: string | undefined;
+  try {
+    visibleToken = await showTurnstileVisibleChallenge(options.visibleSiteKey, options.action);
+  } catch (e) {
+    if (e instanceof BotChallengeUserCancelledError) throw e;
+    captureError("turnstile-flow-visible-challenge-failed", e instanceof Error ? e : new HexclaveAssertionError("Non-Error thrown during visible Turnstile challenge", { cause: e }));
+    throw new BotChallengeExecutionFailedError("Visible bot challenge could not be completed", {
+      cause: e,
+    });
+  }
+
+  return await options.execute({ token: visibleToken, phase: "visible" });
+}

package/src/utils/turnstile.ts

@@ -0,0 +1,34 @@
+export const turnstileActionValues = [
+  "sign_up_with_credential",
+  "send_magic_link_email",
+  "oauth_authenticate",
+] as const;
+
+export type TurnstileAction = typeof turnstileActionValues[number];
+
+export const turnstilePhaseValues = [
+  "invisible",
+  "visible",
+] as const;
+
+export type TurnstilePhase = typeof turnstilePhaseValues[number];
+
+export const turnstileResultValues = [
+  "ok",
+  "invalid",
+  "error",
+] as const;
+
+export type TurnstileResult = typeof turnstileResultValues[number];
+
+export const turnstileDevelopmentKeys = {
+  visibleSiteKey: "1x00000000000000000000AA",
+  invisibleSiteKey: "1x00000000000000000000BB",
+  secretKey: "1x0000000000000000000000000000000AA",
+  forcedChallengeSiteKey: "3x00000000000000000000FF",
+} as const;
+
+
+export function isTurnstileResult(value: unknown): value is TurnstileResult {
+  return typeof value === "string" && turnstileResultValues.some((status) => status === value);
+}

package/src/utils/typed-arrays.tsx

@@ -0,0 +1,17 @@
+import { HexclaveAssertionError } from "./errors";
+
+/**
+ * Ensures a Uint8Array is backed by a regular ArrayBuffer (not SharedArrayBuffer).
+ *
+ * TypeScript 5.7+ made typed arrays generic over their buffer type. Bare `Uint8Array`
+ * defaults to `Uint8Array<ArrayBufferLike>`, which includes SharedArrayBuffer. Web Crypto
+ * APIs require `BufferSource` which only accepts `ArrayBufferView<ArrayBuffer>`. This
+ * function narrows the type using an instanceof guard, creating a same-buffer view
+ * (zero-copy) when the buffer is already an ArrayBuffer.
+ */
+export function toArrayBufferBacked(arr: Uint8Array): Uint8Array<ArrayBuffer> {
+  if (arr.buffer instanceof SharedArrayBuffer) {
+    throw new HexclaveAssertionError("SharedArrayBuffer-backed Uint8Arrays are not supported in this context");
+  }
+  return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+}