tikwebsign 0.1.0__tar.gz

tikwebsign-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: tikwebsign
+Version: 0.1.0
+Summary: Safe HMAC request signing helpers for authorized APIs
+Author: tikwebsign contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# tikwebsign
+
+مكتبة صغيرة لتوقيع طلبات HTTP الخاصة بواجهات API التي تملكها أو لديك تفويض صريح لاستخدامها. تستخدم **HMAC-SHA256** مع canonical request، ولا تطبق تجاوزات anti-bot أو فحص بيانات اعتماد أو جمع cookies/tokens من خدمات طرف ثالث.
+
+## التثبيت
+
+```bash
+pip install -e .
+```
+
+## الاستخدام
+
+```python
+import requests
+import tikwebsign
+
+url = "https://api.example.com/v1/items"
+params = {"page": 1, "limit": 20}
+body = {"filter": "active"}
+signer = tikwebsign.RequestSigner("ضع-المفتاح-السري-في-متغير-بيئة", key_id="client-1")
+
+# الدوال ترجع dicts؛ لذلك الاستدعاء الصحيح يتضمن الأقواس.
+signed_params = tikwebsign.getparams(
+    signer=signer, method="POST", url=url, params=params, body=body
+)
+headers = tikwebsign.getheaders(
+    signer=signer, method="POST", url=url, params=params, body=body,
+    headers={"Content-Type": "application/json"}
+)
+params.update(signed_params)
+response = requests.post(url, params=params, json=body, headers=headers, timeout=30)
+response.raise_for_status()
+```
+
+> لا يمكن جعل `params.update(tikwebsign.getparams)` يولّد توقيعًا صحيحًا دون معرفة method وURL وbody والسر. لذلك صُممت الدوال كـ `getparams(...)` و`getheaders(...)` حتى يوقّع الخادم نفس البيانات بالترتيب canonical نفسه.
+
+## صيغة التوقيع للخادم
+
+يبني العميل النص التالي مفصولًا بـ newline:
+
+```text
+METHOD
+URL
+sorted-urlencoded-query
+sha256(body)
+timestamp
+nonce
+```
+
+ثم يحسب `HMAC-SHA256(secret, canonical_request)` ويضع القيمة Base64URL في `X-Request-Signature`. يجب على الخادم التحقق من `timestamp` ضمن نافذة قصيرة (مثل 300 ثانية)، ومنع إعادة استخدام `nonce`، واستخدام مقارنة ثابتة الزمن.
+
+## توليد جهاز محلي
+
+```python
+device = tikwebsign.generate_device(user_agent="my-client/1.0")
+print(device.to_dict())
+```
+
+هذا مولد هوية محلية فقط، ولا يتصل بأي خدمة خارجية ولا ينشئ tokens أو cookies خاصة بخدمة أخرى.

tikwebsign-0.1.0/README.md

@@ -0,0 +1,59 @@
+# tikwebsign
+
+مكتبة صغيرة لتوقيع طلبات HTTP الخاصة بواجهات API التي تملكها أو لديك تفويض صريح لاستخدامها. تستخدم **HMAC-SHA256** مع canonical request، ولا تطبق تجاوزات anti-bot أو فحص بيانات اعتماد أو جمع cookies/tokens من خدمات طرف ثالث.
+
+## التثبيت
+
+```bash
+pip install -e .
+```
+
+## الاستخدام
+
+```python
+import requests
+import tikwebsign
+
+url = "https://api.example.com/v1/items"
+params = {"page": 1, "limit": 20}
+body = {"filter": "active"}
+signer = tikwebsign.RequestSigner("ضع-المفتاح-السري-في-متغير-بيئة", key_id="client-1")
+
+# الدوال ترجع dicts؛ لذلك الاستدعاء الصحيح يتضمن الأقواس.
+signed_params = tikwebsign.getparams(
+    signer=signer, method="POST", url=url, params=params, body=body
+)
+headers = tikwebsign.getheaders(
+    signer=signer, method="POST", url=url, params=params, body=body,
+    headers={"Content-Type": "application/json"}
+)
+params.update(signed_params)
+response = requests.post(url, params=params, json=body, headers=headers, timeout=30)
+response.raise_for_status()
+```
+
+> لا يمكن جعل `params.update(tikwebsign.getparams)` يولّد توقيعًا صحيحًا دون معرفة method وURL وbody والسر. لذلك صُممت الدوال كـ `getparams(...)` و`getheaders(...)` حتى يوقّع الخادم نفس البيانات بالترتيب canonical نفسه.
+
+## صيغة التوقيع للخادم
+
+يبني العميل النص التالي مفصولًا بـ newline:
+
+```text
+METHOD
+URL
+sorted-urlencoded-query
+sha256(body)
+timestamp
+nonce
+```
+
+ثم يحسب `HMAC-SHA256(secret, canonical_request)` ويضع القيمة Base64URL في `X-Request-Signature`. يجب على الخادم التحقق من `timestamp` ضمن نافذة قصيرة (مثل 300 ثانية)، ومنع إعادة استخدام `nonce`، واستخدام مقارنة ثابتة الزمن.
+
+## توليد جهاز محلي
+
+```python
+device = tikwebsign.generate_device(user_agent="my-client/1.0")
+print(device.to_dict())
+```
+
+هذا مولد هوية محلية فقط، ولا يتصل بأي خدمة خارجية ولا ينشئ tokens أو cookies خاصة بخدمة أخرى.

