ribaunt 0.2.2 → 0.2.4

package/README.md

@@ -16,10 +16,19 @@ Ribaunt is a stateless proof-of-work CAPTCHA library for Node.js and modern brow
 - Browser widget for plain HTML apps
 - React and Next.js-friendly wrapper via `ribaunt/widget-react`
 - Server helpers for creating, solving, and verifying PoW challenges
+- Programmable risk engine (`assess()`) with caller-supplied signals, pluggable scorers, and `allow`/`challenge`/`block` policy
 - Default process-local replay protection with support for remote replay stores
 - CSS custom properties for theming
 - TypeScript types included
 
+## What Ribaunt does not do
+
+Read this before relying on Ribaunt alone.
+
+- **Ribaunt does not rate-limit your endpoints.** Nothing stops an attacker from hammering your challenge or verify endpoints themselves, no solving required. Put a rate limiter (per-IP, per-account, or WAF-level) in front of both. Ribaunt exposes optional rate-limit and telemetry hooks so you can wire your own limiter and metrics in at the point challenges are issued and verified (see `rateLimiter` and `onEvent` below).
+- **Ribaunt does not prove a human is present.** It raises the cost of automated abuse. A sufficiently resourced attacker can solve any proof-of-work challenge.
+- **Ribaunt is one layer, not the whole stack.** Use it behind rate limiting and risk signals, and never as the sole gate for sensitive actions such as password reset, account recovery, or payments.
+
 ## Install
 
 ```bash
@@ -56,8 +65,8 @@ const app = express();
 
 app.use(express.json());
 
-app.get('/api/captcha/challenge', (_req, res) => {
-  const challenges = createChallenge(5, 4, 120);
+app.get('/api/captcha/challenge', async (_req, res) => {
+  const challenges = await createChallenge(5, 4, 120);
   res.json({ challenges });
 });
 
@@ -129,10 +138,10 @@ For Next.js App Router, keep the widget in a client component. Do not expose `RI
 
 ### `createChallenge(difficulty, amount, ttlSeconds)`
 
-Creates signed challenge tokens.
+Creates signed challenge tokens. Since the optional `rateLimiter` hook can be async, `createChallenge()` returns a `Promise`:
 
 ```ts
-const challenges = createChallenge(5, 4, 120);
+const challenges = await createChallenge(5, 4, 120);
 ```
 
 | Parameter | Default | Description |
@@ -143,12 +152,14 @@ const challenges = createChallenge(5, 4, 120);
 
 Validate user- or config-controlled values before passing them to `createChallenge()`. Invalid values throw.
 
+> **API note:** the options object form defaults to a single challenge (`amount: 1`) unless you pass `amount`; only the positional form above defaults to `4`.
+
 ### `createChallenge({ difficulty: "auto", ... })`
 
 Creates adaptive challenge tokens from a server-bounded calibration hint. Calibration is untrusted and raise-only: it can increase work for fast clients, but it never lowers the server baseline.
 
 ```ts
-const challenges = createChallenge({
+const challenges = await createChallenge({
   difficulty: 'auto',
   calibration: requestBody.calibration,
   targetDurationMs: 750,
@@ -196,9 +207,41 @@ const workload = selectWorkload({
   minDifficulty: 3,
   maxDifficulty: 6,
 });
-// { difficulty: 5, amount: 4, estimatedAttempts: 1256 }
+ // { difficulty: 3, amount: 5, estimatedAttempts: 20480 }
+```
+
+### `assess(options)` — Risk Engine
+
+ Stateless, caller-driven risk assessment. All signals are caller-supplied (untrusted). Returns a bounded heuristic risk score (0–100, not a probability) and a policy action.
+
+```ts
+import { assess } from 'ribaunt';
+
+const assessment = await assess({
+  signals: {
+    accountAgeSeconds: account.ageSeconds,
+    requestVelocity: requestsPerMinute,
+    userAgent: req.headers['user-agent'],
+    ip: req.ip, // accepted for custom scorers; default scorer ignores it
+  },
+  // thresholds: { challenge: 40, block: 80 }, // defaults shown
+  // scorer: myScorer, // optional pluggable RiskScorer
+  // workload: { minDifficulty: 3, maxDifficulty: 6, targetDurationMs: 750, calibration },
+});
+
+if (assessment.action === 'allow') { /* continue */ }
+else if (assessment.action === 'challenge') {
+  const workload = assessment.workload!; // { difficulty, amount, estimatedAttempts } from selectWorkload()
+}
+else { /* block — application decides how to reject */ }
 ```
 
