CVE-2026-54635

pytonapi is a Python SDK for TONAPI that provides REST API, streaming, and webhook access to the TON blockchain. From 2.0.0 to 2.2.0, TonapiWebhookDispatcher fails to validate the Authorization header when a webhook handler is registered with the documented path argument, because setup() stores bearer tokens only under the default suffix paths and never adds the custom path to the token map, so self._tokens.get(path) returns None and the authentication guard is skipped. An unauthenticated remote attacker can POST forged payloads to the custom webhook endpoint and trigger victim-defined handlers. This issue is fixed in version 2.2.1.

pytonapi is a Python SDK for TONAPI that provides REST API, streaming, and webhook access to the TON blockchain. From 2.0.0 to 2.2.0, TonapiWebhookDispatcher fails to validate the Authorization header when a webhook handler is registered with the documented path argument, because setup() stores bearer tokens only under the default suffix paths and never adds the custom path to the token map, so self._tokens.get(path) returns None and the authentication guard is skipped. An unauthenticated remote attacker can POST forged payloads to the custom webhook endpoint and trigger victim-defined handlers. This issue is fixed in version 2.2.1.

Webhook Custom Path Authentication Bypass in pytonapi

Summary

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.

Details

The vulnerability is a fail-open authentication check in pytonapi/webhook/dispatcher.py.

Token registration (setup) stores tokens only under default suffix paths:

# dispatcher.py lines 109-112
suffix = self.DEFAULT_SUFFIXES[event_type]
local_path = self._path + suffix          # e.g., "/hook/account-tx"
webhook = await self._client.ensure(f"{self._url}{suffix}")
self._tokens[local_path] = webhook.token  # custom path is NEVER stored here

Handler registration preserves the custom path in the handler tuple:

# dispatcher.py lines 339, 342
resolved_path = path or self._resolve_path(event_type)  # -> "/hook/custom"
self._handlers[event_type].append((account_filter, fn, resolved_path))

Path routing (_build_path_map) correctly maps the custom path to the event type:

# dispatcher.py line 182
return {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers}
# -> {"/hook/custom": WebhookEventType.ACCOUNT_TX}

Authentication check (fail-open):

# dispatcher.py lines 286-288
expected_token = self._tokens.get(path)        # "/hook/custom" -> None
if expected_token is not None and authorization != f"Bearer {expected_token}":
    raise TONAPIError("Invalid webhook token")  # SKIPPED because expected_token is None

Because 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 — or whether it is absent entirely. Execution continues to lines 291 and 297 where the attacker's payload is parsed and the victim handler is invoked.

The 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.

PoC

Requirements: Python 3.12, pytonapi 2.2.0 installed from source (commit e46c4a4).

Build and run with Docker:

# From the repository root
docker build -t vuln001-pytonapi -f vuln-001/Dockerfile .
docker run --rm vuln001-pytonapi

The Dockerfile installs pytonapi from the local source tree and executes poc.py.

What the PoC does:

1. Creates a TonapiWebhookDispatcher with a custom-path handler (path="/hook/custom").
2. Calls setup() — tokens are registered only for /hook/account-tx.
3. Case A — calls process("/hook/custom", forged_payload, authorization=None): no Authorization header, handler fires.
4. Case B — calls process("/hook/custom", forged_payload, authorization="Bearer totally-wrong-token"): wrong token, handler still fires.
5. Case C (control) — same attack against the default path /hook/account-tx with no auth: correctly raises TONAPIError.
6. Case D (control) — default path with valid token: correctly accepted.

Simulated malicious HTTP request routed to the victim dispatcher:

POST /hook/custom HTTP/1.1
Host: victim.example
Content-Type: application/json
# No Authorization header

{"event_type":"account_tx","account_id":"0:victim","lt":1,"tx_hash":"FORGED_TX_HASH"}

Expected output confirming the vulnerability: …

pytonapi is a Python SDK for TONAPI that provides REST API, streaming, and webhook access to the TON blockchain. From 2.0.0 to 2.2.0, TonapiWebhookDispatcher fails to validate the Authorization header when a webhook handler is registered with the documented path argument, because setup() stores bearer tokens only under the default suffix paths and never adds the custom path to the token map, so self._tokens.get(path) returns None and the authentication guard is skipped. An unauthenticated remote attacker can POST forged payloads to the custom webhook endpoint and trigger victim-defined handlers. This issue is fixed in version 2.2.1.

pytonapi is a Python SDK for TONAPI that provides REST API, streaming, and webhook access to the TON blockchain. From 2.0.0 to 2.2.0, TonapiWebhookDispatcher fails to validate the Authorization header when a webhook handler is registered with the documented path argument, because setup() stores bearer tokens only under the default suffix paths and never adds the custom path to the token map, so self._tokens.get(path) returns None and the authentication guard is skipped. An unauthenticated remote attacker can POST forged payloads to the custom webhook endpoint and trigger victim-defined handlers. This issue is fixed in version 2.2.1.

Webhook Custom Path Authentication Bypass in pytonapi

Summary

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.

Details

The vulnerability is a fail-open authentication check in pytonapi/webhook/dispatcher.py.

Token registration (setup) stores tokens only under default suffix paths:

