engagelab-captcha-sdk 1.0.0

package/src/challenges/spatial.ts

@@ -0,0 +1,91 @@
+import { t } from '../i18n';
+
+export interface SpatialResult {
+  answerIndex: number;
+  passtime: number;
+}
+
+export class SpatialChallenge {
+  private resolve?: (result: SpatialResult) => void;
+  private startTime = 0;
+
+  create(imageBase64: string, question: string, options: string[]): {
+    element: HTMLElement;
+    promise: Promise<SpatialResult>;
+  } {
+    this.startTime = performance.now();
+
+    const wrapper = document.createElement('div');
+    const title = document.createElement('div');
+    title.className = 'elc-title';
+    title.textContent = t('spatial.title');
+
+    const imgContainer = document.createElement('div');
+    imgContainer.className = 'elc-image-container';
+    const img = document.createElement('img');
+    img.src = `data:image/png;base64,${imageBase64}`;
+    img.alt = t('challenge.imageAlt');
+    img.draggable = false;
+    imgContainer.appendChild(img);
+
+    const questionEl = document.createElement('div');
+    questionEl.className = 'elc-question';
+    questionEl.textContent = question;
+
+    const optionsEl = document.createElement('div');
+    optionsEl.className = 'elc-options';
+    optionsEl.setAttribute('role', 'radiogroup');
+    optionsEl.setAttribute('aria-label', question);
+
+    const promise = new Promise<SpatialResult>((resolve) => {
+      this.resolve = resolve;
+    });
+
+    options.forEach((opt, idx) => {
+      const btn = document.createElement('div');
+      btn.className = 'elc-option';
+      btn.setAttribute('role', 'radio');
+      btn.setAttribute('aria-checked', 'false');
+      btn.setAttribute('tabindex', idx === 0 ? '0' : '-1');
+      btn.textContent = `${String.fromCharCode(65 + idx)}. ${opt}`;
+
+      const selectOption = () => {
+        optionsEl.querySelectorAll('.elc-option').forEach(el => {
+          el.classList.remove('selected');
+          el.setAttribute('aria-checked', 'false');
+          el.setAttribute('tabindex', '-1');
+        });
+        btn.classList.add('selected');
+        btn.setAttribute('aria-checked', 'true');
+        btn.setAttribute('tabindex', '0');
+        btn.focus();
+        const passtime = performance.now() - this.startTime;
+        this.resolve?.({ answerIndex: idx, passtime });
+      };
+
+      btn.addEventListener('click', selectOption);
+      btn.addEventListener('keydown', (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          selectOption();
+        } else if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
+          e.preventDefault();
+          const next = optionsEl.children[(idx + 1) % options.length] as HTMLElement;
+          next?.focus();
+        } else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
+          e.preventDefault();
+          const prev = optionsEl.children[(idx - 1 + options.length) % options.length] as HTMLElement;
+          prev?.focus();
+        }
+      });
+      optionsEl.appendChild(btn);
+    });
+
+    wrapper.appendChild(title);
+    wrapper.appendChild(imgContainer);
+    wrapper.appendChild(questionEl);
+    wrapper.appendChild(optionsEl);
+
+    return { element: wrapper, promise };
+  }
+}

package/src/compat/hcaptcha.ts

