eidreader-sdk 1.0.0__tar.gz

eidreader_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: eidreader-sdk
+Version: 1.0.0
+Summary: Host-side SDK for the eID Reader P2P protocol. Receives identity document data from a mobile app over an AES-256-GCM encrypted LAN WebSocket connection secured with ECDH P-256 key exchange and SAS MITM protection. Download the app from: https://play.google.com/store/apps/details?id=com.TFAStudios.eidreadermobile
+Author: Tipa Fabian
+License: GPL-3.0-only
+Project-URL: Homepage, https://play.google.com/store/apps/details?id=com.TFAStudios.eidreadermobile
+Keywords: eid,nfc,identity,document,qrcode,websocket,ecdh,encryption,p2p
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: websockets>=10.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: qrcode>=7.4
+Provides-Extra: pil
+Requires-Dist: Pillow>=10.0; extra == "pil"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: Pillow>=10.0; extra == "dev"

eidreader_sdk-1.0.0/eidreader_sdk/__init__.py

@@ -0,0 +1,47 @@
+"""eID Reader SDK — serverless P2P identity data transfer.
+
+Receive identity data scanned by the eID Reader mobile app directly in your
+application — no cloud server, no data storage, no intermediaries.
+
+Quick start::
+
+    from eidreader_sdk import EIDReaderSession
+
+    session = EIDReaderSession()
+    session.on_paired(lambda: print(f"SAS: {session.sas_code}"))
+    session.on_data(lambda data: print(data.personal.full_name))
+    session.start()
+
+    # Render session.qr_code_png in your UI
+    # When the user confirms SAS codes match:
+    session.confirm_sas()
+"""
+
+from .session import EIDReaderSession
+from .types import (
+    DocumentType,
+    EIDData,
+    EIDDocument,
+    EIDError,
+    EIDImage,
+    EIDMeta,
+    EIDMrz,
+    EIDPersonal,
+    Gender,
+    SessionState,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "EIDReaderSession",
+    "EIDData",
+    "EIDMeta",
+    "EIDPersonal",
+    "EIDDocument",
+    "EIDMrz",
+    "EIDImage",
+    "EIDError",
+    "DocumentType",
+    "Gender",
+    "SessionState",
+]

eidreader_sdk-1.0.0/eidreader_sdk/crypto.py

@@ -0,0 +1,110 @@
+"""Cryptographic operations: ECDH, HKDF, AES-256-GCM, SAS."""
+
+from __future__ import annotations
+
+import base64
+import hmac
+import json
+import os
+from typing import Tuple
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric.ec import (
+    ECDH,
+    SECP256R1,
+    EllipticCurvePrivateKey,
+    EllipticCurvePublicKey,
+    generate_private_key,
+)
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.serialization import load_der_public_key
+
+
+def generate_keypair() -> Tuple[EllipticCurvePrivateKey, EllipticCurvePublicKey]:
+    """Generate an ephemeral ECDH P-256 keypair."""
+    privkey = generate_private_key(SECP256R1())
+    return privkey, privkey.public_key()
+
+
+def serialize_pubkey(pubkey: EllipticCurvePublicKey) -> str:
+    """Serialize a public key to base64url-encoded DER (no padding)."""
+    der = pubkey.public_bytes(
+        serialization.Encoding.DER,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return base64.urlsafe_b64encode(der).rstrip(b"=").decode()
+
+
+def deserialize_pubkey(b64: str) -> EllipticCurvePublicKey:
+    """Deserialize a base64url-encoded DER public key."""
+    # Restore padding
+    padding = "=" * (4 - len(b64) % 4) if len(b64) % 4 else ""
+    der = base64.urlsafe_b64decode(b64 + padding)
+    return load_der_public_key(der)
+
+
+def derive_shared_secret(
+    privkey: EllipticCurvePrivateKey,
+    phone_pubkey: EllipticCurvePublicKey,
+) -> bytes:
+    """Perform ECDH to derive the shared secret."""
+    return privkey.exchange(ECDH(), phone_pubkey)
+
+
+def derive_aes_key(shared_secret: bytes, session_id: str) -> bytes:
+    """Derive a 256-bit AES key from the shared secret using HKDF-SHA256.
+
+    Uses session_id as the HKDF salt and "eidreader-v1" as the info string,
+    ensuring each session produces a unique key even from the same shared secret.
+    """
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=session_id.encode("utf-8"),
+        info=b"eidreader-v1",
+    )
+    return hkdf.derive(shared_secret)
+
+
+def compute_sas(shared_secret: bytes, session_id: str) -> str:
+    """Compute the 6-digit Short Authentication String (SAS).
+
+    Both sides independently compute this from the shared secret.
+    A MITM attacker cannot forge it without knowing both private keys.
+
+    Returns a string like "482 931" (two 3-digit groups).
+    """
+    mac = hmac.new(shared_secret, session_id.encode("utf-8"), "sha256").digest()
+    sas_int = int.from_bytes(mac[0:3], "big") % 1_000_000
+    raw = f"{sas_int:06d}"
+    return f"{raw[:3]} {raw[3:]}"
+
+
+def decrypt_payload(aes_key: bytes, payload: dict) -> dict:
+    """Decrypt an AES-256-GCM encrypted DATA message payload.
+
+    The GCM authentication tag is appended to the ciphertext by the phone
+    (tag_included: true), so AESGCM.decrypt() handles tag verification automatically.
+    """
+    nonce = base64.urlsafe_b64decode(payload["nonce"] + "==")
+    ciphertext = base64.urlsafe_b64decode(payload["ciphertext"] + "==")
+    aesgcm = AESGCM(aes_key)
+    plaintext = aesgcm.decrypt(nonce, ciphertext, None)
+    return json.loads(plaintext)
+
+
+def encrypt_payload(aes_key: bytes, plaintext_dict: dict) -> dict:
+    """Encrypt a payload with AES-256-GCM (for testing / phone-side simulation).
+
+    Returns the payload dict suitable for embedding in a DATA message.
+    """
+    nonce = os.urandom(12)
+    aesgcm = AESGCM(aes_key)
+    plaintext = json.dumps(plaintext_dict).encode("utf-8")
+    ciphertext = aesgcm.encrypt(nonce, plaintext, None)  # GCM tag appended
+    return {
+        "nonce": base64.urlsafe_b64encode(nonce).rstrip(b"=").decode(),
+        "ciphertext": base64.urlsafe_b64encode(ciphertext).rstrip(b"=").decode(),
+        "tag_included": True,
+    }

