kwcli 0.1.0__py3-none-any.whl

kiwoom/core/secrets.py

@@ -0,0 +1,217 @@
+import hashlib
+import os
+from dataclasses import dataclass
+from typing import Protocol
+
+import keyring
+from keyring.errors import KeyringError, NoKeyringError
+
+from kiwoom.core.errors import KeyringUnavailableError
+from kiwoom.core.types import Mode
+
+
+@dataclass(frozen=True)
+class CredentialSet:
+    appkey: str
+    secretkey: str
+    source: str
+
+
+class SecretProvider(Protocol):
+    def get_credentials(self, mode: Mode) -> CredentialSet | None: ...
+
+    def set_credentials(self, mode: Mode, appkey: str, secretkey: str) -> None: ...
+
+    def clear_credentials(self, mode: Mode) -> None: ...
+
+
+class EnvSecretProvider:
+    def get_credentials(self, mode: Mode) -> CredentialSet | None:
+        appkey_var, secretkey_var = env_var_names(mode)
+        appkey = os.getenv(appkey_var)
+        secretkey = os.getenv(secretkey_var)
+        if not appkey or not secretkey:
+            return None
+        return CredentialSet(appkey=appkey, secretkey=secretkey, source="env")
+
+    def set_credentials(self, mode: Mode, appkey: str, secretkey: str) -> None:
+        raise RuntimeError("환경변수 공급자는 읽기 전용입니다.")
+
+    def clear_credentials(self, mode: Mode) -> None:
+        raise RuntimeError("환경변수 공급자는 읽기 전용입니다.")
+
+
+class KeyringSecretProvider:
+    def get_credentials(self, mode: Mode) -> CredentialSet | None:
+        try:
+            appkey = keyring.get_password(self._service_name(mode), "appkey")
+            secretkey = keyring.get_password(self._service_name(mode), "secretkey")
+        except NoKeyringError as exc:
+            raise KeyringUnavailableError(
+                "사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다. "
+                "환경변수를 사용하거나 지원되는 keyring 백엔드를 설치해 주세요."
+            ) from exc
+        except KeyringError as exc:
+            raise KeyringUnavailableError(f"운영체제 자격 증명 저장소를 읽는 중 오류가 발생했습니다: {exc}") from exc
+
+        if not appkey or not secretkey:
+            return None
+
+        return CredentialSet(appkey=appkey, secretkey=secretkey, source="keyring")
+
+    def set_credentials(self, mode: Mode, appkey: str, secretkey: str) -> None:
+        try:
+            keyring.set_password(self._service_name(mode), "appkey", appkey)
+            keyring.set_password(self._service_name(mode), "secretkey", secretkey)
+        except NoKeyringError as exc:
+            raise KeyringUnavailableError(
+                "사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다. "
+                "환경변수를 사용하거나 지원되는 keyring 백엔드를 설치해 주세요."
+            ) from exc
+        except KeyringError as exc:
+            self._best_effort_clear(mode)
+            raise KeyringUnavailableError(f"운영체제 자격 증명 저장소에 저장하는 중 오류가 발생했습니다: {exc}") from exc
+
+    def clear_credentials(self, mode: Mode) -> None:
+        try:
+            for name in ("appkey", "secretkey"):
+                try:
+                    keyring.delete_password(self._service_name(mode), name)
+                except keyring.errors.PasswordDeleteError:
+                    continue
+        except NoKeyringError as exc:
+            raise KeyringUnavailableError(
+                "사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다. "
+                "환경변수를 사용하거나 지원되는 keyring 백엔드를 설치해 주세요."
+            ) from exc
+        except KeyringError as exc:
+            raise KeyringUnavailableError(f"운영체제 자격 증명 저장소를 정리하는 중 오류가 발생했습니다: {exc}") from exc
+
+    @staticmethod
+    def _service_name(mode: Mode) -> str:
+        return f"kiwoom-{mode}"
+
+    def _best_effort_clear(self, mode: Mode) -> None:
+        for name in ("appkey", "secretkey"):
+            try:
+                keyring.delete_password(self._service_name(mode), name)
+            except Exception:
+                continue
+
+
+class ProfileKeyringSecretProvider:
+    def __init__(self, profile_alias: str) -> None:
+        self.profile_alias = profile_alias
+
+    def get_credentials(self, mode: Mode) -> CredentialSet | None:
+        try:
+            appkey = keyring.get_password(self._service_name(), "appkey")
+            secretkey = keyring.get_password(self._service_name(), "secretkey")
+        except NoKeyringError as exc:
+            raise KeyringUnavailableError(
+                "사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다. "
+                "환경변수를 사용하거나 지원되는 keyring 백엔드를 설치해 주세요."
+            ) from exc
+        except KeyringError as exc:
+            raise KeyringUnavailableError(f"운영체제 자격 증명 저장소를 읽는 중 오류가 발생했습니다: {exc}") from exc
+
+        if not appkey or not secretkey:
+            return None
+        return CredentialSet(appkey=appkey, secretkey=secretkey, source="keyring")
+
+    def set_credentials(self, mode: Mode, appkey: str, secretkey: str) -> None:
+        try:
+            keyring.set_password(self._service_name(), "appkey", appkey)
+            keyring.set_password(self._service_name(), "secretkey", secretkey)
+        except NoKeyringError as exc:
+            raise KeyringUnavailableError(
+                "사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다. "
+                "환경변수를 사용하거나 지원되는 keyring 백엔드를 설치해 주세요."
+            ) from exc
+        except KeyringError as exc:
+            self._best_effort_clear()
+            raise KeyringUnavailableError(f"운영체제 자격 증명 저장소에 저장하는 중 오류가 발생했습니다: {exc}") from exc
+
+    def clear_credentials(self, mode: Mode) -> None:
+        try:
+            for name in ("appkey", "secretkey"):
+                try:
+                    keyring.delete_password(self._service_name(), name)
+                except keyring.errors.PasswordDeleteError:
+                    continue
+        except NoKeyringError as exc:
+            raise KeyringUnavailableError(
+                "사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다. "
+                "환경변수를 사용하거나 지원되는 keyring 백엔드를 설치해 주세요."
+            ) from exc
+        except KeyringError as exc:
+            raise KeyringUnavailableError(f"운영체제 자격 증명 저장소를 정리하는 중 오류가 발생했습니다: {exc}") from exc
+
+    def _service_name(self) -> str:
+        digest = hashlib.sha256(self.profile_alias.encode("utf-8")).hexdigest()[:16]
+        return f"kiwoom-profile-{digest}"
+
+    def _best_effort_clear(self) -> None:
+        for name in ("appkey", "secretkey"):
+            try:
+                keyring.delete_password(self._service_name(), name)
+            except Exception:
+                continue
+
+
+class CompositeSecretProvider:
+    def __init__(
+        self,
+        *providers: SecretProvider,
+        writable_provider: SecretProvider | None = None,
+        suppress_read_errors: tuple[type[Exception], ...] = (),
+    ) -> None:
+        self.providers = providers
+        self.writable_provider = writable_provider
+        self.suppress_read_errors = suppress_read_errors
+
+    def get_credentials(self, mode: Mode) -> CredentialSet | None:
+        for provider in self.providers:
+            try:
+                credentials = provider.get_credentials(mode)
+            except self.suppress_read_errors:
+                continue
+            if credentials is not None:
+                return credentials
+        return None
+
+    def set_credentials(self, mode: Mode, appkey: str, secretkey: str) -> None:
+        if self.writable_provider is None:
+            raise RuntimeError("이 자격 증명 공급자는 읽기 전용입니다.")
+        self.writable_provider.set_credentials(mode, appkey, secretkey)
+
+    def clear_credentials(self, mode: Mode) -> None:
+        if self.writable_provider is None:
+            raise RuntimeError("이 자격 증명 공급자는 읽기 전용입니다.")
+        self.writable_provider.clear_credentials(mode)
+
+
+def default_secret_provider(*, profile: str | None = None) -> CompositeSecretProvider:
+    if profile is not None:
+        profile_keyring_provider = ProfileKeyringSecretProvider(profile)
+        return CompositeSecretProvider(
+            profile_keyring_provider,
+            writable_provider=profile_keyring_provider,
+            suppress_read_errors=(KeyringUnavailableError,),
+        )
+
+    keyring_provider = KeyringSecretProvider()
+    return CompositeSecretProvider(
+        EnvSecretProvider(),
+        keyring_provider,
+        writable_provider=keyring_provider,
+        suppress_read_errors=(KeyringUnavailableError,),
+    )
+
+
+def env_var_names(mode: Mode) -> tuple[str, str]:
+    if mode == "real":
+        return "APP_KEY", "APP_SECRET"
+    if mode == "demo":
+        return "APP_KEY_MOCK", "APP_SECRET_MOCK"
+    raise ValueError(f"Unsupported mode: {mode!r}")