+- `risk < challenge` → `allow` (no workload)
+- `challenge ≤ risk < block` → `challenge` (with workload via existing `selectWorkload()`)
+- `risk ≥ block` → `block` (no workload)
+
+Defaults are `DEFAULT_RISK_THRESHOLDS = { challenge: 40, block: 80 }` — tune to your app; they are policy defaults, not fraud probabilities. Custom scorers (`RiskScorer { score(signals): Promise<number> }`) are `async` so you can call a remote model; invalid outputs (`NaN`/`Infinity`/`<0`/`>100`/non-number) are rejected, not clamped, and thrown errors propagate. See `docs/risk-engine.md` for the full default-scorer buckets, trust model, and limitations.
+
 ### `verifySolution(tokens, solutions, options?)`
 
 Verifies submitted solutions and returns a structured result:
@@ -226,6 +269,59 @@ const result = await verifySolution(tokens, solutions, {
 });
 ```
 
+### `rateLimiter` hook
+
+Ribaunt does not rate-limit anything itself — bring your own limiter. Both `createChallenge()` and `verifySolution()` accept an optional `rateLimiter: { check(key?) => Promise<boolean> }` that runs before the operation. If it returns `false`, issuance or verification is blocked with a `RateLimitedError` (`code = 'rate-limited'`) so you can catch it specifically. Errors thrown by your limiter propagate unchanged.
+
+```ts
+import { RateLimitedError } from 'ribaunt';
+
+const rateLimiter = {
+  check: async (key?: string) => (await redisBucket.hit(key ?? 'unknown')) < 10,
+};
+
+// Challenge endpoint: key the limiter on the client IP by closing over the
+// request instead of passing `context`. Passing `context: req.ip` here would
+// also cryptographically bind each challenge to that IP, forcing the verify
+// call to pass the exact same `context` (see `verifySolution` below).
+app.get('/api/captcha/challenge', async (req, res) => {
+  try {
+    const challenges = await createChallenge({
+      difficulty: 5,
+      amount: 4,
+      rateLimiter,
+    });
+    res.json({ challenges });
+  } catch (error) {
+    if (error instanceof RateLimitedError) {
+      return res.status(429).json({ error: 'Too many challenge requests' });
+    }
+    throw error;
+  }
+});
+```
+
+> **Context binding:** if you *do* pass `context` to `createChallenge()`, every challenge token is bound to that context via an HMAC digest. You must then pass the identical `context` to `verifySolution()` or verification fails with `context-mismatch`. Use `context` for binding a challenge to a specific action (e.g. one signup attempt), not for rate limiting.
+
+### `onEvent` telemetry hook
+
+Both entry points accept an optional synchronous `onEvent` callback for structured lifecycle events. It is fire-and-forget: a throwing consumer can never break challenge issuance or verification.
+
+```ts
+const counts = { issued: 0, success: 0, failure: 0 };
+
+const onEvent = (event: RibauntEvent) => {
+  if (event.type === 'challenge-issued') counts.issued += 1;
+  else if (event.type === 'verify-success') counts.success += 1;
+  else if (event.type === 'verify-failure') counts.failure += 1;
+};
+
+await createChallenge({ difficulty: 5, amount: 4, onEvent });
+const result = await verifySolution(tokens, solutions, { onEvent });
+```
+
+`verify-failure` events carry the same `reason` values as `VerifySolutionResult` (`invalid-token`, `expired-token`, `invalid-solution`, `context-mismatch`, `replay-detected`, `replay-store-unavailable`, `configuration-error`). Add aggregation over Windows, StatsD, or Prometheus yourself — Ribaunt only emits raw events.
+
 ### `solveChallenge(token, options?)`
 
 Solves challenges synchronously. This is mainly useful for tests and debugging.
@@ -249,6 +345,8 @@ const solutions = solveChallenge(challenges, {
   show-warning="false"
   warning-message="Verification may take longer on this device."
   solve-timeout="15000"
+  worker-mode="preferred"
+  wasm-mode="preferred"
   disabled="false"
 ></ribaunt-widget>
 ```