eidreader_sdk-1.0.0/eidreader_sdk/network.py

@@ -0,0 +1,84 @@
+"""Network utilities: LAN IP detection and port selection."""
+
+from __future__ import annotations
+
+import random
+import socket
+
+# Common virtual/container adapter name fragments to filter out
+_VIRTUAL_NAMES = frozenset(
+    {
+        "vethernet",
+        "docker",
+        "vmnet",
+        "utun",
+        "bridge",
+        "loopback",
+        "virtual",
+        "hyperv",
+        "vbox",
+        "npcap",
+        "tailscale",
+        "zerotier",
+    }
+)
+
+
+def get_lan_ip() -> str:
+    """Detect the primary LAN IPv4 address.
+
+    Uses the UDP connect trick: opening a UDP socket to an external address
+    (without sending anything) forces the OS to select the correct outbound
+    interface. Falls back to hostname resolution if that fails.
+
+    Per the spec, loopback (127.x) and link-local (169.254.x) addresses are
+    excluded. On complex machines (multiple NICs, Docker, etc.) the developer
+    should pass ``host=`` to EIDReaderSession instead.
+    """
+    # Primary method: UDP connect trick — no packet actually sent
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+        s.close()
+        if ip and not ip.startswith("127.") and not ip.startswith("169.254."):
+            return ip
+    except Exception:
+        pass
+
+    # Fallback: hostname resolution
+    try:
+        hostname = socket.gethostname()
+        ip = socket.gethostbyname(hostname)
+        if ip and ip != "127.0.0.1" and not ip.startswith("169.254."):
+            return ip
+    except Exception:
+        pass
+
+    return "127.0.0.1"
+
+
+def find_available_port(
+    host: str,
+    min_port: int = 49152,
+    max_port: int = 65535,
+    max_attempts: int = 10,
+) -> int:
+    """Find a random available TCP port in the ephemeral range.
+
+    Attempts up to ``max_attempts`` random ports before raising RuntimeError.
+    """
+    for _ in range(max_attempts):
+        port = random.randint(min_port, max_port)
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host, port))
+            s.close()
+            return port
+        except OSError:
+            continue
+    raise RuntimeError(
+        f"Unable to find an available port after {max_attempts} attempts. "
+        "Check that your firewall allows incoming connections."
+    )

eidreader_sdk-1.0.0/eidreader_sdk/protocol.py

@@ -0,0 +1,52 @@
+"""Protocol constants, message types, and QR URI builder."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class MsgType(str, Enum):
+    HELLO = "HELLO"
+    HELLO_ACK = "HELLO_ACK"
+    CONFIRM = "CONFIRM"
+    CONFIRM_ACK = "CONFIRM_ACK"
+    DATA = "DATA"
+    DATA_ACK = "DATA_ACK"
+    CLOSE = "CLOSE"
+    ERROR = "ERROR"
+
+
+PROTOCOL_VERSION = 1
+PORT_RANGE_MIN = 49152
+PORT_RANGE_MAX = 65535
+DEFAULT_TTL = 180
+
+
+def build_qr_uri(
+    ip: str,
+    port: int,
+    pubkey_b64: str,
+    session_id: str,
+    expires: int,
+) -> str:
+    """Build the eidreader:// URI that gets encoded into the QR code."""
+    return (
+        f"eidreader://pair"
+        f"?ip={ip}"
+        f"&port={port}"
+        f"&pubkey={pubkey_b64}"
+        f"&session={session_id}"
+        f"&expires={expires}"
+        f"&v={PROTOCOL_VERSION}"
+    )
+
+
+def build_message(msg_type: str, session_id: str, seq: int, payload: Any) -> dict:
+    """Build a WebSocket message envelope."""
+    return {
+        "type": msg_type,
+        "session": session_id,
+        "seq": seq,
+        "payload": payload,
+    }

eidreader_sdk-1.0.0/eidreader_sdk/qrcode_gen.py

