pykorail 0.1.0__py3-none-any.whl

pykorail/__init__.py

@@ -0,0 +1,124 @@
+"""pykorail — 코레일(KTX) 스마트 예매 비공식 Python 클라이언트.
+
+::
+
+    from pykorail import AdultPassenger, ChildPassenger, Korail
+    from pykorail.device import profile_by_id, random_profile
+
+    profile = profile_by_id(saved_id) or random_profile()
+    with Korail.logged_in("me@example.com", "password", device_profile=profile) as korail:
+        trains = korail.trains.search("서울", "부산", passengers=[AdultPassenger(2), ChildPassenger(1)])
+        reservation = korail.reservations.create(trains[0])
+
+API 는 리소스별로 나뉘어 있습니다 — ``korail.stations`` / ``korail.trains`` /
+``korail.reservations`` / ``korail.tickets``. 로그인·로그아웃·연결 정리만
+:class:`~pykorail.client.Korail` 본체에 있습니다.
+
+하위 모듈:
+    - :mod:`pykorail.device` — 기기 프로파일 카탈로그 (주입용)
+    - :mod:`pykorail.exceptions` — 예외 계층
+    - :mod:`pykorail.models` — 불변 응답 모델
+    - :mod:`pykorail.options` — 조회·예매 옵션 코드
+    - :mod:`pykorail.resources` — 리소스 구현
+    - :mod:`pykorail.auth` — DynaPath 서명, NetFunnel 대기열
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+from pykorail import _compat as _compat  # 최소 파이썬 버전 강제 — 다른 임포트보다 먼저
+from pykorail.auth import NetFunnelHelper
+from pykorail.client import Korail
+from pykorail.device import DeviceProfile, DeviceProfileLike, profile_by_id, random_profile
+from pykorail.exceptions import (
+    KorailError,
+    LoginFailedError,
+    NeedToLoginError,
+    NetFunnelError,
+    NoResultsError,
+    PastDepartureError,
+    PykorailError,
+    SoldOutError,
+    StationNotFoundError,
+    TransportError,
+)
+from pykorail.models import (
+    AdultPassenger,
+    Card,
+    ChildPassenger,
+    Disability1To3Passenger,
+    Disability4To6Passenger,
+    Passenger,
+    Reservation,
+    Schedule,
+    Seat,
+    SeniorPassenger,
+    Station,
+    Ticket,
+    ToddlerPassenger,
+    Train,
+)
+from pykorail.options import ReserveOption, ReserveOptionCode, TrainType, TrainTypeCode
+
+
+def _resolve_version() -> str:
+    """설치된 배포 메타데이터에서 버전을 읽습니다.
+
+    버전의 유일한 출처는 **git 태그**입니다 (hatch-vcs). 소스에 숫자를 박아 두면
+    태그와 어긋나므로 여기서 하드코딩하지 않습니다. 빌드 훅이 `_version.py` 를
+    만들어 두므로 설치 후에는 git 없이도 읽힙니다.
+    """
+    try:
+        from pykorail._version import __version__ as built_version
+    except ImportError:
+        pass
+    else:
+        return built_version
+
+    try:
+        return metadata.version("pykorail")
+    except metadata.PackageNotFoundError:
+        # 설치하지 않고 소스 트리에서 바로 임포트한 경우.
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+
+__all__ = [
+    "AdultPassenger",
+    "Card",
+    "ChildPassenger",
+    "DeviceProfile",
+    "DeviceProfileLike",
+    "Disability1To3Passenger",
+    "Disability4To6Passenger",
+    "Korail",
+    "KorailError",
+    "LoginFailedError",
+    "NeedToLoginError",
+    "NetFunnelError",
+    "NetFunnelHelper",
+    "NoResultsError",
+    "Passenger",
+    "PastDepartureError",
+    "PykorailError",
+    "Reservation",
+    "ReserveOption",
+    "ReserveOptionCode",
+    "Schedule",
+    "Seat",
+    "SeniorPassenger",
+    "SoldOutError",
+    "Station",
+    "StationNotFoundError",
+    "Ticket",
+    "ToddlerPassenger",
+    "Train",
+    "TrainType",
+    "TrainTypeCode",
+    "TransportError",
+    "__version__",
+    "profile_by_id",
+    "random_profile",
+]

pykorail/_compat.py

@@ -0,0 +1,19 @@
+"""파이썬 최소 버전 강제.
+
+``requires-python`` 은 패키지 매니저를 통해 설치할 때만 걸립니다. 소스를 그대로
+복사해 오거나 ``PYTHONPATH`` 로 끌어다 쓰는 경우를 대비해 임포트 시점에도 막습니다.
+빈 슬롯 데이터클래스·``X | Y`` 런타임 유니언 등 3.10 문법을 실제로 쓰기 때문에,
+낮은 버전에서는 알아보기 힘든 ``SyntaxError`` 대신 명확한 메시지를 냅니다.
+"""
+
+from __future__ import annotations
+
+import sys
+
+MIN_PYTHON = (3, 10)
+
+if sys.version_info < MIN_PYTHON:  # pragma: no cover - 낮은 버전에서만 실행
+    raise RuntimeError(
+        f"pykorail 은 파이썬 {'.'.join(map(str, MIN_PYTHON))} 이상이 필요합니다 "
+        f"(현재 {'.'.join(map(str, sys.version_info[:3]))})."
+    )

pykorail/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

pykorail/api.py

@@ -0,0 +1,112 @@
+"""요청/응답 계층 — 리소스들이 공유하는 저수준 클라이언트.
+
+:class:`~pykorail.client.Korail` 과 각 리소스가 이 객체 하나를 나눠 씁니다.
+HTTP 왕복·서명·에러 변환처럼 "어느 리소스에서나 똑같은 일"만 담고, 엔드포인트별
+폼 필드는 리소스 쪽에 둡니다.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from pykorail.constants import API_KEY, APP_VERSION, DEVICE
+from pykorail.exceptions import TransportError, error_for_code
+
+if TYPE_CHECKING:
+    from pykorail.auth.signer import RequestSigner
+    from pykorail.transport import HttpSession, Response
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Account:
+    """로그인 세션 상태.
+
+    여러 리소스가 읽고(``mbCrdNo``) 로그인만 쓰기 때문에, 클라이언트와 리소스가
+    같은 인스턴스를 공유합니다.
+    """
+
+    logined: bool = False
+    membership_number: str | None = None
+    name: str | None = None
+    email: str | None = None
+    phone_number: str | None = None
+
+    def clear(self) -> None:
+        self.logined = False
+        self.membership_number = None
+        self.name = None
+        self.email = None
+        self.phone_number = None
+
+
+class ApiClient:
+    """서명·전송·응답 해석을 담당합니다."""
+
+    def __init__(self, session: HttpSession, signer: RequestSigner, verbose: bool = False) -> None:
+        self._session = session
+        self._signer = signer
+        self.verbose = verbose
+        self.account = Account()
+
+    # ------------------------------------------------------------------- 전송
+    def sign(self, url: str) -> tuple[dict[str, str], str | None]:
+        """``url`` 에 필요한 ``(헤더, Sid)``. 서명 대상이 아니면 ``({}, None)``."""
+        return self._signer.sign(url)
+
+    def get(
+        self,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        return self._parse(self._session.get(url, **_kwargs(params=params, headers=headers)))
+
+    def post(
+        self,
+        url: str,
+        *,
+        data: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        return self._parse(self._session.post(url, **_kwargs(data=data, params=params, headers=headers)))
+
+    def close(self) -> None:
+        self._session.close()
+
+    # ------------------------------------------------------------------- 해석
+    def base_payload(self) -> dict[str, Any]:
+        """거의 모든 요청에 실리는 앱 신원 필드."""
+        return {"Device": DEVICE, "Version": APP_VERSION, "Key": API_KEY}
+
+    @staticmethod
+    def check(payload: dict[str, Any]) -> None:
+        """``strResult=FAIL`` 이면 코드에 맞는 예외를 던집니다."""
+        if payload.get("strResult") == "FAIL":
+            raise error_for_code(payload.get("h_msg_cd"), payload.get("h_msg_txt"))
+
+    def _parse(self, response: Response) -> dict[str, Any]:
+        if self.verbose:
+            logger.debug("%s", response.text)
+        try:
+            parsed = json.loads(response.text)
+        except json.JSONDecodeError as exc:
+            raise TransportError(f"코레일 응답을 JSON 으로 읽지 못했습니다: {response.text[:200]!r}") from exc
+        if not isinstance(parsed, dict):
+            raise TransportError(f"코레일 응답이 객체가 아닙니다: {type(parsed).__name__}")
+        return parsed
+
+
+def _kwargs(**candidates: Any) -> dict[str, Any]:
+    """``None`` 인 인자를 빼고 넘깁니다.
+
+    ``post(url)`` 과 ``post(url, data=None)`` 은 라이브러리에 따라 다르게 처리될 수
+    있어(빈 바디 vs 바디 없음), 앱이 보내는 모양을 유지하려면 아예 안 넘겨야 합니다.
+    """
+    return {key: value for key, value in candidates.items() if value is not None}

pykorail/auth/__init__.py

@@ -0,0 +1,9 @@
+"""인증·서명 계층 — DynaPath 토큰, ``Sid``, NetFunnel 대기열."""
+
+from __future__ import annotations
+
+from pykorail.auth.dynapath import DynaPathMasterEngine
+from pykorail.auth.netfunnel import NetFunnelHelper
+from pykorail.auth.signer import RequestSigner
+
+__all__ = ["DynaPathMasterEngine", "NetFunnelHelper", "RequestSigner"]

pykorail/auth/dynapath.py

@@ -0,0 +1,179 @@
+"""DynaPath 요청 서명 (``x-dynapath-m-token``).
+
+코레일 앱이 예매 계열 엔드포인트에 붙이는 무결성 토큰을 재현합니다. 알고리즘은
+앱에서 그대로 옮긴 것이라 **바이트 단위로 같아야** 서버가 받아 줍니다 — 변수
+이름은 읽기 좋게 바꿨지만 연산 순서·상수는 손대지 마세요.
+
+토큰이 광고하는 기기(``os=``·``dm=``)는 User-Agent 가 광고하는 기기와 반드시
+같아야 합니다. :class:`~pykorail.client.Korail` 이 같은 프로파일로 둘 다 채웁니다.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, ClassVar, Final
+
+if TYPE_CHECKING:
+    from pykorail.device import DeviceProfileLike
+
+#: 인코딩 알파벳. 순서가 곧 알고리즘의 일부입니다.
+_TABLE: Final = "3FE9jgRD4KdCyuawklqGJYmvfMn15P7US8XbxeLQtWT6OicBAopINs2Vh0HZrz"
+
+_RADIX: Final = 161  # 청크를 하나의 정수로 접을 때의 진법
+_MODULUS: Final = 30  # 출력 자릿수 진법 (= 커스텀 테이블 길이)
+_CHUNK: Final = 2  # 한 번에 접는 코드포인트 수
+
+
+class DynaPathMasterEngine:
+    """DynaPath 토큰 생성기.
+
+    인스턴스 하나가 "앱 실행 한 번"에 대응합니다 — 생성 시각을 ``it=`` 필드로
+    서명에 담기 때문에, 세션마다 새로 만들지 말고 클라이언트와 수명을 맞추세요.
+    """
+
+    APP_ID: ClassVar[str] = "com.korail.talk"
+    AS_VALUE: ClassVar[str] = "%5B38ff229cb34c7dda8e28220a2d750cce%5D"
+    DEVICE_MODEL: ClassVar[str] = "SM-S928N"
+    OS_VERSION: ClassVar[str] = "13"
+    OS_TYPE: ClassVar[str] = "Android"
+    SDK_VERSION: ClassVar[str] = "v1"
+
+    def __init__(self, device_model: str | None = None, os_version: str | None = None) -> None:
+        self.app_start_ts = str(int(time.time() * 1000))
+        # 기본값을 클래스 상수와 같게 둬 미주입 시 서명이 바이트 단위로 동일합니다.
+        self.device_model = device_model or self.DEVICE_MODEL
+        self.os_version = os_version or self.OS_VERSION
+
+    @classmethod
+    def from_profile(cls, profile: DeviceProfileLike | None) -> DynaPathMasterEngine:
+        """기기 프로파일로 엔진을 만듭니다. ``None`` 이면 클래스 기본값을 씁니다."""
+        if profile is None:
+            return cls()
+        return cls(device_model=profile.model, os_version=profile.android)
+
+    # ------------------------------------------------------------ 인코딩 원시연산
+    @staticmethod
+    def _to_code_units(data: str) -> list[int]:
+        """문자열을 앱 고유의 가변길이 7비트 코드 유닛으로 펼칩니다.
+
+        UTF-8 이 아닙니다 — 연속 바이트가 7비트를 쓰고 선행 바이트의 상위 비트
+        패턴도 다릅니다. 서로게이트(0xD800~0xDFFF)는 앱과 마찬가지로 버립니다.
+        """
+        result: list[int] = []
+        for char in data:
+            cp = ord(char)
+            if cp < 128:
+                result.append(cp)
+            elif cp < 2048:
+                result.append(128 | ((cp >> 7) & 15))
+                result.append(cp & 127)
+            elif cp >= 262144:
+                result.append(160)
+                result.append((cp >> 14) & 127)
+                result.append((cp >> 7) & 127)
+                result.append(cp & 127)
+            elif (63488 & cp) != 55296:
+                result.append(((cp >> 14) & 15) | 144)
+                result.append((cp >> 7) & 127)
+                result.append(cp & 127)
+        return result
+
+    @staticmethod
+    def _derive_key(key_str: str) -> int:
+        """키 문자열을 커스텀 테이블 셔플에 쓸 큰 정수로 접습니다.
+
+        각 문자마다 최상위 세트 비트를 찾아 그 두 배를 진법으로 삼습니다.
+        코드포인트가 0 이면 16 회 탐색이 모두 실패해 진법이 0 이 되고 누산값이
+        초기화되는데, 앱과 동작을 맞추기 위해 그대로 둡니다.
+        """
+        accumulator = 0
+        for char in key_str:
+            cp = ord(char)
+            high_bit = 32768
+            for _ in range(16):
+                if (high_bit & cp) != 0:
+                    break
+                high_bit >>= 1
+            accumulator = (accumulator * (high_bit << 1)) + cp
+        return accumulator
+
+    @staticmethod
+    def _pick_unused_char(base_table: str, position: int, used: str) -> str:
+        """``used`` 에 아직 없는 문자 중 ``position`` 번째를 고릅니다."""
+        seen = 0
+        for char in base_table:
+            if char not in used:
+                if seen == position:
+                    return char
+                seen += 1
+        return " "
+
+    @classmethod
+    def _build_table(cls, seed: int, size: int, base_table: str) -> str:
+        """``seed`` 로 ``base_table`` 에서 길이 ``size`` 의 커스텀 알파벳을 뽑습니다.
+
+        팩토리얼 진법(Lehmer code) 방식이라 같은 seed 는 항상 같은 알파벳을 냅니다.
+        """
+        picked = ""
+        remaining = seed
+        for i in range(size):
+            divisor = size - i
+            picked += cls._pick_unused_char(base_table, remaining % divisor, picked)
+            remaining //= divisor
+        return picked
+
+    @classmethod
+    def _encode(cls, data: str, table: str) -> str:
+        """코드 유닛을 ``_CHUNK`` 개씩 묶어 ``_MODULUS`` 진수 자릿수로 펼칩니다."""
+        units = cls._to_code_units(data)
+        out: list[str] = []
+        digits = [0] * (_CHUNK + 1)
+
+        idx = 0
+        tail = len(units) % _CHUNK
+        body_end = len(units) - tail
+
+        while idx < body_end:
+            value = 0
+            for _ in range(_CHUNK):
+                value = (value * _RADIX) + units[idx]
+                idx += 1
+            for i in range(_CHUNK + 1):
+                digits[i] = value % _MODULUS
+                value //= _MODULUS
+            for i in range(_CHUNK, -1, -1):
+                out.append(table[digits[i]])
+
+        if tail > 0:
+            value = 0
+            for _ in range(tail):
+                value = (value * _RADIX) + units[idx]
+                idx += 1
+            for i in range(tail + 1):
+                digits[i] = value % _MODULUS
+                value //= _MODULUS
+            for i in range(tail, -1, -1):
+                out.append(table[digits[i]])
+
+        return "".join(out)
+
+    # ------------------------------------------------------------------- 공개 API
+    def generate_token(self, device_id: str, ts: int, rand: str) -> str:
+        """``x-dynapath-m-token`` 헤더 값을 만듭니다.
+
+        Args:
+            device_id: 앱이 들고 다니는 기기 식별자.
+            ts: 요청 시각 (epoch 밀리초).
+            rand: 요청마다 새로 뽑는 4자 영대문자·숫자 논스.
+        """
+        payload = (
+            f"ai={self.APP_ID}&di={device_id}&as={self.AS_VALUE}&"
+            f"su=false&dbg=false&emu=false&hk=false&it={self.app_start_ts}&"
+            f"ts={ts}&rt=0&os={self.os_version}&dm={self.device_model}&st={self.OS_TYPE}&sv={self.SDK_VERSION}"
+        )
+
+        dyn_key = f"{self.SDK_VERSION}+{rand}+{ts}"
+        key_part = self._encode(dyn_key, _TABLE)
+        custom_table = self._build_table(self._derive_key(dyn_key), _MODULUS, _TABLE)
+        body_part = self._encode(payload, custom_table)
+        return f"bEeEP{_TABLE[len(key_part)]}{key_part}{body_part}"

pykorail/auth/netfunnel.py

@@ -0,0 +1,140 @@
+"""NetFunnel 대기열 게이트 (``nf.letskorail.com``).
+
+접속 폭주 때 코레일 앞단에 서는 대기열입니다. 통과 티켓(key)을 받아 두면
+잠깐 재사용할 수 있어 캐시합니다.
+
+**클라이언트는 이 모듈을 쓰지 않습니다 — 의도된 것입니다.** 대기열은 코레일 웹
+프런트가 통과하는 관문이고, 이 패키지가 쓰는 스마트 앱 엔드포인트
+(``smart.letskorail.com``)는 대기열 뒤에 있지 않습니다. 명절 예매처럼 앱 경로에도
+대기열이 붙는 상황을 만나면 직접 꺼내 쓸 수 있도록 공개 유틸리티로 남겨 둡니다::
+
+    from pykorail import NetFunnelHelper
+
+    key = NetFunnelHelper().run()  # 통과할 때까지 블로킹
+
+:class:`~pykorail.client.Korail` 에 자동으로 엮지 않은 이유는, 필요 없는 상황에서
+매 요청마다 외부 게이트를 때리는 비용과 실패 지점이 생기기 때문입니다.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import ClassVar, Final
+
+from pykorail.exceptions import NetFunnelError
+from pykorail.transport import create_session
+
+logger = logging.getLogger(__name__)
+
+NETFUNNEL_URL: Final = "http://nf.letskorail.com/ts.wseq"
+
+NETFUNNEL_HEADERS: Final[dict[str, str]] = {
+    "Host": "nf.letskorail.com",
+    "Connection": "Keep-Alive",
+    "User-Agent": "Apache-HttpClient/UNAVAILABLE (java 1.4)",
+}
+
+
+class NetFunnelHelper:
+    """대기열을 통과해 티켓(key)을 얻습니다.
+
+    :meth:`run` 이 유일한 진입점입니다. 대기 줄이 있으면 통과할 때까지 1초 간격으로
+    폴링하므로 **블로킹**됩니다.
+    """
+
+    WAIT_STATUS_PASS: ClassVar[str] = "200"
+    WAIT_STATUS_FAIL: ClassVar[str] = "201"
+    ALREADY_COMPLETED: ClassVar[str] = "502"
+
+    OP_CODE: ClassVar[dict[str, str]] = {
+        "getTidchkEnter": "5101",
+        "chkEnter": "5002",
+        "setComplete": "5004",
+    }
+
+    #: 티켓 재사용 시간(초). 서버 만료보다 짧게 잡아 아슬아슬한 재사용을 피합니다.
+    CACHE_TTL: ClassVar[float] = 50.0
+
+    def __init__(self) -> None:
+        self._session = create_session(NETFUNNEL_HEADERS)
+        self._cached_key: str | None = None
+        self._last_fetch_time = 0.0
+
+    def run(self) -> str | None:
+        """통과 티켓을 돌려줍니다. 캐시가 살아 있으면 재사용합니다.
+
+        Raises:
+            NetFunnelError: 대기열 통과에 실패했습니다. 캐시는 비워집니다.
+        """
+        now = time.time()
+        if self._is_cache_valid(now):
+            return self._cached_key
+
+        try:
+            status, self._cached_key, nwait = self._start()
+            self._last_fetch_time = now
+
+            while status == self.WAIT_STATUS_FAIL:
+                logger.debug("현재 %s명 대기중", nwait)
+                time.sleep(1)
+                status, self._cached_key, nwait = self._check()
+
+            status, _, _ = self._complete()
+            if status in (self.WAIT_STATUS_PASS, self.ALREADY_COMPLETED):
+                return self._cached_key
+
+            self.clear()
+            raise NetFunnelError("Failed to complete NetFunnel")
+
+        except NetFunnelError:
+            self.clear()
+            raise
+        except Exception as exc:
+            self.clear()
+            raise NetFunnelError(str(exc)) from exc
+
+    def clear(self) -> None:
+        """캐시된 티켓을 버립니다."""
+        self._cached_key = None
+        self._last_fetch_time = 0.0
+
+    # ------------------------------------------------------------------- 내부
+    def _start(self) -> tuple[str | None, str | None, str | None]:
+        return self._make_request("getTidchkEnter")
+
+    def _check(self) -> tuple[str | None, str | None, str | None]:
+        return self._make_request("chkEnter")
+
+    def _complete(self) -> tuple[str | None, str | None, str | None]:
+        return self._make_request("setComplete")
+
+    def _make_request(self, operation: str) -> tuple[str | None, str | None, str | None]:
+        params = self._build_params(self.OP_CODE[operation])
+        parsed = self._parse(self._session.get(NETFUNNEL_URL, params=params).text)
+        return parsed.get("status"), parsed.get("key"), parsed.get("nwait")
+
+    def _build_params(self, opcode: str, key: str | None = None) -> dict[str, str]:
+        params: dict[str, str] = {"opcode": opcode}
+
+        if opcode in (self.OP_CODE["getTidchkEnter"], self.OP_CODE["chkEnter"]):
+            params.update({"sid": "service_1", "aid": "act_8"})
+            if opcode == self.OP_CODE["chkEnter"]:
+                params.update({"key": key or self._cached_key or "", "ttl": "1"})
+        elif opcode == self.OP_CODE["setComplete"]:
+            params["key"] = key or self._cached_key or ""
+
+        return params
+
+    @staticmethod
+    def _parse(response: str) -> dict[str, str]:
+        status, _, params_str = response.partition(":")
+        if not params_str:
+            raise NetFunnelError("Failed to parse NetFunnel response")
+
+        parsed = dict(param.split("=", 1) for param in params_str.split("&") if "=" in param)
+        parsed["status"] = status
+        return parsed
+
+    def _is_cache_valid(self, now: float) -> bool:
+        return bool(self._cached_key) and (now - self._last_fetch_time) < self.CACHE_TTL

pykorail/auth/signer.py

@@ -0,0 +1,51 @@
+"""요청 서명 — 어떤 경로에 어떤 인증 재료를 붙일지 결정합니다."""
+
+from __future__ import annotations
+
+import random
+import string
+from time import time
+from typing import TYPE_CHECKING
+
+from pykorail.auth.dynapath import DynaPathMasterEngine
+from pykorail.constants import DEVICE, DEVICE_ID, DYNAPATH_PATHS, SID_KEY
+from pykorail.crypto import encrypt_sid
+
+if TYPE_CHECKING:
+    from pykorail.device import DeviceProfileLike
+
+_NONCE_ALPHABET = string.ascii_uppercase + string.digits
+
+
+class RequestSigner:
+    """DynaPath 서명이 필요한 요청에 헤더와 ``Sid`` 를 만들어 줍니다.
+
+    엔진 인스턴스를 들고 있으므로 클라이언트당 하나만 두고 재사용하세요 —
+    엔진 생성 시각이 서명에 들어갑니다.
+    """
+
+    def __init__(
+        self,
+        profile: DeviceProfileLike | None = None,
+        device: str = DEVICE,
+        device_id: str = DEVICE_ID,
+        sid_key: bytes = SID_KEY,
+    ) -> None:
+        self._engine = DynaPathMasterEngine.from_profile(profile)
+        self._device = device
+        self._device_id = device_id
+        self._sid_key = sid_key
+
+    def sign(self, url: str) -> tuple[dict[str, str], str | None]:
+        """``url`` 에 필요한 ``(헤더, Sid)`` 를 만듭니다.
+
+        서명 대상이 아닌 경로면 ``({}, None)`` 을 돌려줍니다. 토큰과 ``Sid`` 는
+        같은 타임스탬프로 만들어야 서버가 짝을 맞춰 검증할 수 있습니다.
+        """
+        if not any(path in url for path in DYNAPATH_PATHS):
+            return {}, None
+
+        ts = int(time() * 1000)
+        nonce = "".join(random.choices(_NONCE_ALPHABET, k=4))
+        token = self._engine.generate_token(self._device_id, ts, nonce)
+        return {"x-dynapath-m-token": token}, encrypt_sid(self._device, ts, self._sid_key)