# dispatcher.py lines 109-112
suffix = self.DEFAULT_SUFFIXES[event_type]
local_path = self._path + suffix          # e.g., "/hook/account-tx"
webhook = await self._client.ensure(f"{self._url}{suffix}")
self._tokens[local_path] = webhook.token  # custom path is NEVER stored here

Handler registration preserves the custom path in the handler tuple:

# dispatcher.py lines 339, 342
resolved_path = path or self._resolve_path(event_type)  # -> "/hook/custom"
self._handlers[event_type].append((account_filter, fn, resolved_path))

Path routing (_build_path_map) correctly maps the custom path to the event type:

# dispatcher.py line 182
return {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers}
# -> {"/hook/custom": WebhookEventType.ACCOUNT_TX}

Authentication check (fail-open):

# dispatcher.py lines 286-288
expected_token = self._tokens.get(path)        # "/hook/custom" -> None
if expected_token is not None and authorization != f"Bearer {expected_token}":
    raise TONAPIError("Invalid webhook token")  # SKIPPED because expected_token is None

Because 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 — or whether it is absent entirely. Execution continues to lines 291 and 297 where the attacker's payload is parsed and the victim handler is invoked.

The 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.

PoC

Requirements: Python 3.12, pytonapi 2.2.0 installed from source (commit e46c4a4).

Build and run with Docker:

# From the repository root
docker build -t vuln001-pytonapi -f vuln-001/Dockerfile .
docker run --rm vuln001-pytonapi

The Dockerfile installs pytonapi from the local source tree and executes poc.py.

What the PoC does:

1. Creates a TonapiWebhookDispatcher with a custom-path handler (path="/hook/custom").
2. Calls setup() — tokens are registered only for /hook/account-tx.
3. Case A — calls process("/hook/custom", forged_payload, authorization=None): no Authorization header, handler fires.
4. Case B — calls process("/hook/custom", forged_payload, authorization="Bearer totally-wrong-token"): wrong token, handler still fires.
5. Case C (control) — same attack against the default path /hook/account-tx with no auth: correctly raises TONAPIError.
6. Case D (control) — default path with valid token: correctly accepted.

Simulated malicious HTTP request routed to the victim dispatcher:

POST /hook/custom HTTP/1.1
Host: victim.example
Content-Type: application/json
# No Authorization header

{"event_type":"account_tx","account_id":"0:victim","lt":1,"tx_hash":"FORGED_TX_HASH"}

Expected output confirming the vulnerability: …

Webhook Custom Path Authentication Bypass in pytonapi

Summary

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.

Details

The vulnerability is a fail-open authentication check in pytonapi/webhook/dispatcher.py.

Token registration (setup) stores tokens only under default suffix paths:

# dispatcher.py lines 109-112
suffix = self.DEFAULT_SUFFIXES[event_type]
local_path = self._path + suffix          # e.g., "/hook/account-tx"
webhook = await self._client.ensure(f"{self._url}{suffix}")
self._tokens[local_path] = webhook.token  # custom path is NEVER stored here

Handler registration preserves the custom path in the handler tuple:

# dispatcher.py lines 339, 342
resolved_path = path or self._resolve_path(event_type)  # -> "/hook/custom"
self._handlers[event_type].append((account_filter, fn, resolved_path))

Path routing (_build_path_map) correctly maps the custom path to the event type:

# dispatcher.py line 182
return {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers}
# -> {"/hook/custom": WebhookEventType.ACCOUNT_TX}

Authentication check (fail-open):

# dispatcher.py lines 286-288
expected_token = self._tokens.get(path)        # "/hook/custom" -> None
if expected_token is not None and authorization != f"Bearer {expected_token}":
    raise TONAPIError("Invalid webhook token")  # SKIPPED because expected_token is None

Because 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 — or whether it is absent entirely. Execution continues to lines 291 and 297 where the attacker's payload is parsed and the victim handler is invoked.

The 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.

PoC

Requirements: Python 3.12, pytonapi 2.2.0 installed from source (commit e46c4a4).

Build and run with Docker:

# From the repository root
docker build -t vuln001-pytonapi -f vuln-001/Dockerfile .
docker run --rm vuln001-pytonapi

The Dockerfile installs pytonapi from the local source tree and executes poc.py.

What the PoC does:

1. Creates a TonapiWebhookDispatcher with a custom-path handler (path="/hook/custom").
2. Calls setup() — tokens are registered only for /hook/account-tx.
3. Case A — calls process("/hook/custom", forged_payload, authorization=None): no Authorization header, handler fires.
4. Case B — calls process("/hook/custom", forged_payload, authorization="Bearer totally-wrong-token"): wrong token, handler still fires.
5. Case C (control) — same attack against the default path /hook/account-tx with no auth: correctly raises TONAPIError.
6. Case D (control) — default path with valid token: correctly accepted.

Simulated malicious HTTP request routed to the victim dispatcher:

POST /hook/custom HTTP/1.1
Host: victim.example
Content-Type: application/json
# No Authorization header

{"event_type":"account_tx","account_id":"0:victim","lt":1,"tx_hash":"FORGED_TX_HASH"}

Expected output confirming the vulnerability: …