@@ -262,7 +360,10 @@ const solutions = solveChallenge(challenges, {
 | `calibrate` | `calibrate` | Benchmarks the browser and sends `{ calibration }` with POST challenge requests. |
 | `show-warning` | `showWarning` | Shows a warning banner. |
 | `warning-message` | `warningMessage` | Custom warning text. |
-| `solve-timeout` | `solveTimeout` | Optional solve timeout in milliseconds. |
+| `show-progress` | `showProgress` | Set to `"false"` to swap the percentage ring for a plain bars spinner with a static `Loading...` label. |
+| `solve-timeout` | `solveTimeout` | Optional timeout in milliseconds for the whole verification attempt (fetching, solving, and verifying). |
+| `worker-mode` | `workerMode` | Web Worker solving: `preferred` (default; falls back to the main thread), `required` (fail if unavailable), or `disabled`. |
+| `wasm-mode` | `wasmMode` | WASM solver: `preferred` (default; uses WASM batch solver inside worker if available), `disabled` (always use JS solver inside worker). Independent from `worker-mode`. |
 | `disabled` | `disabled` | Blocks user interaction and automatic verification. |
 | | `fallback` | React-only. Custom loading element while widget dynamic import loads. Defaults to a built-in shimmer skeleton. |
 
@@ -295,6 +396,7 @@ See [theming docs](https://github.com/ribaunt/ribaunt/blob/main/docs/theming.md)
 
 - [Quick start](https://github.com/ribaunt/ribaunt/blob/main/docs/quick-start.md)
 - [Configuration](https://github.com/ribaunt/ribaunt/blob/main/docs/configuration.md)
+- [Risk Engine](https://github.com/ribaunt/ribaunt/blob/main/docs/risk-engine.md)
 - [Events](https://github.com/ribaunt/ribaunt/blob/main/docs/events.md)
 - [HTML integration](https://github.com/ribaunt/ribaunt/blob/main/docs/integrations/html.md)
 - [React integration](https://github.com/ribaunt/ribaunt/blob/main/docs/integrations/react.md)
@@ -313,9 +415,10 @@ You can also ask documentation-aware tools to use the Context7 library ID:
 ## Development
 
 ```bash
-npm install
-npm test
-npm run build
+corepack enable
+pnpm install
+pnpm test
+pnpm run build
 ```
 
 ## License

package/demo/lib/solver-worker.js

@@ -0,0 +1,174 @@
+/// <reference lib="webworker" />
+import { solveChallenge, decodeChallengeToken } from './solver.js';
+import { ensureWasm, solveBatch, resetWasmHeap } from './wasm-solver.js';
+const workerScope = self;
+const activeControllers = new Map();
+// Cache WASM initialization per worker lifetime (wasm-solver already caches, but keep explicit)
+let wasmBackendState = 'uninitialized';
+const WASM_BATCH_SIZE = 1024;
+const yieldToEventLoop = (() => {
+    if (typeof MessageChannel !== 'function') {
+        return () => new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    let channel = null;
+    const waiting = new Set();
+    return () => {
+        if (!channel) {
+            channel = new MessageChannel();
+            channel.port1.onmessage = () => {
+                for (const resolve of waiting)
+                    resolve();
+                waiting.clear();
+            };
+            channel.port1.unref?.();
+        }
+        return new Promise((resolve) => {
+            waiting.add(resolve);
+            channel.port2.postMessage(null);
+        });
+    };
+})();
+async function solveSingleChallengeWasm(token, signal) {
+    const payload = decodeChallengeToken(token);
+    if (!payload)
+        return undefined;
+    const { challenge, difficulty } = payload;
+    let startNonce = 0;
+    try {
+        while (true) {
+            if (signal?.aborted) {
+                throw new DOMException('Challenge solving aborted', 'AbortError');
+            }
+            const result = solveBatch(challenge, startNonce, WASM_BATCH_SIZE, difficulty);
+            if (result.found && result.nonce && result.hash) {
+                // Validate before returning (wasm-solver already validated, but double-check)
+                if (typeof result.nonce !== 'string' || typeof result.hash !== 'string') {
+                    throw new Error('Invalid WASM result shape');
+                }
+                return { nonce: result.nonce, hash: result.hash };
+            }
+            startNonce += WASM_BATCH_SIZE;
+            // Overflow guard - do not wrap; allow final batch where last nonce is 0x7fffffff
+            if (startNonce > 0x7fffffff - WASM_BATCH_SIZE + 1) {
+                throw new Error('WASM solver nonce overflow');
+            }
+            // Yield every 2048 nonces to keep worker responsive (matches JS solver's 2048)
+            if (startNonce % 2048 === 0) {
+                await yieldToEventLoop();
+            }
+        }
+    }
+    finally {
+        // Reset heap to avoid leak between tokens/requests
+        try {
+            resetWasmHeap();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+async function solveChallengeWasm(tokens, onProgress, signal) {
+    const solutions = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (!token)
+            throw new Error(`Invalid token at index ${i}`);
+        if (signal?.aborted)
+            throw new DOMException('Challenge solving aborted', 'AbortError');
+        const solution = await solveSingleChallengeWasm(token, signal);
+        if (!solution)
+            throw new Error(`Failed to solve challenge ${i + 1}`);
+        solutions.push(solution);
+        if (onProgress) {
+            const progress = Math.round(((i + 1) / tokens.length) * 100);
+            onProgress(progress);
+        }
+    }
+    return solutions;
+}
+async function selectBackend(wasmMode) {
+    if (wasmMode === 'disabled')
+        return 'js';
+    // preferred (default)
+    if (wasmBackendState === 'wasm-unavailable')
+        return 'js';
+    if (wasmBackendState === 'wasm-ready')
+        return 'wasm';
+    // uninitialized -> try to init
+    try {
+        const ok = await ensureWasm();
+        wasmBackendState = ok ? 'wasm-ready' : 'wasm-unavailable';
+        return ok ? 'wasm' : 'js';
+    }
+    catch {
+        wasmBackendState = 'wasm-unavailable';
+        return 'js';
+    }
+}
+workerScope.addEventListener('message', (event) => {
+    const request = event.data;
+    if (!request)
+        return;
+    if (request.type === 'cancel') {
+        const controller = activeControllers.get(request.id);
+        if (controller) {
+            controller.abort();
+            activeControllers.delete(request.id);
+            workerScope.postMessage({ type: 'cancelled', id: request.id });
+            workerScope.close();
+        }
+        return;
+    }
+    if (request.type !== 'solve')
+        return;
+    const controller = new AbortController();
+    activeControllers.set(request.id, controller);
+    const wasmMode = request.wasmMode === 'disabled' ? 'disabled' : 'preferred';
+    (async () => {
+        const backend = await selectBackend(wasmMode);
+        // Telemetry: report backend selection once per request
+        if (!controller.signal.aborted) {
+            try {
+                workerScope.postMessage({ type: 'backend', id: request.id, backend });
+            }
+            catch {
+                // telemetry must never break solving
+            }
+        }
+        const solver = backend === 'wasm' ? solveChallengeWasm : solveChallenge;
+        // For wasm-unavailable fallback, re-select if wasm fails during solve? We already selected js
+        // But if backend is wasm and solve fails with internal error, we surface not fallback
+        return solver(request.tokens, (progress) => {
+            if (!controller.signal.aborted) {
+                workerScope.postMessage({
+                    type: 'progress',
+                    id: request.id,
+                    progress,
+                });
+            }
+        }, controller.signal);
+    })().then((solutions) => {
+        activeControllers.delete(request.id);
+        if (controller.signal.aborted)
+            return;
+        workerScope.postMessage({
+            type: 'result',
+            id: request.id,
+            solutions,
+        });
+    }, (error) => {
+        activeControllers.delete(request.id);
+        if (controller.signal.aborted)
+            return;
+        // If WASM was selected and failed due to unexpected runtime error, surface as error
+        // For expected initialization failures we already fell back to JS, so this error is genuine
+        workerScope.postMessage({
+            type: 'error',
+            id: request.id,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+});
+export {};
+//# sourceMappingURL=solver-worker.js.map

package/demo/lib/solver-worker.js.map

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

package/demo/lib/solver.js

@@ -0,0 +1,135 @@
+/**
+ * Browser-compatible challenge solver using Web Crypto API
+ */
+/**
+ * Decode JWT token (browser-compatible, without verification)
+ */
+function decodeJWT(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3 || !parts[1])
+            return null;
+        const normalizedPayload = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const paddedPayload = normalizedPayload.padEnd(normalizedPayload.length + ((4 - (normalizedPayload.length % 4)) % 4), '=');
+        const payload = JSON.parse(atob(paddedPayload));
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * SHA-256 hash using Web Crypto API
+ */
+async function sha256(message) {
+    if (typeof TextEncoder === 'undefined') {
+        throw new Error('TextEncoder is unavailable in this browser environment');
+    }
+    if (!globalThis.crypto?.subtle) {
+        throw new Error('Web Crypto API is unavailable. Use HTTPS or localhost.');
+    }
+    const msgBuffer = new TextEncoder().encode(message);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    return hashHex;
+}
+/**
+ * Yield to the event loop without the ~4ms clamping browsers apply to
+ * nested setTimeout calls. MessageChannel tasks run as macrotasks with
+ * microsecond-level latency, keeping the UI responsive at a fraction of
+ * the timer overhead.
+ *
+ * The channel is created lazily on first yield, and the receiving port is
+ * unref'd where supported (Node.js): a port with an active message listener
+ * otherwise keeps the host event loop alive and prevents clean exit.
+ */
+const yieldToEventLoop = (() => {
+    if (typeof MessageChannel !== 'function') {
+        return () => new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    let channel = null;
+    const waiting = new Set();
+    return () => {
+        if (!channel) {
+            channel = new MessageChannel();
+            channel.port1.onmessage = () => {
+                for (const resolve of waiting)
+                    resolve();
+                waiting.clear();
+            };
+            channel.port1.unref?.();
+        }
+        return new Promise((resolve) => {
+            waiting.add(resolve);
+            channel.port2.postMessage(null);
+        });
+    };
+})();
+export async function calibrateBrowser(iterations = 128) {
+    if (!Number.isFinite(iterations) || iterations < 1) {
+        throw new Error('Calibration iterations must be at least 1');
+    }
+    const normalizedIterations = Math.floor(iterations);
+    const startedAt = performance.now();
+    for (let index = 0; index < normalizedIterations; index++) {
+        await sha256(`ribaunt-calibration:${index}`);
+    }
+    return {
+        iterations: normalizedIterations,
+        durationMs: Math.max(1, Math.round(performance.now() - startedAt)),
+    };
+}
+export const calibrateClient = calibrateBrowser;
+export function decodeChallengeToken(token) {
+    return decodeJWT(token);
+}
+/**
+ * Solve a single challenge token (browser-compatible)
+ */
+export async function solveSingleChallenge(token, signal) {
+    const payload = decodeJWT(token);
+    if (!payload)
+        return undefined;
+    const { challenge, difficulty } = payload;
+    const prefix = '0'.repeat(difficulty);
+    let nonce = 0;
+    while (true) {
+        if (signal?.aborted) {
+            throw new DOMException('Challenge solving aborted', 'AbortError');
+        }
+        const hash = await sha256(`${challenge}${nonce}`);
+        if (hash.startsWith(prefix)) {
+            return { nonce: String(nonce), hash };
+        }
+        nonce++;
+        // Yield to keep the UI responsive; each batch amortizes the yield cost.
+        if (nonce % 2048 === 0) {
+            await yieldToEventLoop();
+        }
+    }
+}
+/**
+ * Solve multiple challenge tokens (browser-compatible)
+ */
+export async function solveChallenge(tokens, onProgress, signal) {
+    const solutions = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (!token) {
+            throw new Error(`Invalid token at index ${i}`);
+        }
+        const solution = await solveSingleChallenge(token, signal);
+        if (!solution) {
+            throw new Error(`Failed to solve challenge ${i + 1}`);
+        }
+        solutions.push(solution);
+        // Report progress
+        if (onProgress) {
+            const progress = Math.round(((i + 1) / tokens.length) * 100);
+            onProgress(progress);
+        }
+    }
+    return solutions;
+}
+//# sourceMappingURL=solver.js.map

package/demo/lib/solver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solver.js","sourceRoot":"","sources":["../src/solver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH;;GAEG;AACH,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAEjD,MAAM,iBAAiB,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzE,MAAM,aAAa,GAAG,iBAAiB,CAAC,MAAM,CAC5C,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EACrE,GAAG,CACJ,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;QAChD,OAAO,OAA2B,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,MAAM,CAAC,OAAe;IACnC,IAAI,OAAO,WAAW,KAAK,WAAW,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,gBAAgB,GAAwB,CAAC,GAAG,EAAE;IAClD,IAAI,OAAO,cAAc,KAAK,UAAU,EAAE,CAAC;QACzC,OAAO,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,IAAI,OAAO,GAA0B,IAAI,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;IAEtC,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,EAAE;gBAC7B,KAAK,MAAM,OAAO,IAAI,OAAO;oBAAE,OAAO,EAAE,CAAC;gBACzC,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC,CAAC;YACD,OAAO,CAAC,KAA8C,CAAC,KAAK,EAAE,EAAE,CAAC;QACpE,CAAC;QACD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACnC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrB,OAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC,CAAC,EAAE,CAAC;AAEL,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAAU,GAAG,GAAG;IACrD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,oBAAoB,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACpC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,oBAAoB,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,MAAM,CAAC,uBAAuB,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,UAAU,EAAE,oBAAoB;QAChC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;KACnE,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEhD,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAa,EACb,MAAoB;IAEpB,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC1C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAEtC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,YAAY,CAAC,2BAA2B,EAAE,YAAY,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,SAAS,GAAG,KAAK,EAAE,CAAC,CAAC;QAElD,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;QACxC,CAAC;QAED,KAAK,EAAE,CAAC;QAER,wEAAwE;QACxE,IAAI,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,gBAAgB,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAgB,EAChB,UAAuC,EACvC,MAAoB;IAEpB,MAAM,SAAS,GAAwB,EAAE,CAAC;IAE1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxD,CAAC;QAED,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEzB,kBAAkB;QAClB,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC;YAC7D,UAAU,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}