tikwebsign-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tikwebsign"
+version = "0.1.0"
+description = "Safe HMAC request signing helpers for authorized APIs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "tikwebsign contributors"}]
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["."]

tikwebsign-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tikwebsign-0.1.0/tests/run_tests.py

@@ -0,0 +1,33 @@
+import base64
+import hashlib
+import hmac
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parents[1]))
+import tikwebsign
+
+signer = tikwebsign.RequestSigner("secret", key_id="k1")
+params, headers = signer.sign(
+    method="post", url="https://api.example.test/v1", params={"b": 2, "a": 1},
+    body='{"x":1}', timestamp=1700000000, nonce="n1"
+)
+canonical = "\n".join((
+    "POST", "https://api.example.test/v1", "a=1&b=2",
+    hashlib.sha256(b'{"x":1}').hexdigest(), "1700000000", "n1"
+))
+expected = base64.urlsafe_b64encode(
+    hmac.new(b"secret", canonical.encode(), hashlib.sha256).digest()
+).decode().rstrip("=")
+assert params == {"ts": "1700000000", "nonce": "n1", "key_id": "k1"}
+assert headers["X-Request-Signature"] == expected
+
+base = {"q": "hello"}
+base.update(tikwebsign.getparams(signer=signer, method="GET", url="https://x", params=base))
+assert "ts" in base
+assert "X-Request-Signature" in tikwebsign.getheaders(
+    signer=signer, method="GET", url="https://x", params={"q": "hello"}
+)
+device = tikwebsign.generate_device()
+assert len(device.device_id) == 36
+print("ok")

tikwebsign-0.1.0/tests/test_core.py

@@ -0,0 +1,37 @@
+import base64
+import hashlib
+import hmac
+
+import tikwebsign
+
+
+def test_signature_is_deterministic_with_fixed_nonce_and_timestamp():
+    signer = tikwebsign.RequestSigner("secret", key_id="k1")
+    params, headers = signer.sign(
+        method="post", url="https://api.example.test/v1", params={"b": 2, "a": 1},
+        body='{"x":1}', timestamp=1700000000, nonce="n1"
+    )
+    canonical = "\n".join((
+        "POST", "https://api.example.test/v1", "a=1&b=2",
+        hashlib.sha256(b'{"x":1}').hexdigest(), "1700000000", "n1"
+    ))
+    expected = base64.urlsafe_b64encode(
+        hmac.new(b"secret", canonical.encode(), hashlib.sha256).digest()
+    ).decode().rstrip("=")
+    assert params == {"ts": "1700000000", "nonce": "n1", "key_id": "k1"}
+    assert headers["X-Request-Signature"] == expected
+
+
+def test_helpers_return_mergeable_dicts():
+    signer = tikwebsign.RequestSigner("secret")
+    params = {"q": "hello"}
+    params.update(tikwebsign.getparams(signer=signer, method="GET", url="https://x", params=params))
+    headers = tikwebsign.getheaders(signer=signer, method="GET", url="https://x", params=params)
+    assert "ts" in params and "X-Request-Signature" in headers
+
+
+def test_device_is_local_and_serializable():
+    device = tikwebsign.generate_device()
+    data = device.to_dict()
+    assert len(data["device_id"]) == 36
+    assert data["platform"] == "python"