@@ -0,0 +1,112 @@
+/**
+ * hCaptcha compatibility adapter.
+ *
+ * Registers `window.hcaptcha` with the standard API surface:
+ *   hcaptcha.render(el, params), hcaptcha.execute(widgetId), hcaptcha.reset(widgetId),
+ *   hcaptcha.getResponse(widgetId)
+ *
+ * All calls delegate to an internal EngageLabCaptcha instance.
+ */
+import { EngageLabCaptcha } from '../index';
+import type { CaptchaConfig } from '../types';
+
+interface HCaptchaRenderParams {
+  sitekey?: string;
+  callback?: (token: string) => void;
+  'expired-callback'?: () => void;
+  'error-callback'?: (err: any) => void;
+  size?: 'invisible' | 'normal' | 'compact';
+  theme?: 'light' | 'dark';
+}
+
+interface HCaptchaApi {
+  render: (container: string | HTMLElement, params: HCaptchaRenderParams) => string;
+  execute: (widgetId?: string) => Promise<{ response: string }>;
+  reset: (widgetId?: string) => void;
+  getResponse: (widgetId?: string) => string;
+}
+
+const instances = new Map<string, { captcha: EngageLabCaptcha; params: HCaptchaRenderParams; lastToken: string }>();
+let nextId = 0;
+
+function createHCaptcha(apiBase: string): HCaptchaApi {
+  return {
+    render(container: string | HTMLElement, params: HCaptchaRenderParams): string {
+      const widgetId = `hc-${nextId++}`;
+      const siteKey = params.sitekey || '';
+
+      const config: CaptchaConfig = {
+        siteKey,
+        apiBase,
+        mode: params.size === 'invisible' ? 'invisible' : 'popup',
+        theme: params.theme === 'dark' ? { darkMode: true } : undefined,
+        onSuccess: (token) => {
+          const entry = instances.get(widgetId);
+          if (entry) entry.lastToken = token;
+          params.callback?.(token);
+        },
+        onFail: (err) => {
+          params['error-callback']?.(err);
+        },
+      };
+
+      const captcha = new EngageLabCaptcha(config);
+      instances.set(widgetId, { captcha, params, lastToken: '' });
+
+      if (params.size !== 'invisible') {
+        const el = typeof container === 'string'
+          ? document.getElementById(container)
+          : container;
+        if (el) {
+          const trigger = document.createElement('div');
+          trigger.style.cssText = 'cursor:pointer;display:inline-block;';
+          trigger.textContent = "I'm not a robot";
+          trigger.addEventListener('click', () => captcha.execute());
+          el.appendChild(trigger);
+        }
+      }
+
+      return widgetId;
+    },
+
+    execute(widgetId?: string): Promise<{ response: string }> {
+      const id = widgetId || Array.from(instances.keys())[0];
+      const entry = instances.get(id);
+      if (!entry) return Promise.reject(new Error('No hCaptcha widget found'));
+
+      return new Promise((resolve, reject) => {
+        const origCallback = entry.params.callback;
+        entry.params.callback = (token: string) => {
+          entry.lastToken = token;
+          origCallback?.(token);
+          resolve({ response: token });
+        };
+        const origError = entry.params['error-callback'];
+        entry.params['error-callback'] = (err: any) => {
+          origError?.(err);
+          reject(err);
+        };
+        entry.captcha.execute();
+      });
+    },
+
+    reset(widgetId?: string) {
+      const id = widgetId || Array.from(instances.keys())[0];
+      const entry = instances.get(id);
+      if (entry) {
+        entry.lastToken = '';
+        entry.captcha.reset();
+      }
+    },
+
+    getResponse(widgetId?: string): string {
+      const id = widgetId || Array.from(instances.keys())[0];
+      return instances.get(id)?.lastToken || '';
+    },
+  };
+}
+
+export function installHCaptchaCompat(apiBase: string): void {
+  if (typeof window === 'undefined') return;
+  (window as any).hcaptcha = createHCaptcha(apiBase);
+}

package/src/compat/recaptcha.ts

