npm - @zaptcha/widget - Versions diffs - 1.0.0 - Mend

@zaptcha/widget 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,496 @@
+# Zero-Captcha
+[![npm version](https://img.shields.io/npm/v/@your-org/zero-captcha.svg)](https://www.npmjs.com/package/@your-org/zero-captcha)
+[![deno land](https://img.shields.io/badge/available%20on-deno.land-lightgrey)](https://deno.land/x/zero_captcha)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+A zero-knowledge CAPTCHA Web Component with WASM-based proof-of-work verification. Secure, accessible, and framework-agnostic.
+## Features
+✨ **Zero-Knowledge Proof** - Server doesn't learn anything about solver
+🔐 **WASM Proof-of-Work** - Client-side computational verification
+🎨 **Fully Themeable** - CSS custom properties for complete styling control
+♿ **Accessible** - ARIA attributes, keyboard navigation, semantic HTML
+📦 **Framework Agnostic** - Works with React, Vue, Angular, Svelte, plain JS
+⚡ **Lightweight** - ~8KB gzipped (with WASM)
+🚀 **Deno & Node.js** - Published to both ecosystems
+## Installation
+### npm (Node.js)
+```bash
+npm install @your-org/zero-captcha
+```
+```bash
+yarn add @your-org/zero-captcha
+```
+```bash
+pnpm add @your-org/zero-captcha
+```
+### Deno
+```typescript
+import ZeroCaptcha from "https://deno.land/x/zero_captcha@1.0.0/src/index.ts";
+```
+### Browser (CDN)
+```html
+<script type="module">
+  import ZeroCaptcha from "https://cdn.jsdelivr.net/npm/@your-org/zero-captcha@1.0.0/dist/index.js";
+</script>
+```
+## Quick Start
+### Basic HTML
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    :root {
+      --zaptcha-accent: #4f46e5;
+      --zaptcha-success: #10b981;
+    }
+  </style>
+</head>
+<body>
+  <form id="myForm">
+    <input type="text" placeholder="Your name" required />
+    <zero-captcha
+      base-url="https://api.example.com"
+      config-id="AAAA"
+    ></zero-captcha>
+    <button type="submit">Submit</button>
+  </form>
+  <script type="module">
+    import ZeroCaptcha from '@your-org/zero-captcha';
+    const form = document.getElementById('myForm');
+    const captcha = form.querySelector('zero-captcha');
+    let token = null;
+    captcha.addEventListener('zaptcha-success', (e) => {
+      token = e.detail.token;
+      console.log('✓ CAPTCHA verified:', token);
+    });
+    captcha.addEventListener('zaptcha-fail', (e) => {
+      console.error('✗ CAPTCHA failed:', e.detail.reason);
+    });
+    form.addEventListener('submit', async (e) => {
+      e.preventDefault();
+      if (!token) {
+        alert('Please solve the CAPTCHA');
+        return;
+      }
+      // Send form with token to server
+      const formData = new FormData(form);
+      formData.append('captcha_token', token);
+      const response = await fetch('/api/submit', {
+        method: 'POST',
+        body: formData
+      });
+      if (response.ok) {
+        console.log('✓ Form submitted');
+        captcha.reset();
+      }
+    });
+  </script>
+</body>
+</html>
+```
+### React
+```jsx
+import { useEffect, useRef, useState } from 'react';
+import ZeroCaptcha from '@your-org/zero-captcha';
+export function CaptchaForm() {
+  const captchaRef = useRef(null);
+  const [token, setToken] = useState(null);
+  const [loading, setLoading] = useState(false);
+  useEffect(() => {
+    const el = captchaRef.current;
+    if (!el) return;
+    const handleSuccess = (e) => setToken(e.detail.token);
+    const handleFail = (e) => console.error(e.detail.reason);
+    el.addEventListener('zaptcha-success', handleSuccess);
+    el.addEventListener('zaptcha-fail', handleFail);
+    return () => {
+      el.removeEventListener('zaptcha-success', handleSuccess);
+      el.removeEventListener('zaptcha-fail', handleFail);
+    };
+  }, []);
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    if (!token) return alert('Solve CAPTCHA first');
+    setLoading(true);
+    const res = await fetch('/api/submit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token })
+    });
+    setLoading(false);
+    if (res.ok) {
+      captchaRef.current?.reset();
+      setToken(null);
+    }
+  };
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="email" placeholder="Email" required />
+      <zero-captcha
+        ref={captchaRef}
+        base-url="https://api.example.com"
+        config-id="AAAA"
+      />
+      <button type="submit" disabled={!token || loading}>
+        {loading ? 'Submitting...' : 'Submit'}
+      </button>
+    </form>
+  );
+}
+```
+### Vue 3
+```vue
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="email" type="email" placeholder="Email" required />
+    <zero-captcha
+      ref="captchaRef"
+      base-url="https://api.example.com"
+      config-id="AAAA"
+      @zaptcha-success="onSuccess"
+      @zaptcha-fail="onFail"
+    />
+    <button type="submit" :disabled="!token || loading">
+      {{ loading ? 'Submitting...' : 'Submit' }}
+    </button>
+  </form>
+</template>
+<script setup>
+import { ref } from 'vue';
+import ZeroCaptcha from '@your-org/zero-captcha';
+const captchaRef = ref(null);
+const email = ref('');
+const token = ref(null);
+const loading = ref(false);
+const onSuccess = (e) => {
+  token.value = e.detail.token;
+};
+const onFail = (e) => {
+  console.error(e.detail.reason);
+};
+const handleSubmit = async () => {
+  if (!token.value) return;
+  loading.value = true;
+  const res = await fetch('/api/submit', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email: email.value, token: token.value })
+  });
+  loading.value = false;
+  if (res.ok) {
+    captchaRef.value?.reset();
+    token.value = null;
+  }
+};
+</script>
+```
+### Angular
+```typescript
+import { Component, ViewChild, ElementRef } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import ZeroCaptcha from '@your-org/zero-captcha';
+@Component({
+  selector: 'app-captcha-form',
+  template: `
+    <form (ngSubmit)="onSubmit()">
+      <input
+        [(ngModel)]="email"
+        name="email"
+        type="email"
+        placeholder="Email"
+        required
+      />
+      <zero-captcha
+        #captchaEl
+        base-url="https://api.example.com"
+        config-id="AAAA"
+        (zaptcha-success)="onSuccess($event)"
+        (zaptcha-fail)="onFail($event)"
+      />
+      <button
+        type="submit"
+        [disabled]="!token || loading"
+      >
+        {{ loading ? 'Submitting...' : 'Submit' }}
+      </button>
+    </form>
+  `,
+  standalone: true,
+  imports: [FormsModule]
+})
+export class CaptchaFormComponent {
+  @ViewChild('captchaEl') captchaEl!: ElementRef<any>;
+  email = '';
+  token: string | null = null;
+  loading = false;
+  onSuccess(event: CustomEvent<{ token: string }>) {
+    this.token = event.detail.token;
+  }
+  onFail(event: CustomEvent<{ reason: string }>) {
+    console.error(event.detail.reason);
+  }
+  async onSubmit() {
+    if (!this.token) return;
+    this.loading = true;
+    const res = await fetch('/api/submit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: this.email, token: this.token })
+    });
+    this.loading = false;
+    if (res.ok) {
+      this.captchaEl.nativeElement.reset();
+      this.token = null;
+    }
+  }
+}
+```
+### Deno Fresh
+```typescript
+// routes/form.tsx
+import { h, Fragment } from "preact";
+import { useState, useRef } from "preact/hooks";
+export default function FormPage() {
+  const [token, setToken] = useState<string | null>(null);
+  const captchaRef = useRef<any>(null);
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      if (!token) alert('Solve CAPTCHA');
+    }}>
+      <input type="email" placeholder="Email" required />
+      <zero-captcha
+        ref={captchaRef}
+        base-url="https://api.example.com"
+        config-id="AAAA"
+        onzaptcha-success={(e: any) => setToken(e.detail.token)}
+      />
+      <button type="submit" disabled={!token}>Submit</button>
+    </form>
+  );
+}
+```
+## Styling
+Customize appearance with CSS custom properties:
+```css
+:root {
+  /* Light mode (defaults) */
+  --zaptcha-bg: #ffffff;
+  --zaptcha-border: #e5e7eb;
+  --zaptcha-border-hover: #d1d5db;
+  --zaptcha-border-focus: #4f46e5;
+  --zaptcha-text: #374151;
+  --zaptcha-text-muted: #9ca3af;
+  --zaptcha-accent: #4f46e5;
+  --zaptcha-success: #10b981;
+  --zaptcha-shadow: 0 2px 6px rgba(0,0,0,0.04);
+  --zaptcha-radius: 8px;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --zaptcha-bg: #1f2937;
+    --zaptcha-border: #374151;
+    --zaptcha-border-hover: #4b5563;
+    --zaptcha-border-focus: #818cf8;
+    --zaptcha-text: #f3f4f6;
+    --zaptcha-text-muted: #6b7280;
+    --zaptcha-accent: #818cf8;
+    --zaptcha-success: #34d399;
+    --zaptcha-shadow: 0 2px 6px rgba(0,0,0,0.3);
+  }
+}
+zero-captcha {
+  width: 100%;
+  max-width: 210px;
+}
+```
+## API Reference
+### Attributes
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `base-url` | string | ✓ | Backend API base URL |
+| `config-id` | string | ✓ | Base64url-encoded config ID |
+| `wasm-glue` | string | | Custom WASM glue module path |
+| `wasm-bin` | string | | Custom WASM binary path |
+### Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `zaptcha-success` | `{ token: string }` | CAPTCHA solved, token generated |
+| `zaptcha-fail` | `{ reason: string }` | Solve failed |
+| `zaptcha-reset` | `{}` | Widget reset to idle state |
+| `zaptcha-progress` | `{ index, nonce, total, pct }` | Solving progress update |
+### Methods
+```typescript
+element.reset(): void
+// Reset widget to idle state
+```
+## Backend Integration
+Your backend needs two endpoints:
+### GET /config-id/challenge
+Returns:
+```json
+{
+  "token": "eyJ...",
+  "challenge_count": 16,
+  "salt_length": 32,
+  "difficulty": 20
+}
+```
+### POST /config-id/redeem
+Request body:
+```json
+{
+  "token": "eyJ...",
+  "solutions": [12345, 67890, ...]
+}
+```
+Response:
+```json
+{
+  "message": "proof_token_xyz"
+}
+```
+See [backend implementation guide](./docs/backend.md) for details.
+## Browser Support
+| Browser | Version |
+|---------|---------|
+| Chrome | 76+ |
+| Firefox | 79+ |
+| Safari | 14.1+ |
+| Edge | 79+ |
+WebAssembly and ES2020 modules required.
+## Troubleshooting
+**WASM not loading?**
+- Check WASM paths in `wasm-glue` and `wasm-bin` attributes
+- Ensure WASM served with `Content-Type: application/wasm`
+**Events not firing?**
+- Use `addEventListener()` (not `on*` attributes for Custom Events)
+- Event names are `zaptcha-success`, not `zaptchaSuccess`
+**Styling not applying?**
+- CSS custom properties must be set on parent, not `:root`
+- Use `!important` if conflicting with existing styles
+## Performance
+- Challenge solving: 100-500ms (varies by difficulty)
+- WASM bundle: 2-3MB uncompressed, gzipped to ~400KB
+- Component size: ~8KB (with gzip)
+## Security
+- No cookies stored
+- No tracking pixels
+- No external requests (except to your API)
+- Proof-of-work verified on server
+- Token valid for single use only
+## License
+MIT © 2024 Your Organization
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+## Support
+- 📖 [Documentation](https://github.com/your-org/zero-captcha/wiki)
+- 🐛 [Issue Tracker](https://github.com/your-org/zero-captcha/issues)
+- 💬 [Discussions](https://github.com/your-org/zero-captcha/discussions)

package/package.json ADDED Viewed

@@ -0,0 +1,13 @@
+{
+  "name": "@zaptcha/widget",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./src/zaptcha-widget.js",
+  "types": "./src/zaptcha.d.ts",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/zaptcha-widget.js"
+  }
+}

package/src/zaptcha-widget.js ADDED Viewed

@@ -0,0 +1,485 @@
+/**
+ * <zero-captcha> — CAPTCHA Web Component with WASM Proof-of-Work
+ *
+ * The worker is bundled inline — only this one file needs to be distributed.
+ * WASM paths are resolved automatically relative to this module's URL.
+ *
+ * Attributes:
+ * base-url="https://api.example.com"   required — backend base URL
+ * config-id="AAAA"                     required — base64url-encoded u32
+ * wasm-glue="./pkg/zaptcha.js"         optional — override WASM glue path
+ * wasm-bin="./pkg/zaptcha_bg.wasm"     optional — override WASM binary path
+ *
+ * CSS custom properties (set on a parent element to theme the widget):
+ * --zaptcha-bg           background color
+ * --zaptcha-border       border color
+ * --zaptcha-border-focus focus ring color
+ * --zaptcha-text         primary text color
+ * --zaptcha-text-muted   muted / branding text color
+ * --zaptcha-accent       spinner / interactive accent color
+ * --zaptcha-success      checkmark fill color
+ * --zaptcha-shadow       box shadow
+ * --zaptcha-radius       border radius
+ *
+ * Events dispatched on host element:
+ * zaptcha-success  -> detail: { token: string }
+ * zaptcha-fail     -> detail: { reason: string }
+ * zaptcha-reset    -> detail: {}
+ *
+ * Public methods:
+ * el.reset()
+ *
+ * Usage:
+ * <zero-captcha base-url="https://api.example.com" config-id="AAAA"></zero-captcha>
+ */
+// ── Default WASM paths (relative to this module) ──────────────────────────
+const _wasmGlue = new URL('./zaptcha.js',      import.meta.url).href;
+const _wasmBin  = new URL('./zaptcha_bg.wasm', import.meta.url).href;
+const WORKER_SRC = `
+let wasmModule  = null;
+let wasmReady   = false;
+let wasmGlueUrl = null;
+let wasmBinUrl  = null;
+async function initWasm() {
+  if (wasmReady) return;
+  if (!wasmGlueUrl) throw new Error("WASM paths not provided");
+  const mod = await import(wasmGlueUrl);
+  if (typeof mod.default === "function") await mod.default(wasmBinUrl);
+  wasmModule = mod;
+  wasmReady  = true;
+}
+async function runSolve(baseUrl, configId) {
+  await initWasm();
+  const challengeRes = await fetch(baseUrl + "/" + configId + "/challenge");
+  if (!challengeRes.ok) throw new Error("Challenge request failed: HTTP " + challengeRes.status);
+  const { token, challenge_count, salt_length, difficulty } = await challengeRes.json();
+  self.__zaptchaProgressCb = (index, nonce) => {
+    self.postMessage({ type: "progress", index, nonce, total: challenge_count });
+  };
+  let solutions;
+  try {
+    solutions = wasmModule.solve_challenge(
+      token, difficulty, challenge_count, salt_length, self.__zaptchaProgressCb,
+    );
+  } finally {
+    delete self.__zaptchaProgressCb;
+  }
+  const redeemRes = await fetch(baseUrl + "/" + configId + "/redeem", {
+    method:  "POST",
+    headers: { "Content-Type": "application/json" },
+    body:    JSON.stringify({ token, solutions: Array.from(solutions) }),
+  });
+  if (!redeemRes.ok) throw new Error("Redeem request failed: HTTP " + redeemRes.status);
+  const { message } = await redeemRes.json();
+  if (!message) throw new Error("Server did not return a token");
+  return message;
+}
+self.onmessage = async function ({ data }) {
+  if (data.type === "init") {
+    wasmGlueUrl = data.wasmGlue;
+    wasmBinUrl  = data.wasmBin;
+    try {
+      await initWasm();
+      self.postMessage({ type: "ready" });
+    } catch (err) {
+      self.postMessage({ type: "fail", reason: err.message });
+    }
+    return;
+  }
+  if (data.type === "solve") {
+    try {
+      const token = await runSolve(data.baseUrl, data.configId);
+      self.postMessage({ type: "success", token });
+    } catch (err) {
+      self.postMessage({ type: "fail", reason: err.message });
+    }
+    return;
+  }
+};
+`;
+const STYLE = `
+  :host {
+    display: inline-block;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    /*
+     * Map public --zaptcha-* custom properties to internal vars with
+     * sensible light-mode fallbacks.
+     */
+    --zap-bg:           var(--zaptcha-bg,           #ffffff);
+    --zap-border:       var(--zaptcha-border,       #e5e7eb);
+    --zap-border-hover: var(--zaptcha-border-hover, #d1d5db);
+    --zap-border-focus: var(--zaptcha-border-focus, #4f46e5);
+    --zap-text:         var(--zaptcha-text,         #374151);
+    --zap-text-muted:   var(--zaptcha-text-muted,   #9ca3af);
+    --zap-accent:       var(--zaptcha-accent,       #4f46e5);
+    --zap-success:      var(--zaptcha-success,      #10b981);
+    --zap-shadow:       var(--zaptcha-shadow,       0 2px 6px rgba(0,0,0,0.04));
+    --zap-radius:       var(--zaptcha-radius,       8px);
+  }
+  .widget {
+    background:    var(--zap-bg);
+    border:        1px solid var(--zap-border);
+    border-radius: var(--zap-radius);
+    box-shadow:    var(--zap-shadow);
+    width:         210px; /* Слегка шире для баланса, но все еще очень компактно */
+    box-sizing:    border-box;
+    transition:    box-shadow 0.2s ease, border-color 0.2s ease;
+  }
+  .widget:hover {
+    box-shadow: 0 4px 12px rgba(0,0,0,0.06);
+  }
+  .row {
+    display:       flex;
+    align-items:   center;
+    gap:           10px;
+    padding:       0 12px;
+    height:        48px;
+    cursor:        pointer;
+    user-select:   none;
+    box-sizing:    border-box;
+    border-radius: var(--zap-radius);
+    outline:       none;
+  }
+  .row:focus-visible {
+    box-shadow: 0 0 0 2px var(--zap-bg), 0 0 0 4px var(--zap-border-focus);
+  }
+  .row[aria-checked="true"] {
+    cursor: default;
+  }
+  /* Checkbox */
+  .box {
+    width:           22px;
+    height:          22px;
+    flex-shrink:     0;
+    position:        relative;
+    display:         flex;
+    align-items:     center;
+    justify-content: center;
+  }
+  .box-border {
+    position:      absolute;
+    inset:         0;
+    border:        1.5px solid var(--zap-border);
+    border-radius: 4px;
+    background:    var(--zap-bg);
+    transition:    border-color 0.2s ease, background-color 0.2s ease;
+  }
+  .row:hover:not([aria-checked="true"]) .box-border {
+    border-color: var(--zap-border-hover);
+  }
+  .box.done .box-border {
+    background:   var(--zap-success);
+    border-color: var(--zap-success);
+  }
+  .box-tick            { display: none; position: relative; z-index: 1; }
+  .box.done .box-tick  { display: block; animation: zap-pop 0.3s cubic-bezier(0.175, 0.885, 0.32, 1.275); }
+  @keyframes zap-pop {
+    0%   { transform: scale(0.5); opacity: 0; }
+    100% { transform: scale(1); opacity: 1; }
+  }
+  /* Spinner */
+  .box-spinner { display: none; position: absolute; inset: 0; }
+  .box.spinning .box-border  { border-color: transparent; background: transparent; }
+  .box.spinning .box-spinner {
+    display:         flex;
+    align-items:     center;
+    justify-content: center;
+  }
+  .box-spinner::after {
+    content:          '';
+    display:          block;
+    width:            18px;
+    height:           18px;
+    border:           2px solid var(--zap-border);
+    border-top-color: var(--zap-accent);
+    border-radius:    50%;
+    animation:        zap-spin 0.6s linear infinite;
+  }
+  @keyframes zap-spin { to { transform: rotate(360deg); } }
+  /* Label */
+  .label {
+    color:         var(--zap-text);
+    font-size:     13.5px;
+    font-weight:   500;
+    flex:          1;
+    white-space:   nowrap;
+    overflow:      hidden;
+    text-overflow: ellipsis;
+  }
+  /* Branding */
+  .branding {
+    display:         flex;
+    flex-direction:  column;
+    align-items:     flex-end;
+    justify-content: center;
+    flex-shrink:     0;
+    gap:             1px;
+  }
+  .branding strong {
+    font-size:      9px;
+    font-weight:    700;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    color:          var(--zap-text-muted);
+  }
+  .branding a {
+    font-size:       9px;
+    color:           var(--zap-text-muted);
+    text-decoration: none;
+    transition:      color 0.2s;
+  }
+  .branding a:hover {
+    color: var(--zap-text);
+  }
+`;
+class ZeroCaptcha extends HTMLElement {
+  static get observedAttributes() { return []; }
+  constructor() {
+    super();
+    this._shadow   = this.attachShadow({ mode: "open" });
+    this._worker   = null;
+    this._blobUrl  = null;
+    /** @type {"idle"|"solving"|"done"|"error"} */
+    this._state    = "idle";
+    this._progress = { done: 0, total: 1 };
+    this._render();
+  }
+  connectedCallback() {
+    this._bindEvents();
+    this._startWorker();
+  }
+  disconnectedCallback() {
+    this._destroyWorker();
+  }
+  reset() {
+    this._destroyWorker();
+    this._state    = "idle";
+    this._progress = { done: 0, total: 1 };
+    this._render();
+    this._bindEvents();
+    this._startWorker();
+    this.dispatchEvent(new CustomEvent("zaptcha-reset", { bubbles: true, detail: {} }));
+  }
+  _startWorker() {
+    try {
+      const externalUrl = this.getAttribute("worker-url");
+      if (externalUrl) {
+        this._worker = new Worker(externalUrl, { type: "module" });
+      } else {
+        const blob    = new Blob([WORKER_SRC], { type: "text/javascript" });
+        this._blobUrl = URL.createObjectURL(blob);
+        this._worker  = new Worker(this._blobUrl, { type: "module" });
+      }
+      this._worker.onmessage = (e) => this._onWorkerMsg(e.data);
+      this._worker.onerror   = (e) => this._onFail(`Worker error: ${e.message}`);
+      const wasmGlue = this.getAttribute("wasm-glue") ?? _wasmGlue;
+      const wasmBin  = this.getAttribute("wasm-bin")  ?? _wasmBin;
+      this._worker.postMessage({ type: "init", wasmGlue, wasmBin });
+    } catch (err) {
+      this._worker = null;
+    }
+  }
+  _destroyWorker() {
+    this._worker?.terminate();
+    this._worker = null;
+    if (this._blobUrl) {
+      URL.revokeObjectURL(this._blobUrl);
+      this._blobUrl = null;
+    }
+  }
+  _onWorkerMsg(msg) {
+    switch (msg.type) {
+      case "ready":
+        break;
+      case "progress":
+        this._progress.done  = (msg.index ?? 0) + 1;
+        this._progress.total = msg.total ?? 1;
+        this.dispatchEvent(new CustomEvent("zaptcha-progress", {
+          bubbles:  true,
+          composed: true,
+          detail: {
+            index: msg.index,
+            nonce: msg.nonce,
+            total: msg.total,
+            pct:   Math.round(((msg.index ?? 0) + 1) / (msg.total ?? 1) * 100),
+          },
+        }));
+        break;
+      case "success":
+        this._state = "done";
+        this._render();
+        this.dispatchEvent(new CustomEvent("zaptcha-success", {
+          bubbles:  true,
+          composed: true,
+          detail:   { token: msg.token },
+        }));
+        break;
+      case "fail":
+        this._onFail(msg.reason || "Unknown error");
+        break;
+    }
+  }
+  _render() {
+    const solving = this._state === "solving";
+    const done    = this._state === "done";
+    const label = done    ? "Verified"        :
+                  solving ? "Verifying\u2026"  :
+                            "I'm not a robot";
+    this._shadow.innerHTML = `
+      <style>${STYLE}</style>
+      <div class="widget" part="widget">
+        <div class="row"
+             id="row"
+             tabindex="${done ? -1 : 0}"
+             role="checkbox"
+             aria-checked="${done}"
+             aria-label="${label}">
+          <div class="box ${solving ? "spinning" : done ? "done" : ""}" id="box" part="checkbox">
+            <div class="box-border"></div>
+            <div class="box-spinner"></div>
+            <svg class="box-tick" width="12" height="9" viewBox="0 0 12 9" fill="none" aria-hidden="true">
+              <polyline points="1.5,4.5 4.5,7.5 10.5,1.5"
+                        stroke="white" stroke-width="2"
+                        stroke-linecap="round" stroke-linejoin="round"/>
+            </svg>
+          </div>
+          <span class="label" part="label">${label}</span>
+          <div class="branding" part="branding">
+            <strong>Zaptcha</strong>
+            <a href="#" tabindex="-1">Privacy</a>
+          </div>
+        </div>
+      </div>
+    `;
+  }
+  // ── Event binding ───────────────────────────────────────────────────────
+  _bindEvents() {
+    const row = this._shadow.getElementById("row");
+    if (!row) return;
+    row.addEventListener("click",   () => this._onRowClick());
+    row.addEventListener("keydown", (e) => {
+      if (e.key === " " || e.key === "Enter") {
+        e.preventDefault();
+        this._onRowClick();
+      }
+    });
+  }
+  _onRowClick() {
+    if (this._state !== "idle") return;
+    this._startSolve();
+  }
+  // ── Solving flow ────────────────────────────────────────────────────────
+  _startSolve() {
+    this._state    = "solving";
+    this._progress = { done: 0, total: 1 };
+    this._render();
+    if (!this._worker) {
+      this._onFail("Worker unavailable");
+      return;
+    }
+    const baseUrl  = this.getAttribute("base-url")  ?? "";
+    const configId = this.getAttribute("config-id") ?? "";
+    if (!baseUrl || !configId) {
+      this._onFail("Attributes base-url and config-id are required");
+      return;
+    }
+    this._worker.postMessage({ type: "solve", baseUrl, configId });
+  }
+  _onFail(reason) {
+    this._state = "error";
+    this._render();
+    this.dispatchEvent(new CustomEvent("zaptcha-fail", {
+      bubbles:  true,
+      composed: true,
+      detail:   { reason },
+    }));
+    setTimeout(() => this.reset(), 3000);
+  }
+}
+customElements.define("zero-captcha", ZeroCaptcha);
+export default ZeroCaptcha;
+export { ZeroCaptcha };
+// ── Standalone worker factory ─────────────────────────────────────────────
+export function createWorker({ wasmGlue = _wasmGlue, wasmBin = _wasmBin } = {}) {
+  const blob    = new Blob([WORKER_SRC], { type: "text/javascript" });
+  const blobUrl = URL.createObjectURL(blob);
+  const worker  = new Worker(blobUrl, { type: "module" });
+  worker.addEventListener("message", function onReady(e) {
+    if (e.data?.type === "ready" || e.data?.type === "fail") {
+      URL.revokeObjectURL(blobUrl);
+      worker.removeEventListener("message", onReady);
+    }
+  });
+  worker.postMessage({ type: "init", wasmGlue, wasmBin });
+  return worker;
+}

package/src/zaptcha.d.ts ADDED Viewed

@@ -0,0 +1,145 @@
+/**
+ * zaptcha.d.ts — TypeScript type declarations for <zero-captcha>
+ *
+ * Usage (module):
+ *   import type { ZeroCaptcha, ZaptchaSuccessEvent, ZaptchaFailEvent } from "./zaptcha";
+ *
+ * Usage (global augmentation, add to your project's *.d.ts):
+ *   /// <reference types="./zaptcha" />
+ */
+// ── Event payload types ───────────────────────────────────────────────────
+/** Fired when PoW solving succeeds and the server returns a signed token. */
+export interface ZaptchaSuccessDetail {
+  /** Signed token returned by the backend after successful PoW redemption. */
+  token: string;
+}
+/** Fired when solving or network communication fails. */
+export interface ZaptchaFailDetail {
+  /** Human-readable error description. */
+  reason: string;
+}
+/** Fired on each solved PoW challenge. */
+export interface ZaptchaProgressDetail {
+  index: number;
+  nonce: number;
+  total: number;
+  /** 0–100 */
+  pct: number;
+}
+/** Fired when the widget is reset to its idle state. */
+export type ZaptchaResetDetail = Record<string, never>;
+export type ZaptchaSuccessEvent  = CustomEvent<ZaptchaSuccessDetail>;
+export type ZaptchaFailEvent     = CustomEvent<ZaptchaFailDetail>;
+export type ZaptchaProgressEvent = CustomEvent<ZaptchaProgressDetail>;
+export type ZaptchaResetEvent    = CustomEvent<ZaptchaResetDetail>;
+// ── Element class ─────────────────────────────────────────────────────────
+export declare class ZeroCaptcha extends HTMLElement {
+  /**
+   * Backend base URL.
+   * Maps to the `base-url` attribute.
+   */
+  baseUrl: string;
+  /**
+   * Base64url-encoded config identifier (u32).
+   * Maps to the `config-id` attribute.
+   */
+  configId: string;
+  /**
+   * Color theme.
+   * Maps to the `theme` attribute.
+   * @default "light"
+   */
+  theme: "light" | "dark";
+  /**
+   * URL of the Web Worker script.
+   * Maps to the `worker-url` attribute.
+   * @default "./zaptcha-worker.js"
+   */
+  workerUrl: string;
+  /**
+   * Reset the widget to idle state, terminate any in-progress solving,
+   * and fire a `zaptcha-reset` event.
+   */
+  reset(): void;
+  // ── Standard HTMLElement event overloads ────────────────────────────────
+  addEventListener(
+    type: "zaptcha-progress",
+    listener: (ev: ZaptchaProgressEvent) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: "zaptcha-success",
+    listener: (ev: ZaptchaSuccessEvent) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: "zaptcha-fail",
+    listener: (ev: ZaptchaFailEvent) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: "zaptcha-reset",
+    listener: (ev: ZaptchaResetEvent) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}
+// ── Global HTMLElementTagNameMap augmentation ─────────────────────────────
+// Enables typed querySelector / createElement in TypeScript projects.
+declare global {
+  interface HTMLElementTagNameMap {
+    "zero-captcha": ZeroCaptcha;
+  }
+  interface HTMLElementEventMap {
+    "zaptcha-progress": ZaptchaProgressEvent;
+    "zaptcha-success":  ZaptchaSuccessEvent;
+    "zaptcha-fail":     ZaptchaFailEvent;
+    "zaptcha-reset":    ZaptchaResetEvent;
+  }
+}
+export default ZeroCaptcha;
+// ── Standalone worker factory ─────────────────────────────────────────────
+export interface CreateWorkerOptions {
+  /** Absolute URL to the WASM JS glue file. Defaults to the bundled path. */
+  wasmGlue?: string;
+  /** Absolute URL to the WASM binary. Defaults to the bundled path. */
+  wasmBin?: string;
+}
+/**
+ * Create a standalone Zaptcha worker without the widget UI.
+ * The worker is pre-warmed and ready to receive `"solve"` messages.
+ *
+ * @example
+ * const worker = createWorker();
+ * worker.onmessage = ({ data }) => {
+ *   if (data.type === 'success') console.log(data.token);
+ * };
+ * worker.postMessage({ type: 'solve', baseUrl: 'https://api.example.com', configId: 'AAAA' });
+ * worker.terminate();
+ */
+export function createWorker(options?: CreateWorkerOptions): Worker;

package/src/zaptcha.js ADDED Viewed

@@ -0,0 +1,249 @@
+/* @ts-self-types="./zaptcha.d.ts" */
+/**
+ * @param {string} token
+ * @param {number} difficulty
+ * @param {number} challenge_count
+ * @param {number} salt_length
+ * @param {Function} progress_callback
+ * @returns {Uint32Array}
+ */
+export function solve_challenge(token, difficulty, challenge_count, salt_length, progress_callback) {
+    const ptr0 = passStringToWasm0(token, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.solve_challenge(ptr0, len0, difficulty, challenge_count, salt_length, progress_callback);
+    var v2 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v2;
+}
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_throw_6ddd609b62940d55: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_call_dcc2662fa17a72cf: function() { return handleError(function (arg0, arg1, arg2, arg3) {
+            const ret = arg0.call(arg1, arg2, arg3);
+            return ret;
+        }, arguments); },
+        __wbindgen_cast_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./zaptcha_bg.js": import0,
+    };
+}
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+function getArrayU32FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
+}
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+let cachedUint32ArrayMemory0 = null;
+function getUint32ArrayMemory0() {
+    if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) {
+        cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer);
+    }
+    return cachedUint32ArrayMemory0;
+}
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+    const mem = getUint8ArrayMemory0();
+    let offset = 0;
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+const cachedTextEncoder = new TextEncoder();
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+let WASM_VECTOR_LEN = 0;
+let wasmModule, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedUint32ArrayMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    wasm.__wbindgen_start();
+    return wasm;
+}
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = module.ok && expectedResponseType(module.type);
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+                } else { throw e; }
+            }
+        }
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+    if (module_or_path === undefined) {
+        module_or_path = new URL('zaptcha_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+    return __wbg_finalize_init(instance, module);
+}
+export { initSync, __wbg_init as default };

package/src/zaptcha_bg.wasm ADDED Viewed

Binary file