tradingsignalbot 0.1.0__tar.gz

tradingsignalbot-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+package-lock.json
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/

tradingsignalbot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TradingSignalBot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

tradingsignalbot-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: tradingsignalbot
+Version: 0.1.0
+Summary: Verify TradingSignalBot webhook signatures (HMAC-SHA256, constant-time, timestamp window). Standard library only. The full API client comes when the sandbox opens.
+Project-URL: Homepage, https://tradingsignalbot.com/api/?via=tsb-sdk
+Project-URL: Source, https://github.com/TradingSignalBot/sdk/tree/main/python
+Project-URL: Issues, https://github.com/TradingSignalBot/sdk/issues
+Author: TradingSignalBot
+License-Expression: MIT
+License-File: LICENSE
+Keywords: forex signals api,hmac,signature,telegram signal bot,trading signals,tradingsignalbot,webhook
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# tradingsignalbot
+
+The Python client for the [TradingSignalBot API](https://tradingsignalbot.com/api/?via=tsb-sdk).
+
+**The API is a preview.** It is not live yet, so this package holds only the part you need first: **verifying the signature of a webhook delivery**, so you know an event came from TradingSignalBot and was not changed or replayed. The full client (render a chart from your own levels, register webhooks, read signals) comes here when the sandbox opens. [Get early access](https://tradingsignalbot.com/?for=developers&via=tsb-sdk#start) to get sandbox keys first.
+
+```sh
+pip install tradingsignalbot
+```
+
+Standard library only (`hmac.compare_digest`), Python 3.8+, typed.
+
+## Verify a delivery
+
+```python
+from flask import Flask, request, abort
+from tradingsignalbot import verify_webhook, WebhookVerificationError
+
+app = Flask(__name__)
+
+@app.post("/hooks/signals")
+def signals():
+    try:
+        event = verify_webhook(request.get_data(), request.headers.get("TSB-Signature"), SECRET)
+    except WebhookVerificationError as e:
+        abort(400, e.code)
+    return "", 204
+```
+
+Pass the **raw body**, exactly as it arrived. Parsed and re-serialised JSON will not match.
+
+## The scheme
+
+The scheme, as the [API page](https://tradingsignalbot.com/api/?via=tsb-sdk) states it:
+
+| | |
+| --- | --- |
+| Header | `TSB-Signature: t=<timestamp>,v1=<signature>` (shown on the preview page) |
+| Timestamp | Unix seconds (the preview's example uses the event's time in seconds) |
+| Signed | `"<timestamp>.<raw body>"`, HMAC-SHA256 with your webhook secret |
+| Signature | lowercase hex, 64 characters |
+| Window | the timestamp within 300 seconds of your clock, against replays *(`tolerance` changes it, 0 turns it off)* |
+| Several `v1=` | any one matching is enough, for secret rotation |
+
+The repository's `test-vectors.json` holds the cases both packages are tested against.
+
+Both packages compare in constant time and check every signature and every secret, so a mismatch takes as long as a match.
+
+## API
+
+| Function | Does |
+| --- | --- |
+| `verify_webhook(body, header, secret, tolerance=300, now=None)` | Verifies, returns the parsed event |
+| `verify_signature(...)` | Verifies, returns the timestamp; raises `WebhookVerificationError` |
+| `is_valid_signature(...)` | `True` / `False` |
+| `sign_payload(body, secret, timestamp=None)` | The header TradingSignalBot would send: for your tests |
+| `compute_signature(body, secret, t)` | The hex HMAC |
+| `parse_signature_header(header)` | `(timestamp, signatures)` |
+
+`secret` can be a list while you rotate it. `WebhookVerificationError.code` is one of `missing_header`, `bad_header`, `no_signature`, `timestamp`, `mismatch`, `bad_json`.
+
+## Licence
+
+MIT. Source and the JavaScript package: [github.com/TradingSignalBot/sdk](https://github.com/TradingSignalBot/sdk).
+
+---
+
+Part of the Forexia network: InterestRateDecision.com · Forexia Academy · [TradingSignalBot](https://tradingsignalbot.com/?via=tsb-sdk) · PropSim · OpenCharts

tradingsignalbot-0.1.0/README.md

@@ -0,0 +1,68 @@
+# tradingsignalbot
+
+The Python client for the [TradingSignalBot API](https://tradingsignalbot.com/api/?via=tsb-sdk).
+
+**The API is a preview.** It is not live yet, so this package holds only the part you need first: **verifying the signature of a webhook delivery**, so you know an event came from TradingSignalBot and was not changed or replayed. The full client (render a chart from your own levels, register webhooks, read signals) comes here when the sandbox opens. [Get early access](https://tradingsignalbot.com/?for=developers&via=tsb-sdk#start) to get sandbox keys first.
+
+```sh
+pip install tradingsignalbot
+```
+
+Standard library only (`hmac.compare_digest`), Python 3.8+, typed.
+
+## Verify a delivery
+
+```python
+from flask import Flask, request, abort
+from tradingsignalbot import verify_webhook, WebhookVerificationError
+
+app = Flask(__name__)
+
+@app.post("/hooks/signals")
+def signals():
+    try:
+        event = verify_webhook(request.get_data(), request.headers.get("TSB-Signature"), SECRET)
+    except WebhookVerificationError as e:
+        abort(400, e.code)
+    return "", 204
+```
+
+Pass the **raw body**, exactly as it arrived. Parsed and re-serialised JSON will not match.
+
+## The scheme
+
+The scheme, as the [API page](https://tradingsignalbot.com/api/?via=tsb-sdk) states it:
+
+| | |
+| --- | --- |
+| Header | `TSB-Signature: t=<timestamp>,v1=<signature>` (shown on the preview page) |
+| Timestamp | Unix seconds (the preview's example uses the event's time in seconds) |
+| Signed | `"<timestamp>.<raw body>"`, HMAC-SHA256 with your webhook secret |
+| Signature | lowercase hex, 64 characters |
+| Window | the timestamp within 300 seconds of your clock, against replays *(`tolerance` changes it, 0 turns it off)* |
+| Several `v1=` | any one matching is enough, for secret rotation |
+
+The repository's `test-vectors.json` holds the cases both packages are tested against.
+
+Both packages compare in constant time and check every signature and every secret, so a mismatch takes as long as a match.
+
+## API
+
+| Function | Does |
+| --- | --- |
+| `verify_webhook(body, header, secret, tolerance=300, now=None)` | Verifies, returns the parsed event |
+| `verify_signature(...)` | Verifies, returns the timestamp; raises `WebhookVerificationError` |
+| `is_valid_signature(...)` | `True` / `False` |
+| `sign_payload(body, secret, timestamp=None)` | The header TradingSignalBot would send: for your tests |
+| `compute_signature(body, secret, t)` | The hex HMAC |
+| `parse_signature_header(header)` | `(timestamp, signatures)` |
+
+`secret` can be a list while you rotate it. `WebhookVerificationError.code` is one of `missing_header`, `bad_header`, `no_signature`, `timestamp`, `mismatch`, `bad_json`.
+
+## Licence
+
+MIT. Source and the JavaScript package: [github.com/TradingSignalBot/sdk](https://github.com/TradingSignalBot/sdk).
+
+---
+
+Part of the Forexia network: InterestRateDecision.com · Forexia Academy · [TradingSignalBot](https://tradingsignalbot.com/?via=tsb-sdk) · PropSim · OpenCharts

tradingsignalbot-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tradingsignalbot"
+version = "0.1.0"
+description = "Verify TradingSignalBot webhook signatures (HMAC-SHA256, constant-time, timestamp window). Standard library only. The full API client comes when the sandbox opens."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "TradingSignalBot" }]
+keywords = ["tradingsignalbot", "webhook", "signature", "hmac", "forex signals api", "telegram signal bot", "trading signals"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Topic :: Security :: Cryptography",
+  "Intended Audience :: Developers",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://tradingsignalbot.com/api/?via=tsb-sdk"
+Source = "https://github.com/TradingSignalBot/sdk/tree/main/python"
+Issues = "https://github.com/TradingSignalBot/sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tradingsignalbot"]

tradingsignalbot-0.1.0/src/tradingsignalbot/__init__.py

@@ -0,0 +1,30 @@
+"""TradingSignalBot: verify webhook signatures. The full API client comes when the sandbox opens.
+
+https://tradingsignalbot.com/api/?via=tsb-sdk
+"""
+
+from .webhooks import (
+    DEFAULT_TOLERANCE,
+    SIGNATURE_HEADER,
+    WebhookVerificationError,
+    compute_signature,
+    is_valid_signature,
+    parse_signature_header,
+    sign_payload,
+    verify_signature,
+    verify_webhook,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_TOLERANCE",
+    "SIGNATURE_HEADER",
+    "WebhookVerificationError",
+    "compute_signature",
+    "is_valid_signature",
+    "parse_signature_header",
+    "sign_payload",
+    "verify_signature",
+    "verify_webhook",
+]

tradingsignalbot-0.1.0/src/tradingsignalbot/webhooks.py

@@ -0,0 +1,145 @@
+"""Verify that a webhook delivery came from TradingSignalBot.
+
+The signature scheme (see README, "The scheme")::
+
+    header   TSB-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>...]
+    signed   f"{t}.{raw_body}", HMAC-SHA256 with your webhook secret, lowercase hex
+    window   t within 300 seconds of now (configurable)
+
+Standard library only.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Iterable, List, Optional, Sequence, Tuple, Union
+
+SIGNATURE_HEADER = "TSB-Signature"
+DEFAULT_TOLERANCE = 300
+
+Payload = Union[bytes, bytearray, memoryview, str]
+Secret = Union[str, bytes, Sequence[Union[str, bytes]]]
+
+_HEX64 = re.compile(r"^[0-9a-fA-F]{64}$")
+
+
+class WebhookVerificationError(Exception):
+    """Raised when a delivery cannot be trusted. ``code`` says why:
+    missing_header, bad_header, no_signature, timestamp, mismatch, bad_json."""
+
+    def __init__(self, message: str, code: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _bytes(payload: Payload) -> bytes:
+    if isinstance(payload, str):
+        return payload.encode("utf-8")
+    if isinstance(payload, (bytes, bytearray, memoryview)):
+        return bytes(payload)
+    raise TypeError("tradingsignalbot: pass the raw request body (bytes or str), not parsed JSON")
+
+
+def _key(secret: Union[str, bytes]) -> bytes:
+    if not secret:
+        raise TypeError("tradingsignalbot: the webhook secret is required")
+    return secret.encode("utf-8") if isinstance(secret, str) else bytes(secret)
+
+
+def parse_signature_header(header: Optional[Union[str, Iterable[str]]]) -> Tuple[int, List[str]]:
+    """``t=...,v1=...,v1=...`` to ``(timestamp, signatures)``. Unknown schemes are ignored."""
+    if header is None or header == "":
+        raise WebhookVerificationError(f"missing {SIGNATURE_HEADER} header", "missing_header")
+    if not isinstance(header, str):
+        header = ",".join(header)
+    timestamp: Optional[int] = None
+    signatures: List[str] = []
+    for part in header.split(","):
+        if "=" not in part:
+            continue
+        k, v = part.split("=", 1)
+        k, v = k.strip(), v.strip()
+        if k == "t":
+            timestamp = int(v) if v.isdigit() and v.isascii() else None
+        elif k == "v1" and _HEX64.match(v):
+            signatures.append(v.lower())
+    if timestamp is None:
+        raise WebhookVerificationError(f"{SIGNATURE_HEADER} has no valid t=", "bad_header")
+    if not signatures:
+        raise WebhookVerificationError(f"{SIGNATURE_HEADER} has no v1= signature", "no_signature")
+    return timestamp, signatures
+
+
+def compute_signature(payload: Payload, secret: Union[str, bytes], timestamp: int) -> str:
+    """HMAC-SHA256 of ``f"{timestamp}.{payload}"``, lowercase hex."""
+    msg = f"{timestamp}.".encode("ascii") + _bytes(payload)
+    return hmac.new(_key(secret), msg, hashlib.sha256).hexdigest()
+
+
+def verify_signature(
+    payload: Payload,
+    header: Optional[Union[str, Iterable[str]]],
+    secret: Secret,
+    tolerance: int = DEFAULT_TOLERANCE,
+    now: Optional[int] = None,
+) -> int:
+    """Raise WebhookVerificationError unless the header is a valid, fresh
+    signature of the raw body. Returns the delivery's timestamp.
+
+    ``secret`` may be a list while you rotate it. ``tolerance`` is in seconds;
+    0 turns the timestamp check off."""
+    timestamp, signatures = parse_signature_header(header)
+    now = int(time.time()) if now is None else now
+    if tolerance > 0 and abs(now - timestamp) > tolerance:
+        raise WebhookVerificationError(
+            f"timestamp {timestamp} is outside the {tolerance} s window (now {now})", "timestamp"
+        )
+    secrets = [secret] if isinstance(secret, (str, bytes)) else list(secret)
+    ok = False
+    for sec in secrets:
+        expected = compute_signature(payload, sec, timestamp)
+        for sig in signatures:  # check them all: no early exit
+            ok = hmac.compare_digest(expected, sig) or ok
+    if not ok:
+        raise WebhookVerificationError("signature does not match", "mismatch")
+    return timestamp
+
+
+def is_valid_signature(
+    payload: Payload,
+    header: Optional[Union[str, Iterable[str]]],
+    secret: Secret,
+    tolerance: int = DEFAULT_TOLERANCE,
+    now: Optional[int] = None,
+) -> bool:
+    """Like verify_signature, but True or False instead of raising."""
+    try:
+        verify_signature(payload, header, secret, tolerance=tolerance, now=now)
+        return True
+    except WebhookVerificationError:
+        return False
+
+
+def verify_webhook(
+    payload: Payload,
+    header: Optional[Union[str, Iterable[str]]],
+    secret: Secret,
+    tolerance: int = DEFAULT_TOLERANCE,
+    now: Optional[int] = None,
+) -> Any:
+    """Verify the delivery and return the parsed event (``{"type", "created", "data"}``)."""
+    verify_signature(payload, header, secret, tolerance=tolerance, now=now)
+    try:
+        return json.loads(_bytes(payload).decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        raise WebhookVerificationError("the body is not JSON", "bad_json") from None
+
+
+def sign_payload(payload: Payload, secret: Union[str, bytes], timestamp: Optional[int] = None) -> str:
+    """The header TradingSignalBot would send for this body: for your tests and local replays."""
+    t = int(time.time()) if timestamp is None else timestamp
+    return f"t={t},v1={compute_signature(payload, secret, t)}"

tradingsignalbot-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,90 @@
+import hashlib
+import hmac
+import json
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "src"))
+
+from tradingsignalbot import (  # noqa: E402
+    WebhookVerificationError,
+    compute_signature,
+    is_valid_signature,
+    parse_signature_header,
+    sign_payload,
+    verify_signature,
+    verify_webhook,
+)
+
+VECTORS = json.loads((pathlib.Path(__file__).resolve().parents[2] / "test-vectors.json").read_text("utf-8"))
+SECRET = "whsec_test"
+BODY = json.dumps({"type": "signal.target_hit", "created": "2026-10-14T19:30:00Z", "data": {"target": 2}})
+T = 1792001400
+
+
+def code(fn, *a, **k):
+    try:
+        fn(*a, **k)
+    except WebhookVerificationError as e:
+        return e.code
+    return "ok"
+
+
+class Vectors(unittest.TestCase):
+    def test_shared_vectors(self):
+        for v in VECTORS["cases"]:
+            with self.subTest(v["name"]):
+                self.assertEqual(compute_signature(v["body"], v["secret"], v["timestamp"]), v["signature"])
+                self.assertEqual(code(verify_signature, v["body"], v["header"], v["secret"], now=v["now"]), v["expect"])
+
+
+class Verify(unittest.TestCase):
+    def test_plain_hmac(self):
+        expected = hmac.new(SECRET.encode(), f"{T}.{BODY}".encode(), hashlib.sha256).hexdigest()
+        self.assertEqual(compute_signature(BODY, SECRET, T), expected)
+        self.assertEqual(sign_payload(BODY, SECRET, timestamp=T), f"t={T},v1={expected}")
+
+    def test_good_delivery(self):
+        header = sign_payload(BODY, SECRET, timestamp=T)
+        event = verify_webhook(BODY.encode(), header, SECRET, now=T + 10)
+        self.assertEqual(event["type"], "signal.target_hit")
+        self.assertTrue(is_valid_signature(bytearray(BODY.encode()), header, SECRET, now=T))
+        self.assertEqual(verify_signature(BODY, header, SECRET, now=T), T)
+
+    def test_refused(self):
+        header = sign_payload(BODY, SECRET, timestamp=T)
+        self.assertEqual(code(verify_signature, BODY + " ", header, SECRET, now=T), "mismatch")
+        self.assertEqual(code(verify_signature, BODY, header, "other", now=T), "mismatch")
+        self.assertEqual(code(verify_signature, BODY, header, SECRET, now=T + 301), "timestamp")
+        self.assertEqual(code(verify_signature, BODY, header, SECRET, now=T - 301), "timestamp")
+        self.assertEqual(code(verify_signature, BODY, header, SECRET, now=T + 10_000, tolerance=0), "ok")
+        self.assertEqual(code(verify_signature, BODY, header.replace(f"t={T}", f"t={T + 1}"), SECRET, now=T), "mismatch")
+
+    def test_bad_headers(self):
+        self.assertEqual(code(verify_signature, BODY, None, SECRET), "missing_header")
+        self.assertEqual(code(verify_signature, BODY, "", SECRET), "missing_header")
+        self.assertEqual(code(verify_signature, BODY, "v1=" + "a" * 64, SECRET), "bad_header")
+        self.assertEqual(code(verify_signature, BODY, f"t={T}", SECRET, now=T), "no_signature")
+        self.assertEqual(code(verify_signature, BODY, f"t={T},v1=short", SECRET, now=T), "no_signature")
+        self.assertEqual(code(verify_signature, BODY, "t=-5,v1=" + "a" * 64, SECRET), "bad_header")
+
+    def test_rotation(self):
+        sig = compute_signature(BODY, SECRET, T)
+        header = f"t={T},v1={'0' * 64},v1={sig},v0=whatever"
+        self.assertEqual(len(parse_signature_header(header)[1]), 2)
+        self.assertTrue(is_valid_signature(BODY, header, SECRET, now=T))
+        self.assertTrue(is_valid_signature(BODY, f"t={T},v1={sig}", ["new_secret", SECRET], now=T))
+        self.assertTrue(is_valid_signature(BODY, f" t={T} , v1={sig.upper()} ", SECRET, now=T))
+
+    def test_parsed_json_refused(self):
+        with self.assertRaises(TypeError):
+            verify_signature(json.loads(BODY), f"t={T},v1={'a' * 64}", SECRET, now=T)
+
+    def test_not_json(self):
+        header = sign_payload("not json", SECRET, timestamp=T)
+        self.assertEqual(code(verify_webhook, "not json", header, SECRET, now=T), "bad_json")
+
+
+if __name__ == "__main__":
+    unittest.main()