captchakraken 2.2.0 → 2.4.0

package/python/LICENSE

@@ -0,0 +1,105 @@
+CaptchaKraken Source-Available License v1.0
+Copyright (c) 2026 JobHarvest / JWriter20. All rights reserved.
+
+This license governs use of the CaptchaKraken software in this repository and of
+the associated machine-learning model weights and LoRA adapters published by the
+copyright holder (collectively, the "Software"). By using the Software you agree
+to these terms. If you do not agree, do not use the Software.
+
+================================================================================
+1. GRANT
+================================================================================
+Subject to the restrictions below, you are granted a worldwide, royalty-free,
+non-exclusive license to use, copy, modify, and distribute the Software, and to
+incorporate it into your own products and services.
+
+================================================================================
+2. PERMITTED USES
+================================================================================
+You MAY use the Software for:
+
+  (a) Personal, non-commercial use, research, and education.
+
+  (b) Commercial use INSIDE a larger product or service that delivers
+      substantial value BEYOND captcha solving itself — that is, where captcha
+      solving is an internal, enabling component rather than the product.
+
+  Illustrative (non-exhaustive) examples of PERMITTED commercial use:
+      - Web scrapers and data-collection pipelines.
+      - Stealth / anti-detection browsers and browser automation frameworks
+        that use the Software as one internal capability.
+      - QA, testing, and accessibility tooling.
+      - Any application where the captcha solve is a means to an end the user
+        is actually paying for.
+
+================================================================================
+3. PROHIBITED USES
+================================================================================
+You MAY NOT, without a separate written commercial agreement from the copyright
+holder:
+
+  (a) Sell, resell, rent, or otherwise offer for a fee any captcha-SOLVING
+      service, product, or API whose primary value is solving captchas,
+      where that service is powered by the Software or its model outputs.
+
+  (b) Distribute "thin wrappers" around the Software whose primary purpose is
+      captcha solving — including but not limited to browser extensions,
+      hosted endpoints, SaaS products, or CLIs that simply expose the
+      Software's solving capability to end users.
+
+  (c) Expose, proxy, or relay the responses or outputs of the Software's LoRA
+      models (e.g. bounding boxes, tile selections, click plans) through a paid
+      or public API as a captcha-solving service.
+
+  In short: you may BUILD WITH this Software, but you may not SELL THE SOLVE.
+
+================================================================================
+4. MODEL OUTPUTS
+================================================================================
+Outputs produced by the model weights/adapters are subject to Sections 2 and 3
+to the same extent as the Software itself. Reselling or API-relaying those
+outputs as a captcha-solving service is prohibited under Section 3(c).
+
+================================================================================
+5. REDISTRIBUTION
+================================================================================
+If you redistribute the Software (modified or not), you must retain this license
+and this notice, and you must not remove or alter the restrictions in Section 3.
+
+================================================================================
+6. TRADEMARKS
+================================================================================
+This license does not grant permission to use the trade names, trademarks, or
+product names of the copyright holder, except as required to describe the origin
+of the Software.
+
+================================================================================
+7. NO WARRANTY
+================================================================================
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+================================================================================
+8. RESPONSIBLE USE
+================================================================================
+You are responsible for ensuring your use of the Software complies with all
+applicable laws, the terms of service of any site you interact with, and
+applicable anti-fraud and computer-access statutes. The copyright holder does
+not endorse using the Software to violate any third party's terms or rights.
+
+================================================================================
+9. COMMERCIAL LICENSING
+================================================================================
+For uses prohibited under Section 3 — including selling captcha-solving as a
+service — contact the copyright holder to discuss a separate commercial license.
+
+--------------------------------------------------------------------------------
+This text is a license, not legal advice. If the boundary between a permitted
+"value-add" product and a prohibited "thin wrapper" is unclear for your use
+case, ask by opening an issue or messaging the maintainer on GitHub:
+https://github.com/JWriter20/CaptchaKraken
+--------------------------------------------------------------------------------

package/python/README.md

