truthid-sdk 0.1.0__tar.gz

truthid_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/

truthid_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 masterlxz
+
+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.

truthid_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: truthid-sdk
+Version: 0.1.0
+Summary: TruthID passwordless, decentralized authentication SDK for Python
+Project-URL: Homepage, https://github.com/masterlxz/truthid/tree/main/sdk/python#readme
+Project-URL: Repository, https://github.com/masterlxz/truthid
+Project-URL: Issues, https://github.com/masterlxz/truthid/issues
+Author: masterlxz
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,authentication,blockchain,decentralized,passwordless,web3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: web3>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# truthid-sdk
+
+TruthID passwordless, decentralized authentication SDK for Python.
+
+Integrate passwordless, decentralized authentication into your app in minutes — no TruthID-operated server, no passwords, no third-party login.
+
+```bash
+pip install truthid-sdk
+```
+
+Full documentation, how it works, and usage examples: [github.com/masterlxz/truthid/tree/main/sdk](https://github.com/masterlxz/truthid/tree/main/sdk#readme)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

truthid_sdk-0.1.0/README.md

@@ -0,0 +1,15 @@
+# truthid-sdk
+
+TruthID passwordless, decentralized authentication SDK for Python.
+
+Integrate passwordless, decentralized authentication into your app in minutes — no TruthID-operated server, no passwords, no third-party login.
+
+```bash
+pip install truthid-sdk
+```
+
+Full documentation, how it works, and usage examples: [github.com/masterlxz/truthid/tree/main/sdk](https://github.com/masterlxz/truthid/tree/main/sdk#readme)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

truthid_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "truthid-sdk"
+version = "0.1.0"
+description = "TruthID passwordless, decentralized authentication SDK for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "masterlxz" },
+]
+keywords = ["authentication", "passwordless", "decentralized", "blockchain", "web3", "auth"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "web3>=6.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/masterlxz/truthid/tree/main/sdk/python#readme"
+Repository = "https://github.com/masterlxz/truthid"
+Issues = "https://github.com/masterlxz/truthid/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["truthid"]

truthid_sdk-0.1.0/truthid/__init__.py

@@ -0,0 +1,11 @@
+from .client import TruthIDClient
+from .types import AuthChallenge, AuthResponse, VerifyAuthResult, SessionInfo, DeviceStatus
+
+__all__ = [
+    "TruthIDClient",
+    "AuthChallenge",
+    "AuthResponse",
+    "VerifyAuthResult",
+    "SessionInfo",
+    "DeviceStatus",
+]

truthid_sdk-0.1.0/truthid/client.py

@@ -0,0 +1,126 @@
+import json
+import time
+import uuid
+from dataclasses import asdict
+from datetime import datetime, timezone
+from typing import Optional
+
+from eth_account import Account
+from eth_account.messages import encode_defunct
+from web3 import Web3
+
+from .contracts import (
+    DEVICE_REGISTRY_ADDRESSES,
+    DEVICE_REGISTRY_ABI,
+    SESSION_REGISTRY_ADDRESSES,
+    SESSION_REGISTRY_ABI,
+)
+from .types import AuthChallenge, AuthResponse, DeviceStatus, SessionInfo, VerifyAuthResult
+
+_RPC_URLS = {
+    "base-sepolia": "https://sepolia.base.org",
+    "base-mainnet": "https://mainnet.base.org",
+}
+
+
+class TruthIDClient:
+    def __init__(self, network: str = "base-mainnet", rpc_url: Optional[str] = None):
+        url = rpc_url or _RPC_URLS[network]
+        self._w3 = Web3(Web3.HTTPProvider(url))
+        self._devices = self._w3.eth.contract(
+            address=Web3.to_checksum_address(DEVICE_REGISTRY_ADDRESSES[network]),
+            abi=DEVICE_REGISTRY_ABI,
+        )
+        self._sessions = self._w3.eth.contract(
+            address=Web3.to_checksum_address(SESSION_REGISTRY_ADDRESSES[network]),
+            abi=SESSION_REGISTRY_ABI,
+        )
+
+    def create_challenge(self, origin: str) -> AuthChallenge:
+        return AuthChallenge(
+            type="challenge",
+            nonce=str(uuid.uuid4()),
+            issuedAt=int(time.time() * 1000),
+            origin=origin,
+        )
+
+    def verify_auth_response(
+        self,
+        challenge: AuthChallenge,
+        response: AuthResponse,
+        ttl_ms: int = 30_000,
+    ) -> VerifyAuthResult:
+        # 1. Usuário recusou
+        if not response.approved:
+            return VerifyAuthResult(valid=False, reason="User rejected the login request")
+
+        # 2. TTL expirado
+        now_ms = int(time.time() * 1000)
+        if now_ms - challenge.issuedAt > ttl_ms:
+            return VerifyAuthResult(valid=False, reason="Challenge expired")
+
+        # 3. Nonce bate com o challenge original
+        if challenge.nonce != response.nonce:
+            return VerifyAuthResult(valid=False, reason="Nonce mismatch")
+
+        # 4. Verificar assinatura
+        # separators=(',', ':') → JSON compacto, igual ao jsonEncode() do Dart e JSON.stringify() do JS
+        message = json.dumps(asdict(challenge), separators=(",", ":"))
+        msg = encode_defunct(text=message)  # adiciona o prefixo Ethereum personal_sign
+        try:
+            signer = Account.recover_message(msg, signature=response.signature)
+        except Exception:
+            return VerifyAuthResult(valid=False, reason="Invalid signature format")
+
+        if signer.lower() != response.deviceAddress.lower():
+            return VerifyAuthResult(valid=False, reason="Signature does not match device address")
+
+        # 5. Device ativo na blockchain
+        checksum_addr = Web3.to_checksum_address(response.deviceAddress)
+        is_active = self._devices.functions.isDeviceActive(checksum_addr).call()
+        if not is_active:
+            return VerifyAuthResult(valid=False, reason="Device is not active or has been revoked")
+
+        # 6. Buscar identityId do device
+        device = self._devices.functions.getDevice(checksum_addr).call()
+
+        return VerifyAuthResult(
+            valid=True,
+            identity_id=device[0],          # identityId (uint256)
+            device_address=response.deviceAddress,
+        )
+
+    def verify_session(self, session_hash: str) -> SessionInfo:
+        hash_bytes = bytes.fromhex(session_hash.removeprefix("0x"))
+
+        session = self._sessions.functions.getSession(hash_bytes).call()
+        if not session[4]:  # exists
+            return SessionInfo(exists=False, revoked=False)
+
+        revoked = self._sessions.functions.isSessionRevoked(hash_bytes).call()
+        created_at = datetime.fromtimestamp(session[2], tz=timezone.utc)  # createdAt (uint256 segundos)
+
+        return SessionInfo(
+            exists=True,
+            revoked=revoked,
+            identity_id=session[0],   # identityId
+            device_pub_key=session[1], # devicePubKey
+            created_at=created_at,
+        )
+
+    def check_device_status(self, device_pub_key: str) -> DeviceStatus:
+        checksum_addr = Web3.to_checksum_address(device_pub_key)
+        device = self._devices.functions.getDevice(checksum_addr).call()
+
+        if not device[5]:  # exists
+            return DeviceStatus(exists=False, active=False)
+
+        added_at = datetime.fromtimestamp(device[3], tz=timezone.utc)  # addedAt
+
+        return DeviceStatus(
+            exists=True,
+            active=not device[4],  # revoked → active é o inverso
+            label=device[2],
+            identity_id=device[0],
+            added_at=added_at,
+        )

truthid_sdk-0.1.0/truthid/contracts.py

@@ -0,0 +1,71 @@
+IDENTITY_REGISTRY_ADDRESSES = {
+    "base-sepolia": "0x35D21c65980cBd2dAE7576e1bf6b8e46C9e180BF",
+    "base-mainnet": "0xbf097EC74d0Cc9b16D3d94EaCa62060d89A63b17",
+}
+
+DEVICE_REGISTRY_ADDRESSES = {
+    "base-sepolia": "0x225c67a98c9D675fE595ae05a2F9249C34d9C60a",
+    "base-mainnet": "0x4A7a307cb6872bde24BAf3E9de2BeC3Ddd03e144",
+}
+DEVICE_REGISTRY_ABI = [
+    {
+        "type": "function",
+        "name": "isDeviceActive",
+        "inputs": [{"name": "devicePubKey", "type": "address"}],
+        "outputs": [{"name": "", "type": "bool"}],
+        "stateMutability": "view",
+    },
+    {
+        "type": "function",
+        "name": "getDevice",
+        "inputs": [{"name": "devicePubKey", "type": "address"}],
+        "outputs": [
+            {
+                "name": "",
+                "type": "tuple",
+                "components": [
+                    {"name": "identityId", "type": "uint256"},
+                    {"name": "pubKey", "type": "address"},
+                    {"name": "label", "type": "string"},
+                    {"name": "addedAt", "type": "uint256"},
+                    {"name": "revoked", "type": "bool"},
+                    {"name": "exists", "type": "bool"},
+                ],
+            }
+        ],
+        "stateMutability": "view",
+    },
+]
+
+SESSION_REGISTRY_ADDRESSES = {
+    "base-sepolia": "0xdeD2Ad865069CA6546172926540D3A3Aa73C1CA6",
+    "base-mainnet": "0x24074587a2aFB3aa5491361BB0a5eBee90797D1B",
+}
+SESSION_REGISTRY_ABI = [
+    {
+        "type": "function",
+        "name": "isSessionRevoked",
+        "inputs": [{"name": "hash", "type": "bytes32"}],
+        "outputs": [{"name": "", "type": "bool"}],
+        "stateMutability": "view",
+    },
+    {
+        "type": "function",
+        "name": "getSession",
+        "inputs": [{"name": "hash", "type": "bytes32"}],
+        "outputs": [
+            {
+                "name": "",
+                "type": "tuple",
+                "components": [
+                    {"name": "identityId", "type": "uint256"},
+                    {"name": "devicePubKey", "type": "address"},
+                    {"name": "createdAt", "type": "uint256"},
+                    {"name": "revoked", "type": "bool"},
+                    {"name": "exists", "type": "bool"},
+                ],
+            }
+        ],
+        "stateMutability": "view",
+    },
+]

truthid_sdk-0.1.0/truthid/types.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+
+# Campos em camelCase: mapeiam diretamente para o protocolo JSON do mobile
+@dataclass
+class AuthChallenge:
+    type: str
+    nonce: str
+    issuedAt: int  # timestamp Unix em ms
+    origin: str
+
+
+@dataclass
+class AuthResponse:
+    approved: bool
+    nonce: str
+    signature: str      # assinatura secp256k1 em hex ("0x...")
+    deviceAddress: str  # endereço Ethereum da chave do device
+
+
+@dataclass
+class VerifyAuthResult:
+    valid: bool
+    identity_id: Optional[int] = None
+    device_address: Optional[str] = None
+    reason: Optional[str] = None
+
+
+@dataclass
+class SessionInfo:
+    exists: bool
+    revoked: bool
+    identity_id: Optional[int] = None
+    device_pub_key: Optional[str] = None
+    created_at: Optional[datetime] = None
+
+
+@dataclass
+class DeviceStatus:
+    exists: bool
+    active: bool
+    label: Optional[str] = None
+    identity_id: Optional[int] = None
+    added_at: Optional[datetime] = None