@@ -0,0 +1,55 @@
+"""QR code PNG generation from a URI string."""
+
+from __future__ import annotations
+
+import io
+
+
+def generate_qr_png(uri: str) -> bytes:
+    """Generate a QR code PNG from the given URI string.
+
+    Returns raw PNG bytes. Requires the ``qrcode`` package.
+    Install with: ``pip install 'qrcode[pil]'`` for best results,
+    or ``pip install qrcode`` for the pure-Python PNG backend.
+    """
+    try:
+        import qrcode  # type: ignore[import]
+    except ImportError as exc:
+        raise ImportError(
+            "The 'qrcode' package is required for QR code generation. "
+            "Install it with: pip install 'qrcode[pil]'"
+        ) from exc
+
+    qr = qrcode.QRCode(
+        version=None,  # auto-size to fit content
+        error_correction=qrcode.constants.ERROR_CORRECT_M,
+        box_size=10,
+        border=4,
+    )
+    qr.add_data(uri)
+    qr.make(fit=True)
+
+    # Prefer PIL/Pillow for higher-quality PNG output
+    try:
+        from PIL import Image  # type: ignore[import]  # noqa: F401
+
+        img = qr.make_image(fill_color="black", back_color="white")
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return buf.getvalue()
+    except ImportError:
+        pass
+
+    # Fall back to the pure-Python PNG writer bundled with qrcode
+    try:
+        from qrcode.image.pure import PyPNGImage  # type: ignore[import]
+
+        img = qr.make_image(image_factory=PyPNGImage)
+        buf = io.BytesIO()
+        img.save(buf)
+        return buf.getvalue()
+    except ImportError as exc:
+        raise ImportError(
+            "Could not generate QR code PNG. "
+            "Install Pillow: pip install Pillow"
+        ) from exc

eidreader_sdk-1.0.0/eidreader_sdk/session.py