@@ -68,4 +68,6 @@ Everything model-specific lives in `captchakraken.config` and is env-overridable
 
 ## License
 
-GPL-3.0-or-later.
+**CaptchaKraken Source-Available License v1.0** — see [LICENSE](./LICENSE).
+Build *with* it (scrapers, stealth browsers, QA tooling); you may **not sell the
+solve itself** or ship a thin wrapper (browser extension, hosted solving API).

package/python/pyproject.toml

@@ -4,17 +4,21 @@ build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "2.2.0"
+version = "2.4.0"
 description = "Self-hosted captcha solver: OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA served on vLLM."
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "GPL-3.0-or-later" }
+# Source-available, NOT GPL. The CaptchaKraken Source-Available License permits
+# commercial use as an internal component but prohibits selling the solve itself
+# or thin-wrapper resale — see LICENSE. (GPL-3.0 would wrongly permit reselling.)
+license = { file = "LICENSE" }
 authors = [{ name = "Jake Writer" }]
 keywords = ["captcha", "recaptcha", "hcaptcha", "vllm", "qwen", "computer-vision", "automation"]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Operating System :: OS Independent",
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "License :: Other/Proprietary License",
 ]
 
 # Core = the lightweight CLIENT: OpenCV grid detection + the HTTP planner that

package/python/src/captchakraken/__init__.py

@@ -40,14 +40,26 @@ from .overlay import add_overlays_to_image
 try:  # pragma: no cover - exercised only when the serving stack is installed
     from .planner import ActionPlanner
     from .solver import CaptchaSolver, solve_captcha
+
+    # The page driver sits behind the same guard: it imports `solver`, so it has
+    # the same dependency floor. It needs NO browser package of its own — the
+    # caller supplies the Playwright-compatible page (see page_solver's module
+    # docstring on why we duck-type rather than import one).
+    from .page_solver import PageSolver, SolveResult, solve_captcha_on_page
 except ModuleNotFoundError:
     ActionPlanner = None  # type: ignore[assignment,misc]
     CaptchaSolver = None  # type: ignore[assignment,misc]
     solve_captcha = None  # type: ignore[assignment]