@@ -0,0 +1,108 @@
+/**
+ * reCAPTCHA v2/v3 compatibility adapter.
+ *
+ * Registers `window.grecaptcha` with the standard API surface:
+ *   grecaptcha.ready(cb), grecaptcha.render(el, params), grecaptcha.execute(siteKey, opts),
+ *   grecaptcha.reset(widgetId)
+ *
+ * All calls delegate to an internal EngageLabCaptcha instance.
+ */
+import { EngageLabCaptcha } from '../index';
+import type { CaptchaConfig } from '../types';
+
+interface GrecaptchaRenderParams {
+  sitekey?: string;
+  callback?: (token: string) => void;
+  'expired-callback'?: () => void;
+  'error-callback'?: (err: any) => void;
+  size?: 'invisible' | 'normal' | 'compact';
+  theme?: 'light' | 'dark';
+}
+
+interface GrecaptchaApi {
+  ready: (cb: () => void) => void;
+  render: (container: string | HTMLElement, params: GrecaptchaRenderParams) => number;
+  execute: (siteKey?: string, opts?: { action?: string }) => Promise<string>;
+  reset: (widgetId?: number) => void;
+}
+
+const instances = new Map<number, { captcha: EngageLabCaptcha; params: GrecaptchaRenderParams }>();
+let nextWidgetId = 0;
+
+function createGrecaptcha(apiBase: string): GrecaptchaApi {
+  return {
+    ready(cb: () => void) {
+      if (typeof cb === 'function') cb();
+    },
+
+    render(container: string | HTMLElement, params: GrecaptchaRenderParams): number {
+      const widgetId = nextWidgetId++;
+      const siteKey = params.sitekey || '';
+
+      const config: CaptchaConfig = {
+        siteKey,
+        apiBase,
+        mode: params.size === 'invisible' ? 'invisible' : 'popup',
+        theme: params.theme === 'dark' ? { darkMode: true } : undefined,
+        onSuccess: (token) => {
+          params.callback?.(token);
+        },
+        onFail: (err) => {
+          params['error-callback']?.(err);
+        },
+      };
+
+      const captcha = new EngageLabCaptcha(config);
+      instances.set(widgetId, { captcha, params });
+
+      if (params.size !== 'invisible') {
+        const el = typeof container === 'string'
+          ? document.getElementById(container)
+          : container;
+        if (el) {
+          const trigger = document.createElement('div');
+          trigger.style.cssText = 'cursor:pointer;display:inline-block;';
+          trigger.textContent = "I'm not a robot";
+          trigger.addEventListener('click', () => captcha.execute());
+          el.appendChild(trigger);
+        }
+      }
+
+      return widgetId;
+    },
+
+    execute(siteKey?: string, _opts?: { action?: string }): Promise<string> {
+      const entry = siteKey
+        ? Array.from(instances.values()).find(e => e.params.sitekey === siteKey)
+        : instances.get(0);
+
+      if (!entry) {
+        return Promise.reject(new Error('No reCAPTCHA widget found'));
+      }
+
+      return new Promise((resolve, reject) => {
+        const origSuccess = entry.params.callback;
+        entry.params.callback = (token: string) => {
+          origSuccess?.(token);
+          resolve(token);
+        };
+        const origError = entry.params['error-callback'];
+        entry.params['error-callback'] = (err: any) => {
+          origError?.(err);
+          reject(err);
+        };
+        entry.captcha.execute();
+      });
+    },
+
+    reset(widgetId?: number) {
+      const entry = instances.get(widgetId ?? 0);
+      entry?.captcha.reset();
+    },
+  };
+}
+
+export function installRecaptchaCompat(apiBase: string): void {
+  if (typeof window === 'undefined') return;
+  (window as any).grecaptcha = createGrecaptcha(apiBase);
+}

package/src/crypto.ts

@@ -0,0 +1,69 @@
+/**
+ * Communication security: AES-256-GCM encryption + HMAC-SHA256 signing.
+ * MVP uses a simplified approach with server-provided key material.
+ */
+
+export async function encryptPayload(data: any, sessionKey: string): Promise<{ encrypted: string; iv: string; hmac: string }> {
+  const plaintext = JSON.stringify(data);
+  const encoder = new TextEncoder();
+
+  const sessionKeyBytes = encoder.encode(sessionKey);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', sessionKeyBytes);
+  const aesKeyMaterial = await crypto.subtle.importKey(
+    'raw', hashBuffer,
+    { name: 'AES-GCM' }, false, ['encrypt']
+  );
+
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const encrypted = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    aesKeyMaterial,
+    encoder.encode(plaintext)
+  );
+
+  const hmacKey = await crypto.subtle.importKey(
+    'raw', encoder.encode(sessionKey),
+    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
+  );
+  const signature = await crypto.subtle.sign('HMAC', hmacKey, encrypted);
+
+  return {
+    encrypted: arrayBufferToBase64(encrypted),
+    iv: arrayBufferToBase64(iv),
+    hmac: arrayBufferToBase64(signature),
+  };
+}
+
+export async function createRequestSignature(
+  method: string, path: string, body: string, timestamp: number, nonce: string, secretKey: string,
+): Promise<string> {
+  const message = `${method}\n${path}\n${body}\n${timestamp}\n${nonce}`;
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw', encoder.encode(secretKey),
+    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
+  );
+  const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(message));
+  return arrayBufferToBase64(sig);
+}
+
+export function generateNonce(): string {
+  const arr = crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer | ArrayBufferView): string {
+  let bytes: Uint8Array;
+  if (buffer instanceof Uint8Array) {
+    bytes = buffer;
+  } else if (buffer instanceof ArrayBuffer) {
+    bytes = new Uint8Array(buffer);
+  } else {
+    bytes = new Uint8Array((buffer as ArrayBufferView).buffer, (buffer as ArrayBufferView).byteOffset, (buffer as ArrayBufferView).byteLength);
+  }
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}