kiwoom/core/settings.py

@@ -0,0 +1,64 @@
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from kiwoom.core.errors import InvalidModeError, SettingsError
+from kiwoom.core.platform_paths import config_dir, ensure_private_directory, protect_file
+from kiwoom.core.types import Mode, normalize_mode
+
+
+SETTINGS_FILE_NAME = "settings.json"
+MODE_ENV_VAR = "KIWOOM_MODE"
+PROFILE_ENV_VAR = "KIWOOM_PROFILE"
+
+
+def get_mode_from_env() -> Mode | None:
+    value = os.getenv(MODE_ENV_VAR)
+    if not value:
+        return None
+    try:
+        return normalize_mode(value)
+    except ValueError as exc:
+        raise InvalidModeError(value) from exc
+
+
+def get_profile_from_env() -> str | None:
+    value = os.getenv(PROFILE_ENV_VAR)
+    if not value:
+        return None
+    return value.strip() or None
+
+
+def settings_path() -> Path:
+    return config_dir() / SETTINGS_FILE_NAME
+
+
+def snapshot_settings() -> str | None:
+    path = settings_path()
+    if not path.exists():
+        return None
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SettingsError("settings.json 파일을 읽을 수 없습니다.") from exc
+
+
+def restore_settings(snapshot: str | None) -> None:
+    path = settings_path()
+    if snapshot is None:
+        path.unlink(missing_ok=True)
+        return
+
+    directory = ensure_private_directory(config_dir(), strict=False)
+    with NamedTemporaryFile(
+        "w",
+        encoding="utf-8",
+        dir=directory,
+        delete=False,
+    ) as tmp:
+        tmp.write(snapshot)
+        temp_path = Path(tmp.name)
+
+    protect_file(temp_path, strict=False)
+    temp_path.replace(path)
+    protect_file(path, strict=False)

