@maggidev/captchashield 1.0.0

package/dist/index.mjs

@@ -0,0 +1,611 @@
+// src/errors.ts
+var CaptchaShieldError = class _CaptchaShieldError extends Error {
+  constructor(message, originalError) {
+    super(`[CaptchaShield] ${message}`);
+    this.originalError = originalError;
+    this.name = "CaptchaShieldError";
+    const maybeCaptureStackTrace = Error.captureStackTrace;
+    maybeCaptureStackTrace?.(this, _CaptchaShieldError);
+  }
+};
+
+// src/cookies.ts
+var COOKIE_NAME_RE = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
+function assertValidCookieName(name) {
+  if (!name || !COOKIE_NAME_RE.test(name)) {
+    throw new CaptchaShieldError(
+      `Invalid cookie.name "${name}": must be a valid RFC 6265 token (printable ASCII, no separators or control characters).`
+    );
+  }
+}
+function assertValidCookieAttributeValue(value, attr) {
+  if (value.includes(";")) {
+    throw new CaptchaShieldError(
+      `Invalid cookie.${attr} "${value}": must not contain semicolons.`
+    );
+  }
+}
+function hasCookie(name) {
+  if (typeof document === "undefined") return false;
+  return document.cookie.split(";").some((item) => item.trim().startsWith(`${name}=`));
+}
+function setCookie(options, value) {
+  assertValidCookieName(options.name);
+  if (options.domain) assertValidCookieAttributeValue(options.domain, "domain");
+  assertValidCookieAttributeValue(options.path, "path");
+  const attributes = [
+    `path=${options.path}`,
+    `max-age=${options.maxAgeSeconds}`,
+    options.domain ? `domain=${options.domain}` : "",
+    options.secure ? "secure" : "",
+    options.sameSite ? `samesite=${options.sameSite}` : ""
+  ].filter(Boolean).join("; ");
+  document.cookie = `${options.name}=${encodeURIComponent(value)}; ${attributes}`;
+}
+function clearCookie(options) {
+  assertValidCookieName(options.name);
+  if (options.domain) assertValidCookieAttributeValue(options.domain, "domain");
+  assertValidCookieAttributeValue(options.path, "path");
+  const attributes = [
+    `expires=Thu, 01 Jan 1970 00:00:00 GMT`,
+    `path=${options.path}`,
+    options.domain ? `domain=${options.domain}` : "",
+    options.secure ? "secure" : "",
+    options.sameSite ? `samesite=${options.sameSite}` : ""
+  ].filter(Boolean).join("; ");
+  document.cookie = `${options.name}=; ${attributes}`;
+}
+function deriveCookieName(baseName, options) {
+  if (!options.useScopePrefix) return baseName;
+  const scope = options.scopeId ?? deriveScopeId();
+  return scope ? `${baseName}_${scope}` : baseName;
+}
+function deriveScopeId() {
+  if (typeof window === "undefined") return void 0;
+  try {
+    return window.location.hostname.replace(/\./g, "_");
+  } catch {
+    return void 0;
+  }
+}
+
+// src/renderer.ts
+function renderDefaultModal({ challengeContainer, config, close }) {
+  const overlay = document.createElement("div");
+  const panel = document.createElement("div");
+  const header = document.createElement("div");
+  const title = document.createElement("h2");
+  const closeButton = document.createElement("button");
+  const body = document.createElement("p");
+  const helper = document.createElement("p");
+  overlay.setAttribute("role", "presentation");
+  overlay.className = config.modal.styles.overlayClass;
+  overlay.setAttribute("data-captcha-shield", "overlay");
+  panel.className = config.modal.styles.panelClass;
+  panel.setAttribute("role", "dialog");
+  panel.setAttribute("aria-modal", "true");
+  panel.setAttribute("aria-label", config.modal.ariaLabel);
+  panel.setAttribute("data-captcha-shield", "panel");
+  header.className = "captcha-shield__header";
+  title.className = config.modal.styles.titleClass;
+  title.textContent = config.modal.copy.title;
+  closeButton.type = "button";
+  closeButton.className = "captcha-shield__close";
+  closeButton.setAttribute("aria-label", "Close verification dialog");
+  closeButton.textContent = "Close";
+  closeButton.addEventListener("click", close);
+  body.className = config.modal.styles.bodyClass;
+  body.textContent = config.modal.copy.body;
+  helper.className = config.modal.styles.helperClass;
+  helper.textContent = config.modal.copy.helperText;
+  header.appendChild(title);
+  header.appendChild(closeButton);
+  panel.appendChild(header);
+  panel.appendChild(body);
+  panel.appendChild(challengeContainer);
+  panel.appendChild(helper);
+  overlay.appendChild(panel);
+  let injectedStyle = null;
+  if (config.modal.injectDefaultStyle) {
+    injectedStyle = injectStyle(defaultStyleSheet(config.modal.styles.customCss));
+  } else if (config.modal.styles.customCss.trim().length > 0) {
+    injectedStyle = injectStyle(config.modal.styles.customCss);
+  }
+  return {
+    root: overlay,
+    destroy: () => {
+      overlay.remove();
+      injectedStyle?.remove();
+    }
+  };
+}
+function injectStyle(css) {
+  if (!css.trim()) return null;
+  const style = document.createElement("style");
+  style.setAttribute("data-captcha-shield-style", "true");
+  style.textContent = css;
+  document.head.appendChild(style);
+  return style;
+}
+function defaultStyleSheet(customCss) {
+  const base = `
+.captcha-shield__overlay { position: fixed; inset: 0; background: rgba(15, 23, 42, 0.48); display: flex; align-items: center; justify-content: center; padding: 20px; z-index: 9999; }
+.captcha-shield__panel { width: min(480px, 100%); background: #ffffff; color: #111827; border: 1px solid #d4d4d8; border-radius: 10px; box-shadow: 0 6px 24px rgba(15, 23, 42, 0.12); padding: 20px; font-family: inherit; display: flex; flex-direction: column; gap: 16px; }
+.captcha-shield__header { display: flex; align-items: start; justify-content: space-between; gap: 16px; }
+.captcha-shield__title { margin: 0; font-size: 1.125rem; line-height: 1.35; font-weight: 650; }
+.captcha-shield__close { appearance: none; border: 1px solid #d4d4d8; background: #ffffff; color: #374151; border-radius: 8px; padding: 7px 10px; font: inherit; font-size: 0.875rem; font-weight: 600; cursor: pointer; }
+.captcha-shield__close:hover { background: #f4f4f5; }
+.captcha-shield__body { margin: 0; line-height: 1.6; color: #1f2937; }
+.captcha-shield__helper { margin: 0; font-size: 0.9375rem; color: #52525b; }
+[data-captcha-shield="challenge"] { min-height: 70px; display: flex; align-items: center; justify-content: center; }
+`;
+  return `${base}${customCss ?? ""}`;
+}
+
+// src/validation.ts
+var ABSOLUTE_URL_PATTERN = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+var LOCALHOST_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function validateRequestEndpoint(endpoint, fieldName) {
+  const trimmed = endpoint.trim();
+  if (!trimmed) {
+    throw new CaptchaShieldError(`Configuration field "${fieldName}" cannot be empty.`);
+  }
+  if (trimmed.startsWith("//")) {
+    throw new CaptchaShieldError(`Configuration field "${fieldName}" must not use protocol-relative URLs.`);
+  }
+  if (!ABSOLUTE_URL_PATTERN.test(trimmed)) {
+    return trimmed;
+  }
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new CaptchaShieldError(`Configuration field "${fieldName}" must be a valid URL.`);
+  }
+  if (url.protocol === "https:") {
+    return url.toString();
+  }
+  if (url.protocol === "http:" && LOCALHOST_HOSTNAMES.has(url.hostname)) {
+    return url.toString();
+  }
+  throw new CaptchaShieldError(
+    `Configuration field "${fieldName}" must use HTTPS. Plain HTTP is only allowed for localhost development.`
+  );
+}
+function validateTurnstileScriptUrl(scriptUrl) {
+  let url;
+  try {
+    url = new URL(scriptUrl);
+  } catch {
+    throw new CaptchaShieldError("turnstileScriptUrl must be a valid absolute URL.");
+  }
+  if (url.protocol !== "https:") {
+    throw new CaptchaShieldError("turnstileScriptUrl must use HTTPS.");
+  }
+  if (url.hostname !== "challenges.cloudflare.com" || !url.pathname.startsWith("/turnstile/")) {
+    throw new CaptchaShieldError(
+      "turnstileScriptUrl must point to the official Cloudflare Turnstile host."
+    );
+  }
+  return url.toString();
+}
+
+// src/turnstile.ts
+var turnstileLoaders = /* @__PURE__ */ new Map();
+function ensureTurnstile(scriptUrl, integrity) {
+  requireDom();
+  if (window.turnstile) {
+    assertTurnstile(integrity);
+    return Promise.resolve(window.turnstile);
+  }
+  const existing = turnstileLoaders.get(scriptUrl);
+  if (existing) return existing;
+  const loader = loadTurnstileScript(scriptUrl, integrity).catch((err) => {
+    turnstileLoaders.delete(scriptUrl);
+    throw err;
+  });
+  turnstileLoaders.set(scriptUrl, loader);
+  return loader;
+}
+function loadTurnstileScript(scriptUrl, integrity) {
+  return new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = validateTurnstileScriptUrl(scriptUrl);
+    script.async = true;
+    if (integrity.scriptIntegrity) {
+      script.integrity = integrity.scriptIntegrity;
+      script.crossOrigin = "anonymous";
+    }
+    script.onload = () => {
+      if (window.turnstile) {
+        try {
+          assertTurnstile(integrity);
+          resolve(window.turnstile);
+        } catch (err) {
+          reject(err);
+        }
+      } else {
+        reject(new CaptchaShieldError('Turnstile script loaded but "window.turnstile" is missing.'));
+      }
+    };
+    script.onerror = () => reject(new CaptchaShieldError(`Failed to load Turnstile script from ${scriptUrl}`));
+    document.head.appendChild(script);
+  });
+}
+function assertTurnstile(integrity) {
+  if (!integrity.verifyTurnstileGlobal) return;
+  const t = window.turnstile;
+  if (!t || typeof t.render !== "function") {
+    throw new CaptchaShieldError("Global integrity check failed: window.turnstile.render is missing.");
+  }
+}
+function requireDom() {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    throw new CaptchaShieldError("Library requires a browser DOM environment.");
+  }
+}
+
+// src/network.ts
+async function fetchWithTimeout(url, init, timeoutMs) {
+  const timeoutController = new AbortController();
+  const merged = mergeSignals([init.signal, timeoutController.signal].filter(Boolean));
+  const timer = setTimeout(() => timeoutController.abort(new CaptchaShieldError("Request timed out")), timeoutMs);
+  try {
+    const signal = merged ? merged.signal : init.signal;
+    return await fetch(url, { ...init, signal });
+  } finally {
+    clearTimeout(timer);
+    merged?.cleanup();
+  }
+}
+function isExpectedStatus(status, expected) {
+  if (typeof expected === "function") {
+    return expected(status);
+  }
+  return status === expected;
+}
+function mergeSignals(signals) {
+  if (signals.length === 0) return void 0;
+  const controller = new AbortController();
+  const abortHandler = (event) => {
+    const signal = event.target;
+    controller.abort(signal?.reason);
+  };
+  signals.forEach((sig) => {
+    if (sig.aborted) {
+      if (!controller.signal.aborted) controller.abort(sig.reason);
+    } else {
+      sig.addEventListener("abort", abortHandler, { once: true });
+    }
+  });
+  const cleanup = () => {
+    signals.forEach((sig) => sig.removeEventListener("abort", abortHandler));
+  };
+  if (controller.signal.aborted) {
+    cleanup();
+    return { signal: controller.signal, cleanup: () => {
+    } };
+  }
+  controller.signal.addEventListener("abort", cleanup, { once: true });
+  return { signal: controller.signal, cleanup };
+}
+
+// src/verification.ts
+async function runStatusCheck(status) {
+  if (!status.endpoint) return;
+  const response = await fetchWithTimeout(status.endpoint, { method: "GET" }, status.timeoutMs);
+  if (!isExpectedStatus(response.status, status.expectedStatus)) {
+    throw new CaptchaShieldError(`Status check failed with status: ${response.status}`);
+  }
+}
+async function verifyTokenWithServer(token, verify) {
+  if (!verify.endpoint) return true;
+  let lastError = null;
+  for (let attempt = 0; attempt <= verify.retries; attempt++) {
+    try {
+      const response = await requestVerification(token, verify);
+      if (isExpectedStatus(response.status, verify.expectedStatus)) {
+        return true;
+      }
+      lastError = new CaptchaShieldError(`Verification failed with status: ${response.status}`);
+    } catch (err) {
+      lastError = err instanceof Error ? err : new CaptchaShieldError(String(err));
+    }
+  }
+  if (lastError) {
+    throw lastError;
+  }
+  return false;
+}
+async function requestVerification(token, verify) {
+  const init = {
+    method: verify.method,
+    headers: verify.headers
+  };
+  const body = verify.buildBody(token);
+  if (body) {
+    init.body = body;
+  }
+  return fetchWithTimeout(verify.endpoint ?? "", init, verify.timeoutMs);
+}
+
+// src/shield.ts
+var DEFAULT_SCRIPT_URL = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+var DEFAULT_COOKIE_NAME = "captchaShieldVerified";
+var DEFAULT_MODAL_COPY = {
+  title: "Please verify you are human",
+  body: "Complete the Cloudflare Turnstile check to continue. A short-lived cookie will skip this step until it expires.",
+  helperText: "No data is stored beyond the verification cookie and the Turnstile token."
+};
+var DEFAULT_MODAL_STYLES = {
+  overlayClass: "captcha-shield__overlay",
+  panelClass: "captcha-shield__panel",
+  titleClass: "captcha-shield__title",
+  bodyClass: "captcha-shield__body",
+  helperClass: "captcha-shield__helper",
+  customCss: ""
+};
+var DEFAULT_MODAL = {
+  copy: DEFAULT_MODAL_COPY,
+  styles: DEFAULT_MODAL_STYLES,
+  ariaLabel: "Human verification dialog",
+  closeOnVerify: true,
+  injectDefaultStyle: true
+};
+var DEFAULT_COOKIE = {
+  name: DEFAULT_COOKIE_NAME,
+  maxAgeSeconds: 60 * 60 * 24,
+  path: "/",
+  sameSite: "Lax",
+  secure: true,
+  scopeId: void 0,
+  useScopePrefix: false,
+  trustClientCookie: false
+};
+var DEFAULT_VERIFY = {
+  endpoint: void 0,
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  timeoutMs: 5e3,
+  retries: 1,
+  buildBody: (token) => JSON.stringify({ token }),
+  expectedStatus: (status) => status >= 200 && status < 300
+};
+var DEFAULT_STATUS = {
+  endpoint: void 0,
+  timeoutMs: 3e3,
+  expectedStatus: (status) => status >= 200 && status < 400
+};
+var DEFAULT_INTEGRITY = {
+  scriptIntegrity: void 0,
+  verifyTurnstileGlobal: true,
+  enforceChallengePresence: true,
+  monitorChallengeRemoval: false
+};
+function createCaptchaShield(config) {
+  const resolved = resolveConfig(config);
+  let verified = false;
+  let token = null;
+  let rendererHandle = null;
+  let challengeTarget = null;
+  let widgetId = null;
+  let opening = null;
+  let lastTurnstile = null;
+  let verifying = null;
+  let integrityWatch = null;
+  let currentOpenId = 0;
+  const isAlreadyVerified = () => verified || resolved.cookie.trustClientCookie && hasCookie(resolved.cookie.name);
+  const close = () => {
+    currentOpenId++;
+    if (widgetId && lastTurnstile?.remove) {
+      lastTurnstile.remove(widgetId);
+      widgetId = null;
+    }
+    if (rendererHandle) {
+      rendererHandle.destroy?.();
+      rendererHandle.root.remove();
+      rendererHandle = null;
+    }
+    if (integrityWatch) {
+      integrityWatch.stop();
+      integrityWatch = null;
+    }
+    challengeTarget = null;
+  };
+  const reset = () => {
+    token = null;
+    verified = false;
+    clearCookie(resolved.cookie);
+    if (widgetId && lastTurnstile?.reset) {
+      lastTurnstile.reset(widgetId);
+    }
+    widgetId = null;
+  };
+  const destroy = () => {
+    reset();
+    close();
+  };
+  const renderModal = (turnstile) => {
+    const challengeContainer = document.createElement("div");
+    challengeContainer.setAttribute("data-captcha-shield", "challenge");
+    const handle = resolved.render ? resolved.render({ challengeContainer, config: resolved, close }) : renderDefaultModal({ challengeContainer, config: resolved, close });
+    if (!handle.root.contains(challengeContainer)) {
+      handle.root.appendChild(challengeContainer);
+    }
+    document.body.appendChild(handle.root);
+    lastTurnstile = turnstile;
+    rendererHandle = handle;
+    challengeTarget = challengeContainer;
+    if (resolved.integrity.monitorChallengeRemoval) {
+      integrityWatch = startIntegrityWatch(challengeContainer, () => {
+        handleError("Challenge container was removed. Possible tampering detected.");
+        destroy();
+      });
+    }
+  };
+  const open = async () => {
+    const cookieVerified = resolved.cookie.trustClientCookie && hasCookie(resolved.cookie.name);
+    if (verified || cookieVerified) {
+      verified = true;
+      return { status: "already-verified", reason: cookieVerified ? "cookie" : "session" };
+    }
+    if (opening) {
+      return opening;
+    }
+    const myId = ++currentOpenId;
+    opening = (async () => {
+      requireDom();
+      await runStatusCheck(resolved.statusCheck);
+      if (myId !== currentOpenId) throw new CaptchaShieldError("Operation cancelled by close()");
+      const turnstile = await ensureTurnstile(resolved.turnstileScriptUrl, resolved.integrity);
+      if (myId !== currentOpenId) throw new CaptchaShieldError("Operation cancelled by close()");
+      renderModal(turnstile);
+      if (!challengeTarget) {
+        if (resolved.integrity.enforceChallengePresence) {
+          throw new CaptchaShieldError("Failed to mount a challenge container.");
+        }
+        challengeTarget = document.createElement("div");
+      }
+      widgetId = turnstile.render(challengeTarget, {
+        sitekey: resolved.siteKey,
+        action: resolved.action,
+        cData: resolved.cData,
+        callback: handleVerified,
+        "error-callback": (message) => handleError(message ?? "Turnstile error"),
+        "timeout-callback": () => handleError("Turnstile timed out")
+      });
+      return { status: "rendered" };
+    })();
+    try {
+      return await opening;
+    } finally {
+      opening = null;
+    }
+  };
+  const handleVerified = (turnstileToken) => {
+    token = turnstileToken;
+    const finalize = () => {
+      verified = true;
+      if (resolved.cookie.trustClientCookie) {
+        setCookie(resolved.cookie, "1");
+      }
+      resolved.onVerified?.(turnstileToken);
+      if (resolved.modal.closeOnVerify) {
+        close();
+      }
+    };
+    const resetWidget = () => {
+      if (widgetId && lastTurnstile?.reset) {
+        lastTurnstile.reset(widgetId);
+      }
+    };
+    const executeVerification = async () => {
+      if (!resolved.verify.endpoint) {
+        finalize();
+        return;
+      }
+      const ok = await verifyTokenWithServer(turnstileToken, resolved.verify);
+      if (!ok) {
+        resetWidget();
+        handleError("Server verification rejected token");
+        return;
+      }
+      finalize();
+    };
+    if (!verifying) {
+      verifying = executeVerification().catch((err) => {
+        resetWidget();
+        handleError(normalizeErrorMessage(err));
+      }).finally(() => {
+        verifying = null;
+      });
+    }
+  };
+  const handleError = (message) => {
+    resolved.onError?.(new CaptchaShieldError(message));
+  };
+  return {
+    open,
+    close,
+    reset,
+    destroy,
+    isVerified: () => isAlreadyVerified(),
+    getToken: () => token
+  };
+}
+function resolveConfig(config) {
+  if (!config.siteKey) {
+    throw new CaptchaShieldError('Configuration missing required "siteKey".');
+  }
+  const modalCopy = { ...DEFAULT_MODAL_COPY, ...config.modal?.copy ?? {} };
+  const modalStyles = { ...DEFAULT_MODAL_STYLES, ...config.modal?.styles ?? {} };
+  const modal = {
+    ...DEFAULT_MODAL,
+    ...config.modal ?? {},
+    copy: modalCopy,
+    styles: modalStyles
+  };
+  const cookieBase = config.cookie ?? {};
+  const cookie = { ...DEFAULT_COOKIE, ...cookieBase };
+  cookie.name = deriveCookieName(cookieBase.name ?? DEFAULT_COOKIE_NAME, cookie);
+  const verify = { ...DEFAULT_VERIFY, ...config.verify ?? {} };
+  const statusCheck = { ...DEFAULT_STATUS, ...config.statusCheck ?? {} };
+  const integrity = { ...DEFAULT_INTEGRITY, ...config.integrity ?? {} };
+  if (config.verify?.method && config.verify.method !== "POST") {
+    throw new CaptchaShieldError('verify.method only supports "POST".');
+  }
+  const turnstileScriptUrl = validateTurnstileScriptUrl(config.turnstileScriptUrl ?? DEFAULT_SCRIPT_URL);
+  if (verify.endpoint) {
+    verify.endpoint = validateRequestEndpoint(verify.endpoint, "verify.endpoint");
+  }
+  if (statusCheck.endpoint) {
+    statusCheck.endpoint = validateRequestEndpoint(statusCheck.endpoint, "statusCheck.endpoint");
+  }
+  return {
+    siteKey: config.siteKey,
+    action: config.action,
+    cData: config.cData,
+    turnstileScriptUrl,
+    modal,
+    cookie,
+    verify,
+    statusCheck,
+    integrity,
+    render: config.render,
+    onVerified: config.onVerified,
+    onError: config.onError
+  };
+}
+function startIntegrityWatch(element, onTamper) {
+  if (!element.isConnected) {
+    onTamper();
+    return { stop: () => void 0 };
+  }
+  const observer = new MutationObserver(() => {
+    if (!element.isConnected) {
+      onTamper();
+      observer.disconnect();
+    }
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+  return {
+    observer,
+    stop: () => observer.disconnect()
+  };
+}
+function normalizeErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message.replace(/^\[CaptchaShield\]\s*/, "");
+  }
+  return String(error);
+}
+export {
+  CaptchaShieldError,
+  DEFAULT_COOKIE_NAME,
+  DEFAULT_SCRIPT_URL,
+  clearCookie,
+  createCaptchaShield,
+  hasCookie,
+  setCookie
+};
+//# sourceMappingURL=index.mjs.map