+    PageSolver = None  # type: ignore[assignment,misc]
+    SolveResult = None  # type: ignore[assignment,misc]
+    solve_captcha_on_page = None  # type: ignore[assignment]
 
 __all__ = [
     "CaptchaSolver",
     "solve_captcha",
+    "PageSolver",
+    "SolveResult",
+    "solve_captcha_on_page",
     "ActionPlanner",
     "ImageProcessor",
     "CaptchaAction",
@@ -58,4 +70,4 @@ __all__ = [
     "add_overlays_to_image",
 ]
 
-__version__ = "2.0.0"
+__version__ = "2.3.0"

package/python/src/captchakraken/cli.py

@@ -42,13 +42,21 @@ Modes:
         these — a local server auto-starts on the first solve (disable with
         CAPTCHA_KRAKEN_AUTOSTART=0). Point VLLM_BASE_URL at your own server to
         skip local management entirely.
+
+  captchakraken fetch [--weights-only|--engine-only] [--no-restart] [--dry-run]
+        Update in one step: pull the latest CaptchaKraken model from the HF org
+        (https://huggingface.co/CaptchaKraken) AND upgrade the vLLM serving
+        stack, then restart a running local server so it takes effect. Use this
+        to get new model revisions + engine fixes without re-running setup.sh.
 """
 
 import argparse
 import json
 import os
+import subprocess
 import sys
 
+from .errors import CaptchaKrakenAPIError
 from .solver import CaptchaSolver, UnsupportedCaptchaError
 from .timing import timed
 
@@ -372,6 +380,7 @@ def _handle_serve() -> bool:
       find-grid               {image}                       -> grid_boxes | null
       grid-cell-states        {a, b}                        -> states | {grid: null}
       grid-cell-states-fixed  {a, b, grid_boxes}            -> states
+      check-movement          {a, b, threshold?}            -> {has_movement: bool}
 
     Unknown cmd / malformed line -> an {ok:false} response (the process keeps
     running). EOF on stdin ends the loop cleanly. All heavy detection delegates
@@ -396,6 +405,15 @@ def _handle_serve() -> bool:
             if not grid_boxes:
                 raise ValueError("empty grid_boxes")
             return _compute_grid_cell_states(req["a"], req["b"], grid_boxes)
+        if cmd == "check-movement":
+            # Freshness check for the JS solver: did the captcha frame change
+            # (tiles faded in / refreshed) between the screenshot we sent the
+            # model and now? Same primitive the one-shot `check-movement` uses.
+            from .image_processor import ImageProcessor
+
+            threshold = float(req.get("threshold", 0.005))
+            moved = ImageProcessor.detect_movement(req["a"], req["b"], threshold)
+            return {"has_movement": bool(moved)}
         raise ValueError(f"unknown cmd: {cmd!r}")
 
     # Signal readiness so the JS side knows imports are done before it polls.
@@ -560,9 +578,55 @@ def _handle_server_commands() -> bool:
     return True
 
 
+def _handle_fetch() -> bool:
+    """`captchakraken fetch` — pull the latest published weights from the HF org
+    and refresh the vLLM serving stack, restarting a running local server so the
+    update takes effect. See updater.fetch for the full behavior."""
+    if len(sys.argv) <= 1 or sys.argv[1] not in {"fetch", "update"}:
+        return False
+
+    flags = set(sys.argv[2:])
+    unknown = flags - {"--weights-only", "--engine-only", "--no-restart", "--dry-run"}
+    if unknown:
+        print(
+            json.dumps({"error": f"unknown fetch flag(s): {sorted(unknown)} "
+                                 "(use --weights-only|--engine-only|--no-restart|--dry-run)"}),
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    if "--weights-only" in flags and "--engine-only" in flags:
+        print(json.dumps({"error": "--weights-only and --engine-only are mutually exclusive"}),
+              file=sys.stderr)
+        sys.exit(2)
+
+    from . import updater
+
+    weights = "--engine-only" not in flags
+    engine = "--weights-only" not in flags
+    try:
+        result = updater.fetch(
+            weights=weights,
+            engine=engine,
+            restart="--no-restart" not in flags,
+            dry_run="--dry-run" in flags,
+        )
+        print(json.dumps(result))
+        return True
+    except subprocess.CalledProcessError as e:
+        print(json.dumps({"error": f"fetch step failed (exit {e.returncode}): "
+                                   f"{' '.join(e.cmd) if isinstance(e.cmd, list) else e.cmd}"}),
+              file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}), file=sys.stderr)
+        sys.exit(1)
+
+
 def main():
     if _handle_server_commands():
         return
+    if _handle_fetch():
+        return
     if _handle_movement_commands():
         return
     if _handle_move_commands():
@@ -644,6 +708,17 @@ def main():
         # checkboxes. Emit a clean error with no traceback.
         print(json.dumps({"error": str(e), "unsupported": True}), file=sys.stderr)
         sys.exit(2)
+    except CaptchaKrakenAPIError as e:
+        # The hosted API refused us and told us why. That is an answer, not a
+        # crash, so no traceback: a stack trace here buries the one line the
+        # user needs ("out of credits, top up at …") under frames from a module
+        # they have never opened.
+        #
+        # Exit 3, distinct from 1 (genuine failure) and 2 (unsupported puzzle),
+        # and the payload carries the machine-readable fields so the JS driver
+        # can rebuild the error rather than regex it out of prose.
+        print(json.dumps(e.to_payload()), file=sys.stderr)
+        sys.exit(3)
     except Exception as e:
         import traceback
 

package/python/src/captchakraken/config.py

@@ -13,37 +13,187 @@ The two variables MOST users ever set:
 Advanced / self-hosting overrides (only needed to change WHICH model is served):
   CAPTCHA_BASE_MODEL      base weights vLLM loads         (HF id or local path)
   CAPTCHA_LORA_ADAPTER    LoRA applied on top             (HF id or local path)
+  CAPTCHA_LORA_REVISION   adapter git revision to serve
   CAPTCHA_LORA_NAME       served adapter name the client asks for as `model`
+
+Defaults for the model-identity values come from `pinned_model.json` (see
+`pinned()`), which records the model + prompt pair this release was validated
+against.
   VLLM_PORT, VLLM_GPU_MEMORY_UTILIZATION, VLLM_MAX_MODEL_LEN, VLLM_MAX_LORA_RANK
   CAPTCHA_KRAKEN_AUTOSTART=0   disable auto-starting a local server on first use
 """
 
+import json
 import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict
+
+_PINNED_MODEL_PATH = Path(__file__).with_name("pinned_model.json")
+
+
+@lru_cache(maxsize=1)
+def pinned() -> Dict[str, Any]:
+    """The pinned model manifest shipped with this release.
+
+    Defines the (base model, adapter, serving prompts) triple this version was
+    validated against. Env vars still override every value below — the manifest
+    supplies the DEFAULT and gives CI something to assert against, so an adapter
+    or prompt change is a reviewable diff instead of a silent drift.
+    """
+    with _PINNED_MODEL_PATH.open(encoding="utf-8") as f:
+        return json.load(f)
 
 
 # ── Inference endpoint ──────────────────────────────────────────────────────
 def base_url() -> str:
-    """OpenAI-compatible endpoint, e.g. http://localhost:8000/v1."""
-    return os.getenv("VLLM_BASE_URL", f"http://localhost:{port()}/v1")
+    """OpenAI-compatible endpoint, e.g. http://localhost:8000/v1.
+
+    Precedence mirrors `api_key()` exactly — env, then the credentials file,
+    then the local default — because the two values are set together and a
+    reader who has learned one ordering should not have to learn a second.
+
+      1. VLLM_BASE_URL. An explicit override always wins; self-hosters and the
+         dev environment depend on this and must not be silently redirected.
+      2. The credentials file. Written by the MCP signup flow alongside the key,
+         so onboarding configures the endpoint in the same step and a hosted
+         user needs no env plumbing at all.
+      3. localhost. Unchanged, and still correct: someone with no credentials
+         file is by definition not a hosted user, so the self-hosted default is
+         the right guess for them.
+
+    The bug this closes: a camoufox user who signed up through the MCP had a
+    valid key and no endpoint, so every solve dialled a local port with nothing
+    behind it and failed with connection-refused — a message that says nothing
+    about the fact that their requests were meant to go to api.captchakraken.com.
+    """
+    return (
+        os.getenv("VLLM_BASE_URL")
+        or _base_url_from_credentials_file()
+        or f"http://localhost:{port()}/v1"
+    )
+
+
+def state_dir() -> Path:
+    """Shared state dir for the pidfile, lockfile, server log, and credentials."""
+    return Path(os.getenv("CAPTCHA_KRAKEN_STATE_DIR", str(Path.home() / ".captchakraken")))
+
+
+def credentials_path() -> Path:
+    return state_dir() / "credentials"
+
+
+# Names the credentials file may use for each value. Two spellings each, because
+# the file doubles as something a user can `source` — the VLLM_* names are the
+# env vars this module already honours, and the CAPTCHA_KRAKEN_* names are what
+# the product calls them. Accepting both costs nothing and spares anyone the
+# discovery that they picked the wrong one.
+_KEY_NAMES = ("CAPTCHA_KRAKEN_API_KEY", "VLLM_API_KEY")
+_BASE_URL_NAMES = ("CAPTCHA_KRAKEN_BASE_URL", "VLLM_BASE_URL")
+
+
+def _read_credentials_file() -> Dict[str, str]:
+    """Parse the file the MCP server's signup flow writes.
+
+    Hosted-API onboarding writes the key to a 0600 file rather than returning it
+    through the agent transcript, so it never lands in an LLM context window.
+    Reading it here is what lets a solve authenticate with NO env vars set.
+
+    Returns a mapping of recognised name -> value. The special key ``""`` holds a
+    BARE TOKEN — a file containing nothing but `ck_live_…`, which is what the
+    original single-value format was and what a user hand-writing this file is
+    most likely to produce. Dropping that would silently break every existing
+    credentials file, so it is still accepted and still means "the API key".
+
+    Deliberately tolerant of quoting and comments: the file is written by a
+    *separate* tool, and a format mismatch here surfaces as a baffling 401
+    rather than an obvious parse error. Returns {} whenever the file is missing
+    or unreadable — the self-hosted case, which must stay silent.
+    """
+    try:
+        text = credentials_path().read_text(encoding="utf-8")
+    except OSError:
+        return {}
+
+    found: Dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            name, _, value = line.partition("=")
+            name = name.strip()
+            # An env-file with unrelated keys must not yield a bogus token.
+            if name not in _KEY_NAMES and name not in _BASE_URL_NAMES:
+                continue
+            found.setdefault(name, value.strip().strip("'\""))
+        elif "" not in found:
+            # A bare token. Only the first such line counts; later prose in a
+            # hand-edited file must not overwrite the credential.
+            found[""] = line.strip("'\"")
+
+    return found
+
+
+def _first_present(values: Dict[str, str], names) -> str:
+    """First non-empty value among `names`, in the order given."""
+    for name in names:
+        value = values.get(name, "").strip()
+        if value:
+            return value
+    return ""
+
+
+def _key_from_credentials_file() -> str:
+    """The API key from the credentials file, or "" if there isn't one."""
+    values = _read_credentials_file()
+    return _first_present(values, _KEY_NAMES) or values.get("", "").strip()
+
+
+def _base_url_from_credentials_file() -> str:
+    """The endpoint from the credentials file, or "" if it names none.
+
+    A bare-token file deliberately yields nothing here: it carries no endpoint,
+    and inventing the hosted one for it would silently redirect a self-hoster
+    who wrote a token into that file by hand.
+    """
+    return _first_present(_read_credentials_file(), _BASE_URL_NAMES)
 
 
 def api_key() -> str:
-    return os.getenv("CAPTCHA_KRAKEN_API_KEY") or os.getenv("VLLM_API_KEY") or "EMPTY"
+    """Bearer token, in precedence order.
+
+    Env first so an explicit override always wins, then the credentials file so
+    the MCP/hosted path needs no env plumbing at all, then "EMPTY" (which leaves
+    a self-hosted local vLLM open, as before).
+    """
+    return (
+        os.getenv("CAPTCHA_KRAKEN_API_KEY")
+        or os.getenv("VLLM_API_KEY")
+        or _key_from_credentials_file()
+        or "EMPTY"
+    )
 
 
 # ── Model identity (all overridable — the CLI itself is model-agnostic) ──────
 def base_model() -> str:
-    return os.getenv("CAPTCHA_BASE_MODEL", "Qwen/Qwen3.5-9B")
+    return os.getenv("CAPTCHA_BASE_MODEL", pinned()["base_model"])
 
 
 def lora_adapter() -> str:
     """HF repo id or local path of the captcha adapter served on top of the base."""
-    return os.getenv("CAPTCHA_LORA_ADAPTER", "CaptchaKraken/CaptchaKraken_v1")
+    return os.getenv("CAPTCHA_LORA_ADAPTER", pinned()["lora_adapter"])
+
+
+def lora_revision() -> str:
+    """Git revision of the adapter repo to serve — pinning this is what makes
+    'the adapter this release was tested against' a reproducible statement."""
+    return os.getenv("CAPTCHA_LORA_REVISION", pinned()["lora_revision"])
 
 
 def lora_name() -> str:
     """The served LoRA name the client sends as the `model` field."""
-    return os.getenv("CAPTCHA_LORA_NAME", "captcha")
+    return os.getenv("CAPTCHA_LORA_NAME", pinned()["lora_name"])
 
 
 # ── Local vLLM server knobs ─────────────────────────────────────────────────