@@ -0,0 +1,644 @@
+"""EIDReaderSession — the main public class of the eID Reader SDK."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+import time
+import uuid
+from typing import Callable, Optional
+
+try:
+    import websockets
+    import websockets.exceptions
+    from websockets.server import WebSocketServerProtocol, serve as ws_serve
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "The 'websockets' package is required. Install it with: pip install websockets"
+    ) from exc
+
+from .crypto import (
+    compute_sas,
+    decrypt_payload,
+    derive_aes_key,
+    derive_shared_secret,
+    deserialize_pubkey,
+    generate_keypair,
+    serialize_pubkey,
+)
+from .network import find_available_port, get_lan_ip
+from .protocol import (
+    DEFAULT_TTL,
+    PORT_RANGE_MAX,
+    PORT_RANGE_MIN,
+    MsgType,
+    build_message,
+    build_qr_uri,
+)
+from .qrcode_gen import generate_qr_png
+from .types import EIDData, EIDError, SessionState
+
+logger = logging.getLogger(__name__)
+
+
+class EIDReaderSession:
+    """A single pairing session between the host application and the eID Reader app.
+
+    Usage (synchronous, callback-based)::
+
+        session = EIDReaderSession()
+        session.on_paired(lambda: print(f"SAS: {session.sas_code}"))
+        session.on_data(lambda data: print(data.personal.full_name))
+        session.on_expired(lambda: print("Expired — generate a new QR."))
+        session.on_error(lambda err: print(f"Error: {err}"))
+
+        session.start()
+        display_qr(session.qr_code_png)
+
+        # Later, when user confirms SAS codes match:
+        session.confirm_sas()
+
+    Usage (async)::
+
+        async def main():
+            session = EIDReaderSession()
+            session.on_data(lambda data: print(data.personal.full_name))
+            await session.start_async()
+            display_qr(session.qr_code_base64)
+            data = await session.wait_for_data()
+
+    See EIDReaderSession constructor for configuration options.
+    """
+
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        ttl: int = DEFAULT_TTL,
+        require_sas: bool = True,
+    ) -> None:
+        """Create a new session.
+
+        Args:
+            host: Override the auto-detected LAN IP. Useful on multi-NIC machines
+                  or in Docker/VM environments.
+            port: Override the random port. Must be in range 49152–65535.
+            ttl:  Session lifetime in seconds (default 180). After expiry the QR
+                  becomes invalid and a new session must be created.
+            require_sas: If True (default), the host waits for both the phone's
+                  CONFIRM and developer's confirm_sas() before sending CONFIRM_ACK.
+                  Set to False only in automated test scenarios.
+        """
+        self._host_override = host
+        self._port_override = port
+        self._ttl = ttl
+        self._require_sas = require_sas
+
+        # Session identity
+        self._session_id: Optional[str] = None
+        self._host_ip: Optional[str] = None
+        self._port_num: Optional[int] = None
+        self._expires: Optional[int] = None
+
+        # State machine
+        self._state = SessionState.IDLE
+
+        # Cryptographic material — held only in memory, cleared after session
+        self._privkey = None
+        self._shared_secret: Optional[bytes] = None
+        self._aes_key: Optional[bytes] = None
+
+        # UI data
+        self._qr_png: Optional[bytes] = None
+        self._sas_code: Optional[str] = None
+
+        # Callbacks
+        self._cb_paired: Optional[Callable] = None
+        self._cb_data: Optional[Callable] = None
+        self._cb_expired: Optional[Callable] = None
+        self._cb_error: Optional[Callable] = None
+        self._cb_ready: Optional[Callable] = None
+
+        # Async primitives — created in the correct event loop (see _init_async_primitives)
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._sas_confirmed_event: Optional[asyncio.Event] = None
+        self._phone_confirmed_event: Optional[asyncio.Event] = None
+        self._data_event: Optional[asyncio.Event] = None
+        self._server_task: Optional[asyncio.Task] = None
+
+        # WebSocket references
+        self._server = None
+        self._ws: Optional[WebSocketServerProtocol] = None
+
+        # Received data
+        self._eid_data: Optional[EIDData] = None
+
+        # Sequence counter for outbound messages
+        self._seq_out: int = 0
+        # Last received inbound sequence number
+        self._seq_in: int = 0
+
+        # Threading primitives for sync start()
+        self._ready_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    # ---------------------------------------------------------------------------
+    # Properties
+    # ---------------------------------------------------------------------------
+
+    @property
+    def id(self) -> Optional[str]:
+        """The session UUID (available after start())."""
+        return self._session_id
+
+    @property
+    def state(self) -> SessionState:
+        """Current session state."""
+        return self._state
+
+    @property
+    def qr_code_png(self) -> Optional[bytes]:
+        """Raw PNG bytes of the QR code. Available after start()."""
+        return self._qr_png
+
+    @property
+    def qr_code_base64(self) -> Optional[str]:
+        """Base64-encoded PNG of the QR code. Available after start()."""
+        if self._qr_png:
+            import base64
+            return base64.b64encode(self._qr_png).decode()
+        return None
+
+    @property
+    def sas_code(self) -> Optional[str]:
+        """6-digit SAS code (e.g. "482 931"). Available after the phone connects."""
+        return self._sas_code
+
+    # ---------------------------------------------------------------------------
+    # Callback registration (fluent interface)
+    # ---------------------------------------------------------------------------
+
+    def on_paired(self, callback: Callable[[], None]) -> "EIDReaderSession":
+        """Register a callback fired when the phone connects and SAS is ready."""
+        self._cb_paired = callback
+        return self
+
+    def on_data(self, callback: Callable[[EIDData], None]) -> "EIDReaderSession":
+        """Register a callback fired when eID data is received and decrypted."""
+        self._cb_data = callback
+        return self
+
+    def on_expired(self, callback: Callable[[], None]) -> "EIDReaderSession":
+        """Register a callback fired when the session TTL expires."""
+        self._cb_expired = callback
+        return self
+
+    def on_error(self, callback: Callable[[EIDError], None]) -> "EIDReaderSession":
+        """Register a callback fired on any protocol or crypto error."""
+        self._cb_error = callback
+        return self
+
+    def on_ready(self, callback: Callable[[], None]) -> "EIDReaderSession":
+        """Register a callback fired when the server is listening and QR is ready."""
+        self._cb_ready = callback
+        return self
+
+    # ---------------------------------------------------------------------------
+    # Public API
+    # ---------------------------------------------------------------------------
+
+    def start(self) -> "EIDReaderSession":
+        """Start the session in a background daemon thread (non-blocking).
+
+        Blocks until the WebSocket server is listening and the QR code is ready
+        (or raises RuntimeError on timeout). The calling thread is then free to
+        render the QR code and wait for callbacks.
+
+        Returns:
+            self, for method chaining.
+        """
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._thread_main, daemon=True)
+        self._thread.start()
+        if not self._ready_event.wait(timeout=15):
+            raise RuntimeError(
+                "EIDReaderSession failed to start within 15 seconds. "
+                "Check that the host IP is reachable and the port is not blocked."
+            )
+        return self
+
+    async def start_async(self) -> "EIDReaderSession":
+        """Start the session within the current asyncio event loop (non-blocking).
+
+        Waits until the WebSocket server is listening and the QR code is ready,
+        then returns. The server continues running as a background task.
+
+        Returns:
+            self, for method chaining.
+        """
+        self._loop = asyncio.get_running_loop()
+        self._init_async_primitives()
+
+        ready_future: asyncio.Future = self._loop.create_future()
+        self._server_task = asyncio.create_task(self._async_main(ready_future))
+        await ready_future
+        return self
+
+    async def wait_for_data(self) -> Optional[EIDData]:
+        """Wait (async) until eID data is received.
+
+        Must be called after start_async(). Returns the EIDData object,
+        or None if the session expired/errored before data arrived.
+        """
+        if self._data_event:
+            await self._data_event.wait()
+        return self._eid_data
+
+    def confirm_sas(self) -> None:
+        """Confirm that the SAS codes match on the host side.
+
+        Call this after your user verbally or visually confirms that the 6-digit
+        code displayed in your app matches the code on the phone. This sends
+        CONFIRM_ACK to the phone and transitions the session to active data
+        transfer.
+
+        Thread-safe — can be called from any thread.
+        """
+        if self._loop and self._sas_confirmed_event:
+            self._loop.call_soon_threadsafe(self._sas_confirmed_event.set)
+
+    def close(self) -> None:
+        """Gracefully close the session.
+
+        Sends a CLOSE message to the phone, stops the WebSocket server, and
+        clears all cryptographic material from memory. Thread-safe.
+        """
+        if self._loop and not self._loop.is_closed():
+            asyncio.run_coroutine_threadsafe(self._async_close(), self._loop)
+
+    # ---------------------------------------------------------------------------
+    # Internal — threading entry point
+    # ---------------------------------------------------------------------------
+
+    def _thread_main(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._init_async_primitives()
+        try:
+            self._loop.run_until_complete(self._thread_async_main())
+        except Exception as exc:
+            logger.debug("Session loop exited with exception: %s", exc)
+        finally:
+            self._loop.close()
+
+    async def _thread_async_main(self) -> None:
+        await self._setup()
+        # Signal to start() that the server is ready
+        self._ready_event.set()
+        if self._cb_ready:
+            self._cb_ready()
+        await self._run_server_with_ttl()
+
+    # ---------------------------------------------------------------------------
+    # Internal — async entry point (used by start_async)
+    # ---------------------------------------------------------------------------
+
+    async def _async_main(self, ready_future: asyncio.Future) -> None:
+        await self._setup()
+        if not ready_future.done():
+            ready_future.set_result(True)
+        if self._cb_ready:
+            self._cb_ready()
+        await self._run_server_with_ttl()
+
+    # ---------------------------------------------------------------------------
+    # Internal — session setup (keypair, QR, network)
+    # ---------------------------------------------------------------------------
+
+    def _init_async_primitives(self) -> None:
+        self._sas_confirmed_event = asyncio.Event()
+        self._phone_confirmed_event = asyncio.Event()
+        self._data_event = asyncio.Event()
+
+    async def _setup(self) -> None:
+        # 1. Generate session UUID
+        self._session_id = str(uuid.uuid4())
+        self._seq_out = 0
+        self._seq_in = 0
+
+        # 2. Generate ephemeral ECDH P-256 keypair
+        self._privkey, pubkey = generate_keypair()
+        pubkey_b64 = serialize_pubkey(pubkey)
+
+        # 3. Detect/validate LAN IP
+        self._host_ip = self._host_override or get_lan_ip()
+
+        # 4. Pick an available port
+        self._port_num = self._port_override or find_available_port(
+            self._host_ip, PORT_RANGE_MIN, PORT_RANGE_MAX
+        )
+
+        # 5. Compute session expiry
+        self._expires = int(time.time()) + self._ttl
+
+        # 6. Build QR URI and generate PNG
+        uri = build_qr_uri(
+            self._host_ip,
+            self._port_num,
+            pubkey_b64,
+            self._session_id,
+            self._expires,
+        )
+        self._qr_png = generate_qr_png(uri)
+
+        self._state = SessionState.LISTENING
+        logger.debug(
+            "Session %s listening on %s:%s (TTL %ss)",
+            self._session_id,
+            self._host_ip,
+            self._port_num,
+            self._ttl,
+        )
+
+    # ---------------------------------------------------------------------------
+    # Internal — WebSocket server
+    # ---------------------------------------------------------------------------
+
+    async def _run_server_with_ttl(self) -> None:
+        try:
+            async with ws_serve(
+                self._handle_connection,
+                self._host_ip,
+                self._port_num,
+                ping_interval=None,
+                ping_timeout=None,
+            ) as server:
+                self._server = server
+                try:
+                    await asyncio.wait_for(self._wait_until_done(), timeout=self._ttl)
+                except asyncio.TimeoutError:
+                    await self._handle_expiry()
+        except OSError as exc:
+            err = EIDError(EIDError.E_BIND_FAILED, str(exc))
+            self._state = SessionState.ERROR
+            logger.error("Failed to bind WebSocket server: %s", exc)
+            if self._cb_error:
+                self._cb_error(err)
+        finally:
+            self._clear_keys()
+
+    async def _wait_until_done(self) -> None:
+        terminal = {SessionState.COMPLETE, SessionState.EXPIRED, SessionState.ERROR}
+        while self._state not in terminal:
+            await asyncio.sleep(0.1)
+
+    async def _handle_expiry(self) -> None:
+        if self._state in {SessionState.COMPLETE, SessionState.ERROR}:
+            return  # already finished normally
+        self._state = SessionState.EXPIRED
+        if self._ws:
+            try:
+                msg = build_message(
+                    MsgType.ERROR,
+                    self._session_id,
+                    self._next_seq_out(),
+                    {"code": EIDError.E_EXPIRED, "message": "Session has expired"},
+                )
+                await self._ws.send(json.dumps(msg))
+                await self._ws.close()
+            except Exception:
+                pass
+        self._clear_keys()
+        if self._cb_expired:
+            self._cb_expired()
+        if self._data_event:
+            self._data_event.set()  # unblock wait_for_data()
+
+    # ---------------------------------------------------------------------------
+    # Internal — WebSocket connection handler
+    # ---------------------------------------------------------------------------
+
+    async def _handle_connection(self, ws: WebSocketServerProtocol) -> None:
+        # Only accept one connection per session
+        if self._ws is not None:
+            await ws.close(1008, "Session already in use")
+            return
+
+        self._ws = ws
+        logger.debug("Connection from %s", ws.remote_address)
+
+        try:
+            async for raw in ws:
+                if isinstance(raw, bytes):
+                    raw = raw.decode("utf-8")
+                await self._dispatch(ws, raw)
+                if self._state in {
+                    SessionState.COMPLETE,
+                    SessionState.EXPIRED,
+                    SessionState.ERROR,
+                }:
+                    break
+        except websockets.exceptions.ConnectionClosed:
+            logger.debug("Connection closed by remote")
+        except Exception as exc:
+            logger.exception("Unexpected error in connection handler: %s", exc)
+            err = EIDError("E_INTERNAL", str(exc))
+            self._state = SessionState.ERROR
+            if self._cb_error:
+                self._cb_error(err)
+        finally:
+            self._ws = None
+
+    async def _dispatch(self, ws: WebSocketServerProtocol, raw: str) -> None:
+        try:
+            msg = json.loads(raw)
+        except json.JSONDecodeError:
+            await self._send_error(ws, EIDError.E_UNKNOWN_TYPE, "Invalid JSON")
+            return
+
+        msg_type = msg.get("type")
+        session = msg.get("session")
+        seq = msg.get("seq")
+        payload = msg.get("payload") or {}
+
+        # Validate session ID
+        if session != self._session_id:
+            await self._send_error(ws, EIDError.E_SESSION_MISMATCH, "Session ID mismatch")
+            await ws.close()
+            return
+
+        # Validate sequence number
+        if seq is not None:
+            expected = self._seq_in + 1
+            if seq != expected:
+                await self._send_error(
+                    ws,
+                    EIDError.E_SEQUENCE_ERROR,
+                    f"Expected seq {expected}, got {seq}",
+                )
+                await ws.close()
+                return
+            self._seq_in = seq
+
+        handlers = {
+            MsgType.HELLO: self._on_hello,
+            MsgType.CONFIRM: self._on_confirm,
+            MsgType.DATA: self._on_data_msg,
+            MsgType.CLOSE: self._on_close,
+            MsgType.ERROR: self._on_error_msg,
+        }
+
+        handler = handlers.get(msg_type)
+        if handler:
+            await handler(ws, payload)
+        else:
+            await self._send_error(ws, EIDError.E_UNKNOWN_TYPE, f"Unknown type: {msg_type}")
+
+    # ---------------------------------------------------------------------------
+    # Internal — message handlers
+    # ---------------------------------------------------------------------------
+
+    async def _on_hello(self, ws: WebSocketServerProtocol, payload: dict) -> None:
+        self._state = SessionState.HANDSHAKING
+
+        phone_pubkey_b64 = payload.get("pubkey")
+        if not phone_pubkey_b64:
+            await self._send_error(ws, EIDError.E_CRYPTO_FAILED, "Missing pubkey in HELLO")
+            return
+
+        try:
+            phone_pubkey = deserialize_pubkey(phone_pubkey_b64)
+            self._shared_secret = derive_shared_secret(self._privkey, phone_pubkey)
+            self._aes_key = derive_aes_key(self._shared_secret, self._session_id)
+            self._sas_code = compute_sas(self._shared_secret, self._session_id)
+        except Exception as exc:
+            await self._send_error(ws, EIDError.E_CRYPTO_FAILED, str(exc))
+            return
+
+        # Send HELLO_ACK — both sides now compute and display SAS
+        ack = build_message(MsgType.HELLO_ACK, self._session_id, self._next_seq_out(), {})
+        await ws.send(json.dumps(ack))
+
+        self._state = SessionState.PAIRED
+        logger.debug("SAS code: %s", self._sas_code)
+
+        if self._cb_paired:
+            self._cb_paired()
+
+    async def _on_confirm(self, ws: WebSocketServerProtocol, payload: dict) -> None:
+        # Phone user has confirmed the SAS code
+        self._phone_confirmed_event.set()
+
+        if self._require_sas:
+            # Wait for the developer to also call confirm_sas()
+            await self._sas_confirmed_event.wait()
+
+        # Check if the session timed out while we were waiting
+        if self._state == SessionState.EXPIRED:
+            return
+
+        ack = build_message(MsgType.CONFIRM_ACK, self._session_id, self._next_seq_out(), {})
+        await ws.send(json.dumps(ack))
+        logger.debug("SAS confirmed on both sides — session active")
+
+    async def _on_data_msg(self, ws: WebSocketServerProtocol, payload: dict) -> None:
+        self._state = SessionState.TRANSFERRING
+
+        try:
+            plaintext = decrypt_payload(self._aes_key, payload)
+            eid_data = EIDData.from_dict(plaintext)
+        except Exception as exc:
+            await self._send_error(ws, EIDError.E_CRYPTO_FAILED, f"Decryption failed: {exc}")
+            return
+
+        # Acknowledge receipt
+        ack = build_message(MsgType.DATA_ACK, self._session_id, self._next_seq_out(), {})
+        await ws.send(json.dumps(ack))
+
+        self._eid_data = eid_data
+        self._state = SessionState.COMPLETE
+        self._clear_keys()
+
+        if self._data_event:
+            self._data_event.set()
+
+        if self._cb_data:
+            self._cb_data(eid_data)
+
+        logger.debug("eID data received and decrypted successfully")
+
+    async def _on_close(self, ws: WebSocketServerProtocol, payload: dict) -> None:
+        self._state = SessionState.COMPLETE
+        self._clear_keys()
+        if self._data_event:
+            self._data_event.set()
+        await ws.close()
+
+    async def _on_error_msg(self, ws: WebSocketServerProtocol, payload: dict) -> None:
+        code = payload.get("code", "E_UNKNOWN")
+        message = payload.get("message", "Phone reported an error")
+        err = EIDError(code, message)
+        self._state = SessionState.ERROR
+        self._clear_keys()
+        if self._data_event:
+            self._data_event.set()
+        if self._cb_error:
+            self._cb_error(err)
+        await ws.close()
+
+    # ---------------------------------------------------------------------------
+    # Internal — helpers
+    # ---------------------------------------------------------------------------
+
+    async def _send_error(self, ws: WebSocketServerProtocol, code: str, message: str) -> None:
+        msg = build_message(
+            MsgType.ERROR,
+            self._session_id or "",
+            self._next_seq_out(),
+            {"code": code, "message": message},
+        )
+        try:
+            await ws.send(json.dumps(msg))
+        except Exception:
+            pass
+        self._state = SessionState.ERROR
+        if self._data_event:
+            self._data_event.set()
+        err = EIDError(code, message)
+        if self._cb_error:
+            self._cb_error(err)
+
+    async def _async_close(self) -> None:
+        if self._ws:
+            try:
+                msg = build_message(
+                    MsgType.CLOSE,
+                    self._session_id or "",
+                    self._next_seq_out(),
+                    {},
+                )
+                await self._ws.send(json.dumps(msg))
+                await self._ws.close()
+            except Exception:
+                pass
+        if self._server:
+            self._server.close()
+            try:
+                await asyncio.wait_for(self._server.wait_closed(), timeout=5.0)
+            except asyncio.TimeoutError:
+                pass
+        self._clear_keys()
+        self._state = SessionState.COMPLETE
+        if self._data_event:
+            self._data_event.set()
+
+    def _clear_keys(self) -> None:
+        """Remove all cryptographic material from memory."""
+        self._privkey = None
+        self._shared_secret = None
+        self._aes_key = None
+
+    def _next_seq_out(self) -> int:
+        self._seq_out += 1
+        return self._seq_out

eidreader_sdk-1.0.0/eidreader_sdk/types.py

@@ -0,0 +1,181 @@
+"""Data models for eID Reader SDK."""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from enum import Enum
+from typing import Optional
+
+
+class DocumentType(str, Enum):
+    PASSPORT = "PASSPORT"
+    ID_CARD = "ID_CARD"
+    RESIDENCE_PERMIT = "RESIDENCE_PERMIT"
+
+
+class Gender(str, Enum):
+    MALE = "M"
+    FEMALE = "F"
+    OTHER = "X"
+
+
+class SessionState(str, Enum):
+    IDLE = "IDLE"
+    LISTENING = "LISTENING"
+    HANDSHAKING = "HANDSHAKING"
+    PAIRED = "PAIRED"
+    TRANSFERRING = "TRANSFERRING"
+    COMPLETE = "COMPLETE"
+    EXPIRED = "EXPIRED"
+    ERROR = "ERROR"
+
+
+@dataclass
+class EIDMeta:
+    document_type: Optional[DocumentType] = None
+    issuing_country: Optional[str] = None
+    scan_timestamp: Optional[datetime] = None
+    sdk_version: Optional[str] = None
+
+
+@dataclass
+class EIDPersonal:
+    surname: Optional[str] = None
+    given_names: Optional[str] = None
+    date_of_birth: Optional[date] = None
+    gender: Optional[Gender] = None
+    nationality: Optional[str] = None
+    personal_number: Optional[str] = None
+    place_of_birth: Optional[str] = None
+
+    @property
+    def full_name(self) -> Optional[str]:
+        parts = [p for p in [self.given_names, self.surname] if p]
+        return " ".join(parts) if parts else None
+
+
+@dataclass
+class EIDDocument:
+    number: Optional[str] = None
+    expiry_date: Optional[date] = None
+    issue_date: Optional[date] = None
+    issuing_authority: Optional[str] = None
+    issuing_country: Optional[str] = None
+
+
+@dataclass
+class EIDMrz:
+    line1: Optional[str] = None
+    line2: Optional[str] = None
+    is_valid: Optional[bool] = None
+
+
+@dataclass
+class EIDImage:
+    face_photo: Optional[bytes] = None
+    signature: Optional[bytes] = None
+
+
+@dataclass
+class EIDData:
+    meta: EIDMeta = field(default_factory=EIDMeta)
+    personal: EIDPersonal = field(default_factory=EIDPersonal)
+    document: EIDDocument = field(default_factory=EIDDocument)
+    mrz: EIDMrz = field(default_factory=EIDMrz)
+    image: EIDImage = field(default_factory=EIDImage)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "EIDData":
+        obj = cls()
+
+        meta_d = data.get("meta") or {}
+        doc_type = meta_d.get("document_type")
+        obj.meta.document_type = DocumentType(doc_type) if doc_type else None
+        obj.meta.issuing_country = meta_d.get("issuing_country")
+        ts = meta_d.get("scan_timestamp")
+        if ts:
+            try:
+                obj.meta.scan_timestamp = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+            except (ValueError, AttributeError):
+                pass
+        obj.meta.sdk_version = meta_d.get("sdk_version")
+
+        pers_d = data.get("personal") or {}
+        obj.personal.surname = pers_d.get("surname")
+        obj.personal.given_names = pers_d.get("given_names")
+        dob = pers_d.get("date_of_birth")
+        if dob:
+            try:
+                obj.personal.date_of_birth = date.fromisoformat(dob)
+            except (ValueError, AttributeError):
+                pass
+        gender = pers_d.get("gender")
+        # Accept both enum values and common string representations
+        gender_map = {
+            "M": Gender.MALE,
+            "F": Gender.FEMALE,
+            "X": Gender.OTHER,
+            "MALE": Gender.MALE,
+            "FEMALE": Gender.FEMALE,
+            "OTHER": Gender.OTHER,
+        }
+        if gender:
+            try:
+                obj.personal.gender = Gender(gender)
+            except ValueError:
+                obj.personal.gender = gender_map.get(str(gender).upper(), None)
+        else:
+            obj.personal.gender = None
+        obj.personal.nationality = pers_d.get("nationality")
+        obj.personal.personal_number = pers_d.get("personal_number")
+        obj.personal.place_of_birth = pers_d.get("place_of_birth")
+
+        doc_d = data.get("document") or {}
+        obj.document.number = doc_d.get("number")
+        for attr, key in [("expiry_date", "expiry_date"), ("issue_date", "issue_date")]:
+            val = doc_d.get(key)
+            if val:
+                try:
+                    setattr(obj.document, attr, date.fromisoformat(val))
+                except (ValueError, AttributeError):
+                    pass
+        obj.document.issuing_authority = doc_d.get("issuing_authority")
+        obj.document.issuing_country = doc_d.get("issuing_country")
+
+        mrz_d = data.get("mrz") or {}
+        obj.mrz.line1 = mrz_d.get("line1")
+        obj.mrz.line2 = mrz_d.get("line2")
+        obj.mrz.is_valid = mrz_d.get("valid")
+
+        img_d = data.get("image") or {}
+        for attr, key in [("face_photo", "face_photo"), ("signature", "signature")]:
+            val = img_d.get(key)
+            if val:
+                try:
+                    setattr(obj.image, attr, base64.b64decode(val))
+                except Exception:
+                    pass
+
+        return obj
+
+
+class EIDError(Exception):
+    # Standard error codes
+    E_SESSION_MISMATCH = "E_SESSION_MISMATCH"
+    E_SEQUENCE_ERROR = "E_SEQUENCE_ERROR"
+    E_EXPIRED = "E_EXPIRED"
+    E_CRYPTO_FAILED = "E_CRYPTO_FAILED"
+    E_SAS_REJECTED = "E_SAS_REJECTED"
+    E_PROTOCOL_VERSION = "E_PROTOCOL_VERSION"
+    E_UNKNOWN_TYPE = "E_UNKNOWN_TYPE"
+    E_BIND_FAILED = "E_BIND_FAILED"
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"{code}: {message}")
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"

eidreader_sdk-1.0.0/eidreader_sdk.egg-info/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: eidreader-sdk
+Version: 1.0.0
+Summary: Host-side SDK for the eID Reader P2P protocol. Receives identity document data from a mobile app over an AES-256-GCM encrypted LAN WebSocket connection secured with ECDH P-256 key exchange and SAS MITM protection. Download the app from: https://play.google.com/store/apps/details?id=com.TFAStudios.eidreadermobile
+Author: Tipa Fabian
+License: GPL-3.0-only
+Project-URL: Homepage, https://play.google.com/store/apps/details?id=com.TFAStudios.eidreadermobile
+Keywords: eid,nfc,identity,document,qrcode,websocket,ecdh,encryption,p2p
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: websockets>=10.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: qrcode>=7.4
+Provides-Extra: pil
+Requires-Dist: Pillow>=10.0; extra == "pil"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: Pillow>=10.0; extra == "dev"

eidreader_sdk-1.0.0/eidreader_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+pyproject.toml
+eidreader_sdk/__init__.py
+eidreader_sdk/crypto.py
+eidreader_sdk/network.py
+eidreader_sdk/protocol.py
+eidreader_sdk/qrcode_gen.py
+eidreader_sdk/session.py
+eidreader_sdk/types.py
+eidreader_sdk.egg-info/PKG-INFO
+eidreader_sdk.egg-info/SOURCES.txt
+eidreader_sdk.egg-info/dependency_links.txt
+eidreader_sdk.egg-info/requires.txt
+eidreader_sdk.egg-info/top_level.txt

eidreader_sdk-1.0.0/eidreader_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

eidreader_sdk-1.0.0/eidreader_sdk.egg-info/requires.txt

@@ -0,0 +1,11 @@
+websockets>=10.0
+cryptography>=41.0
+qrcode>=7.4
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+Pillow>=10.0
+
+[pil]
+Pillow>=10.0

eidreader_sdk-1.0.0/eidreader_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+eidreader_sdk

eidreader_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eidreader-sdk"
+version = "1.0.0"
+description = "Host-side SDK for the eID Reader P2P protocol. Receives identity document data from a mobile app over an AES-256-GCM encrypted LAN WebSocket connection secured with ECDH P-256 key exchange and SAS MITM protection. Download the app from: https://play.google.com/store/apps/details?id=com.TFAStudios.eidreadermobile"
+requires-python = ">=3.8"
+license = { text = "GPL-3.0-only" }
+authors = [{ name = "Tipa Fabian" }]
+keywords = ["eid", "nfc", "identity", "document", "qrcode", "websocket", "ecdh", "encryption", "p2p"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "websockets>=10.0",
+    "cryptography>=41.0",
+    "qrcode>=7.4",
+]
+
+[project.optional-dependencies]
+pil = ["Pillow>=10.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "Pillow>=10.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["eidreader_sdk*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[project.urls]
+Homepage = "https://play.google.com/store/apps/details?id=com.TFAStudios.eidreadermobile"

eidreader_sdk-1.0.0/setup.cfg

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