kiwoom/core/token_store.py

@@ -0,0 +1,186 @@
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from stat import S_IMODE
+from tempfile import NamedTemporaryFile
+
+from kiwoom.core.errors import InvalidTokenCacheError
+from kiwoom.core.platform_paths import cache_dir, ensure_private_directory, protect_file
+from kiwoom.core.profiles import validate_profile_alias
+from kiwoom.core.types import Mode
+
+
+VALID_TOKEN_TYPES = {"bearer"}
+
+
+@dataclass(frozen=True)
+class TokenRecord:
+    access_token: str
+    token_type: str
+    expires_at: datetime
+    mode: Mode
+    profile: str | None = None
+    credential_fingerprint: str | None = None
+    saved_at: datetime | None = None
+
+    def to_json(self) -> dict[str, str]:
+        payload = {
+            "access_token": self.access_token,
+            "token_type": self.token_type,
+            "expires_at": self.expires_at.astimezone(UTC).isoformat(),
+            "mode": self.mode,
+        }
+        if self.profile:
+            payload["profile"] = self.profile
+        if self.credential_fingerprint:
+            payload["credential_fingerprint"] = self.credential_fingerprint
+        if self.saved_at:
+            payload["saved_at"] = self.saved_at.astimezone(UTC).isoformat()
+        return payload
+
+    @classmethod
+    def from_json(cls, payload: dict[str, str], *, path: Path) -> "TokenRecord":
+        try:
+            token_type = payload["token_type"].lower()
+            expires_at = datetime.fromisoformat(payload["expires_at"])
+            saved_at_value = payload.get("saved_at")
+            saved_at = datetime.fromisoformat(saved_at_value) if saved_at_value else None
+            mode = payload["mode"]
+            access_token = payload["access_token"]
+        except KeyError as exc:
+            raise InvalidTokenCacheError(path, f"필수 필드가 없습니다: {exc.args[0]}") from exc
+        except ValueError as exc:
+            raise InvalidTokenCacheError(path, f"필드 형식이 올바르지 않습니다: {exc}") from exc
+
+        if token_type not in VALID_TOKEN_TYPES:
+            raise InvalidTokenCacheError(path, f"지원하지 않는 token_type 값입니다: {token_type}")
+        if not access_token:
+            raise InvalidTokenCacheError(path, "access_token 값이 비어 있습니다.")
+        if expires_at.tzinfo is None:
+            raise InvalidTokenCacheError(path, "expires_at에는 시간대 정보가 포함되어야 합니다.")
+        if saved_at is not None and saved_at.tzinfo is None:
+            raise InvalidTokenCacheError(path, "saved_at에는 시간대 정보가 포함되어야 합니다.")
+        if mode not in ("real", "demo"):
+            raise InvalidTokenCacheError(path, f"지원하지 않는 mode 값입니다: {mode}")
+
+        profile = payload.get("profile")
+        if profile is not None:
+            try:
+                profile = validate_profile_alias(profile)
+            except ValueError as exc:
+                raise InvalidTokenCacheError(path, f"profile 값이 올바르지 않습니다: {profile!r}") from exc
+
+        return cls(
+            access_token=access_token,
+            token_type=token_type,
+            expires_at=expires_at.astimezone(UTC),
+            mode=mode,
+            profile=profile,
+            credential_fingerprint=payload.get("credential_fingerprint"),
+            saved_at=saved_at.astimezone(UTC) if saved_at else None,
+        )
+
+
+class MemoryTokenStore:
+    def __init__(self) -> None:
+        self._records: dict[str, TokenRecord] = {}
+
+    def load(self, mode: Mode, *, profile: str | None = None) -> TokenRecord | None:
+        return self._records.get(self._key(mode, profile=profile))
+
+    def save(self, record: TokenRecord) -> None:
+        self._records[self._key(record.mode, profile=record.profile)] = record
+
+    def clear(self, mode: Mode, *, profile: str | None = None) -> None:
+        self._records.pop(self._key(mode, profile=profile), None)
+
+    def peek(self, mode: Mode, *, profile: str | None = None) -> TokenRecord | None:
+        return self.load(mode, profile=profile)
+
+    @staticmethod
+    def _key(mode: Mode, *, profile: str | None) -> str:
+        return f"profile:{profile}" if profile else f"mode:{mode}"
+
+
+class FileTokenStore:
+    def __init__(self, *, strict_permissions: bool = True) -> None:
+        self.strict_permissions = strict_permissions
+
+    def load(self, mode: Mode, *, profile: str | None = None) -> TokenRecord | None:
+        return self._read(mode, profile=profile, clear_on_error=True)
+
+    def peek(self, mode: Mode, *, profile: str | None = None) -> TokenRecord | None:
+        return self._read(mode, profile=profile, clear_on_error=False)
+
+    def _read(self, mode: Mode, *, profile: str | None, clear_on_error: bool) -> TokenRecord | None:
+        path = self._token_path(mode, profile=profile)
+        if not path.exists():
+            return None
+        self._validate_permissions(path, clear_on_error=clear_on_error)
+
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            record = TokenRecord.from_json(payload, path=path)
+        except json.JSONDecodeError as exc:
+            if clear_on_error:
+                self.clear(mode, profile=profile)
+            raise InvalidTokenCacheError(path, f"JSON 파싱에 실패했습니다: {exc}") from exc
+        except InvalidTokenCacheError:
+            if clear_on_error:
+                self.clear(mode, profile=profile)
+            raise
+
+        if record.mode != mode:
+            if clear_on_error:
+                self.clear(mode, profile=profile)
+            raise InvalidTokenCacheError(path, "저장된 mode 값이 요청한 mode와 일치하지 않습니다.")
+
+        return record
+
+    def save(self, record: TokenRecord) -> None:
+        directory = ensure_private_directory(self._token_directory(record.profile), strict=self.strict_permissions)
+        path = self._token_path(record.mode, profile=record.profile)
+        payload = json.dumps(record.to_json(), ensure_ascii=True, indent=2)
+
+        with NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=directory,
+            delete=False,
+        ) as tmp:
+            tmp.write(payload)
+            tmp.flush()
+            os.fsync(tmp.fileno())
+            temp_path = Path(tmp.name)
+
+        protect_file(temp_path, strict=self.strict_permissions)
+        temp_path.replace(path)
+        protect_file(path, strict=self.strict_permissions)
+
+    def clear(self, mode: Mode, *, profile: str | None = None) -> None:
+        path = self._token_path(mode, profile=profile)
+        path.unlink(missing_ok=True)
+
+    @staticmethod
+    def _token_directory(profile: str | None) -> Path:
+        return cache_dir() / "profiles" if profile else cache_dir()
+
+    @staticmethod
+    def _token_path(mode: Mode, *, profile: str | None = None) -> Path:
+        if profile:
+            alias = validate_profile_alias(profile)
+            digest = hashlib.sha256(alias.encode("utf-8")).hexdigest()[:16]
+            return cache_dir() / "profiles" / f"profile-{digest}-token.json"
+        return cache_dir() / f"{mode}-token.json"
+
+    def _validate_permissions(self, path: Path, *, clear_on_error: bool) -> None:
+        if os.name == "nt":
+            return
+        mode = S_IMODE(path.stat().st_mode)
+        if mode & 0o077:
+            if clear_on_error:
+                path.unlink(missing_ok=True)
+            raise InvalidTokenCacheError(path, "토큰 캐시 파일 권한이 너무 넓게 열려 있습니다.")

kiwoom/core/types.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+Mode = Literal["real", "demo"]
+
+VALID_MODES = ("real", "demo")
+
+
+def normalize_mode(value: str) -> Mode:
+    if value not in VALID_MODES:
+        raise ValueError(f"Unsupported mode: {value!r}. Expected one of {VALID_MODES}.")
+    return value  # type: ignore[return-value]
+
+
+@dataclass(frozen=True)
+class Continuation:
+    has_next: bool
+    next_key: str | None
+    cont_yn: str | None
+
+
+@dataclass(frozen=True)
+class KiwoomResponse:
+    body: dict[str, Any]
+    continuation: Continuation
+    headers: dict[str, str]