tikwebsign-0.1.0/tikwebsign/__init__.py

@@ -0,0 +1,15 @@
+"""tikwebsign: safe request signing helpers for APIs you own or are authorized to use.
+
+This package deliberately does not implement third-party anti-bot bypasses,
+credential checking, login automation, or scraping of device tokens.
+"""
+from .core import Device, RequestSigner, generate_device, getheaders, getparams
+
+__all__ = [
+    "Device",
+    "RequestSigner",
+    "generate_device",
+    "getheaders",
+    "getparams",
+]
+__version__ = "0.1.0"

tikwebsign-0.1.0/tikwebsign/core.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+import uuid
+from dataclasses import asdict, dataclass
+from typing import Mapping, MutableMapping
+from urllib.parse import urlencode
+
+
+@dataclass(frozen=True)
+class Device:
+    """Stable local client identity; contains no third-party cookies or tokens."""
+
+    device_id: str
+    user_agent: str
+    platform: str = "python"
+    created_at: int = 0
+
+    def to_dict(self) -> dict[str, str | int]:
+        return asdict(self)
+
+
+def generate_device(*, user_agent: str = "tikwebsign/0.1", platform: str = "python") -> Device:
+    """Generate a local device identity for an authorized API client."""
+    return Device(
+        device_id=str(uuid.uuid4()),
+        user_agent=user_agent,
+        platform=platform,
+        created_at=int(time.time()),
+    )
+
+
+def _canonical_query(params: Mapping[str, object]) -> str:
+    pairs: list[tuple[str, str]] = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            pairs.extend((str(key), str(item)) for item in value)
+        else:
+            pairs.append((str(key), str(value)))
+    return urlencode(sorted(pairs), doseq=True)
+
+
+def _body_bytes(body: str | bytes | bytearray | Mapping[str, object] | None) -> bytes:
+    if body is None:
+        return b""
+    if isinstance(body, (bytes, bytearray)):
+        return bytes(body)
+    if isinstance(body, str):
+        return body.encode("utf-8")
+    return json.dumps(body, separators=(",", ":"), sort_keys=True, ensure_ascii=False).encode("utf-8")
+
+
+class RequestSigner:
+    """HMAC-SHA256 signer for a first-party or explicitly authorized API."""
+
+    def __init__(self, secret: str | bytes, *, key_id: str = "default", ttl: int = 300):
+        self.secret = secret.encode() if isinstance(secret, str) else bytes(secret)
+        if not self.secret:
+            raise ValueError("secret must not be empty")
+        if ttl <= 0:
+            raise ValueError("ttl must be positive")
+        self.key_id, self.ttl = key_id, ttl
+
+    def sign(self, *, method: str, url: str, params: Mapping[str, object] | None = None,
+             body: str | bytes | bytearray | Mapping[str, object] | None = None,
+             timestamp: int | None = None, nonce: str | None = None) -> tuple[dict[str, str], dict[str, str]]:
+        timestamp = int(time.time()) if timestamp is None else int(timestamp)
+        nonce = secrets.token_urlsafe(18) if nonce is None else nonce
+        query = _canonical_query(params or {})
+        body_hash = hashlib.sha256(_body_bytes(body)).hexdigest()
+        canonical = "\n".join((method.upper(), url, query, body_hash, str(timestamp), nonce))
+        digest = hmac.new(self.secret, canonical.encode("utf-8"), hashlib.sha256).digest()
+        signature = base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+        signed_params = {"ts": str(timestamp), "nonce": nonce, "key_id": self.key_id}
+        signed_headers = {
+            "X-Api-Key-Id": self.key_id,
+            "X-Request-Timestamp": str(timestamp),
+            "X-Request-Nonce": nonce,
+            "X-Request-Signature": signature,
+        }
+        return signed_params, signed_headers
+
+
+def getparams(*, signer: RequestSigner, method: str, url: str,
+              params: Mapping[str, object] | None = None,
+              body: str | bytes | bytearray | Mapping[str, object] | None = None) -> dict[str, str]:
+    """Return signed query parameters to merge with ``params``."""
+    signed, _ = signer.sign(method=method, url=url, params=params, body=body)
+    return signed
+
+
+def getheaders(*, signer: RequestSigner, method: str, url: str,
+               params: Mapping[str, object] | None = None,
+               body: str | bytes | bytearray | Mapping[str, object] | None = None,
+               headers: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Return signed headers, preserving caller headers without overwriting them."""
+    _, signed = signer.sign(method=method, url=url, params=params, body=body)
+    result = dict(headers or {})
+    result.update(signed)
+    return result

tikwebsign-0.1.0/tikwebsign.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: tikwebsign
+Version: 0.1.0
+Summary: Safe HMAC request signing helpers for authorized APIs
+Author: tikwebsign contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# tikwebsign
+
+مكتبة صغيرة لتوقيع طلبات HTTP الخاصة بواجهات API التي تملكها أو لديك تفويض صريح لاستخدامها. تستخدم **HMAC-SHA256** مع canonical request، ولا تطبق تجاوزات anti-bot أو فحص بيانات اعتماد أو جمع cookies/tokens من خدمات طرف ثالث.
+
+## التثبيت
+
+```bash
+pip install -e .
+```
+
+## الاستخدام
+
+```python
+import requests
+import tikwebsign
+
+url = "https://api.example.com/v1/items"
+params = {"page": 1, "limit": 20}
+body = {"filter": "active"}
+signer = tikwebsign.RequestSigner("ضع-المفتاح-السري-في-متغير-بيئة", key_id="client-1")
+
+# الدوال ترجع dicts؛ لذلك الاستدعاء الصحيح يتضمن الأقواس.
+signed_params = tikwebsign.getparams(
+    signer=signer, method="POST", url=url, params=params, body=body
+)
+headers = tikwebsign.getheaders(
+    signer=signer, method="POST", url=url, params=params, body=body,
+    headers={"Content-Type": "application/json"}
+)
+params.update(signed_params)
+response = requests.post(url, params=params, json=body, headers=headers, timeout=30)
+response.raise_for_status()
+```
+
+> لا يمكن جعل `params.update(tikwebsign.getparams)` يولّد توقيعًا صحيحًا دون معرفة method وURL وbody والسر. لذلك صُممت الدوال كـ `getparams(...)` و`getheaders(...)` حتى يوقّع الخادم نفس البيانات بالترتيب canonical نفسه.
+
+## صيغة التوقيع للخادم
+
+يبني العميل النص التالي مفصولًا بـ newline:
+
+```text
+METHOD
+URL
+sorted-urlencoded-query
+sha256(body)
+timestamp
+nonce
+```
+
+ثم يحسب `HMAC-SHA256(secret, canonical_request)` ويضع القيمة Base64URL في `X-Request-Signature`. يجب على الخادم التحقق من `timestamp` ضمن نافذة قصيرة (مثل 300 ثانية)، ومنع إعادة استخدام `nonce`، واستخدام مقارنة ثابتة الزمن.
+
+## توليد جهاز محلي
+
+```python
+device = tikwebsign.generate_device(user_agent="my-client/1.0")
+print(device.to_dict())
+```
+
+هذا مولد هوية محلية فقط، ولا يتصل بأي خدمة خارجية ولا ينشئ tokens أو cookies خاصة بخدمة أخرى.

tikwebsign-0.1.0/tikwebsign.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+tests/run_tests.py
+tests/test_core.py
+tikwebsign/__init__.py
+tikwebsign/core.py
+tikwebsign.egg-info/PKG-INFO
+tikwebsign.egg-info/SOURCES.txt
+tikwebsign.egg-info/dependency_links.txt
+tikwebsign.egg-info/top_level.txt

tikwebsign-0.1.0/tikwebsign.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tikwebsign-0.1.0/tikwebsign.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+tests
+tikwebsign