khdp 0.1.0__py3-none-any.whl

khdp/__init__.py

@@ -0,0 +1,18 @@
+"""KHDP Connector — auth + MCP server for the Korea Health Data Platform."""
+
+from khdp.config import Config, load_config
+from khdp.oauth import AuthError, KhdpAuthClient, OAuthError, TokenSet
+from khdp.token_store import TokenStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthError",
+    "Config",
+    "KhdpAuthClient",
+    "OAuthError",
+    "TokenSet",
+    "TokenStore",
+    "__version__",
+    "load_config",
+]

khdp/__main__.py

@@ -0,0 +1,4 @@
+from khdp.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

khdp/cli.py

@@ -0,0 +1,227 @@
+"""``khdp`` command-line interface.
+
+Subcommands:
+
+* ``khdp login`` -- interactive email + password login against KHDP.
+* ``khdp logout`` -- delete the cached token.
+* ``khdp status`` -- show whether a token is cached.
+* ``khdp refresh`` -- force a refresh-token rotation.
+* ``khdp token`` -- print the current access token (use with care).
+* ``khdp api METHOD PATH`` -- issue an authenticated API call.
+* ``khdp config`` -- show the resolved configuration.
+* ``khdp mcp`` -- start the MCP server on stdio.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import logging
+import os
+import sys
+from collections.abc import Sequence
+
+from khdp import __version__
+from khdp.config import load_config
+from khdp.oauth import AuthError
+from khdp.session import Session
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="khdp",
+        description="KHDP connector -- login + API calls + MCP server.",
+    )
+    parser.add_argument("--version", action="version", version=f"khdp {__version__}")
+    parser.add_argument(
+        "-v", "--verbose", action="count", default=0,
+        help="increase logging verbosity (repeat for debug)",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_login = sub.add_parser("login", help="log in with email + password")
+    p_login.add_argument("--email", help="account email (else $KHDP_EMAIL or prompt)")
+    p_login.add_argument(
+        "--password-stdin", action="store_true",
+        help="read password from stdin instead of prompting (for scripts)",
+    )
+
+    sub.add_parser("logout", help="delete cached tokens")
+    sub.add_parser("status", help="show cached token state")
+    sub.add_parser("refresh", help="force-refresh the access token")
+
+    p_token = sub.add_parser("token", help="print the current access token")
+    p_token.add_argument("--raw", action="store_true",
+                         help="print only the token value (no JSON envelope)")
+
+    p_api = sub.add_parser("api", help="make an authenticated API call")
+    p_api.add_argument("method", help="HTTP method, e.g. GET / POST")
+    p_api.add_argument("path", help="API path or full URL")
+    p_api.add_argument("--query", action="append", default=[], metavar="KEY=VAL",
+                       help="query parameter (repeatable)")
+    p_api.add_argument("--data", help="JSON body string")
+
+    sub.add_parser("mcp", help="run the KHDP MCP server on stdio")
+    sub.add_parser("config", help="show resolved configuration")
+
+    return parser
+
+
+def _setup_logging(verbose: int) -> None:
+    level = logging.WARNING
+    if verbose == 1:
+        level = logging.INFO
+    elif verbose >= 2:
+        level = logging.DEBUG
+    logging.basicConfig(level=level, format="[khdp] %(levelname)s %(message)s")
+
+
+def _emit(payload: object) -> None:
+    print(json.dumps(payload, indent=2, sort_keys=True, default=str))
+
+
+def _resolve_email(args: argparse.Namespace) -> str:
+    email = args.email or os.environ.get("KHDP_EMAIL")
+    if email:
+        return email
+    if not sys.stdin.isatty():
+        raise SystemExit(
+            "[khdp] no --email given and stdin is not a TTY. "
+            "Set KHDP_EMAIL or pass --email."
+        )
+    return input("KHDP email: ").strip()
+
+
+def _resolve_password(args: argparse.Namespace) -> str:
+    if args.password_stdin:
+        password = sys.stdin.readline().rstrip("\n")
+        if not password:
+            raise SystemExit("[khdp] --password-stdin given but stdin was empty.")
+        return password
+    env = os.environ.get("KHDP_PASSWORD")
+    if env:
+        return env
+    if not sys.stdin.isatty():
+        raise SystemExit(
+            "[khdp] no password available. Use --password-stdin or set KHDP_PASSWORD."
+        )
+    return getpass.getpass("KHDP password: ")
+
+
+def _cmd_login(session: Session, args: argparse.Namespace) -> int:
+    email = _resolve_email(args)
+    password = _resolve_password(args)
+    tokens = session.login(email=email, password=password)
+    _emit({
+        "ok": True,
+        "app_id": tokens.app_id,
+        "expires_at": tokens.expires_at,
+        "has_refresh_token": tokens.refresh_token is not None,
+    })
+    return 0
+
+
+def _cmd_logout(session: Session, _args: argparse.Namespace) -> int:
+    deleted = session.logout()
+    _emit({"ok": True, "deleted": deleted})
+    return 0
+
+
+def _cmd_status(session: Session, _args: argparse.Namespace) -> int:
+    _emit(session.status())
+    return 0
+
+
+def _cmd_refresh(session: Session, _args: argparse.Namespace) -> int:
+    tokens = session.store.load(session.config.app_id or None)
+    if not tokens or not tokens.refresh_token:
+        print("[khdp] no refresh token cached; run `khdp login` first.", file=sys.stderr)
+        return 1
+    refreshed = session.auth.refresh(tokens.refresh_token)
+    if not refreshed.refresh_token:
+        refreshed.refresh_token = tokens.refresh_token
+    if not refreshed.app_id:
+        refreshed.app_id = tokens.app_id or session.config.app_id
+    session.store.save(refreshed)
+    _emit({"ok": True, "expires_at": refreshed.expires_at})
+    return 0
+
+
+def _cmd_token(session: Session, args: argparse.Namespace) -> int:
+    token = session.access_token()
+    if args.raw:
+        print(token)
+    else:
+        _emit({"access_token": token})
+    return 0
+
+
+def _cmd_api(session: Session, args: argparse.Namespace) -> int:
+    params: dict[str, str] = {}
+    for kv in args.query:
+        if "=" not in kv:
+            print(f"[khdp] invalid --query (expected KEY=VAL): {kv}", file=sys.stderr)
+            return 2
+        k, v = kv.split("=", 1)
+        params[k] = v
+    body = json.loads(args.data) if args.data else None
+    resp = session.authed_request(args.method, args.path, params=params or None, json=body)
+    print(f"[khdp] {resp.status_code} {resp.reason_phrase}", file=sys.stderr)
+    try:
+        _emit(resp.json())
+    except ValueError:
+        sys.stdout.write(resp.text)
+    return 0 if resp.is_success else 1
+
+
+def _cmd_mcp(_session: Session, _args: argparse.Namespace) -> int:
+    from khdp.mcp_server import run_stdio
+    run_stdio()
+    return 0
+
+
+def _cmd_config(session: Session, _args: argparse.Namespace) -> int:
+    cfg = session.config
+    _emit({
+        "app_id": cfg.app_id or None,
+        "redirect_url": cfg.redirect_url or None,
+        "api_base": cfg.api_base,
+        "token_dir": str(cfg.token_dir),
+        "use_keyring": cfg.use_keyring,
+    })
+    return 0
+
+
+_DISPATCH = {
+    "login": _cmd_login,
+    "logout": _cmd_logout,
+    "status": _cmd_status,
+    "refresh": _cmd_refresh,
+    "token": _cmd_token,
+    "api": _cmd_api,
+    "mcp": _cmd_mcp,
+    "config": _cmd_config,
+}
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    _setup_logging(args.verbose)
+
+    config = load_config()
+    try:
+        with Session.open(config=config) as session:
+            return _DISPATCH[args.command](session, args)
+    except AuthError as exc:
+        print(f"[khdp] {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("[khdp] interrupted.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

khdp/config.py

@@ -0,0 +1,106 @@
+"""Configuration loading for the KHDP connector.
+
+KHDP authentication is identified by an ``app_id`` (UUID) registered
+with KHDP and a ``redirect_url`` allowlisted for that app. Both values
+are required for any login or token-refresh call.
+
+Resolution order (highest priority first):
+
+1. Environment variables: ``KHDP_*``
+2. ``khdp.local.toml`` in the current working directory
+3. ``$XDG_CONFIG_HOME/khdp/config.toml`` (or platform equivalent)
+4. Built-in defaults pointing at the production KHDP API.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+
+# KHDP central API base — observed at https://khdp.net/_api.
+DEFAULT_API_BASE = "https://khdp.net/_api"
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved configuration for the connector."""
+
+    # KHDP app registration. ``app_id`` is a UUID issued by KHDP at app
+    # registration time; ``redirect_url`` must match one of the URLs
+    # allowlisted for that app. Both are required even for headless
+    # password login because the KHDP backend validates them.
+    app_id: str = ""
+    redirect_url: str = ""
+    # KHDP API base. Override for staging / on-prem deployments.
+    api_base: str = DEFAULT_API_BASE
+    # Where tokens go on disk. Defaults to platform user-config dir.
+    token_dir: Path = field(default_factory=lambda: Path(user_config_dir("khdp")))
+    # Use OS keychain via the optional ``keyring`` extra when available.
+    use_keyring: bool = True
+
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+def _config_path_user() -> Path:
+    return Path(user_config_dir("khdp")) / "config.toml"
+
+
+def _config_path_local() -> Path:
+    return Path.cwd() / "khdp.local.toml"
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    with path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def _env_overrides() -> dict[str, Any]:
+    mapping = {
+        "app_id": "KHDP_APP_ID",
+        "redirect_url": "KHDP_REDIRECT_URL",
+        "api_base": "KHDP_API_BASE",
+    }
+    out: dict[str, Any] = {}
+    for key, env in mapping.items():
+        if (val := os.environ.get(env)) is not None:
+            out[key] = val
+    if (token_dir := os.environ.get("KHDP_TOKEN_DIR")) is not None:
+        out["token_dir"] = Path(token_dir).expanduser()
+    if (use_kr := os.environ.get("KHDP_USE_KEYRING")) is not None:
+        out["use_keyring"] = use_kr.lower() not in {"0", "false", "no", "off"}
+    return out
+
+
+def load_config(*, extra_path: Path | None = None) -> Config:
+    """Resolve config from defaults + files + environment."""
+    layers: list[dict[str, Any]] = [_read_toml(_config_path_user())]
+    if extra_path is not None:
+        layers.append(_read_toml(extra_path))
+    layers.append(_read_toml(_config_path_local()))
+    layers.append(_env_overrides())
+
+    merged: dict[str, Any] = {}
+    for layer in layers:
+        merged.update(layer)
+
+    if "token_dir" in merged and not isinstance(merged["token_dir"], Path):
+        merged["token_dir"] = Path(merged["token_dir"]).expanduser()
+
+    valid_fields = {f for f in Config.__dataclass_fields__ if f != "extras"}
+    extras = {k: v for k, v in merged.items() if k not in valid_fields}
+    primary = {k: v for k, v in merged.items() if k in valid_fields}
+
+    return Config(extras=extras, **primary)

khdp/mcp_server.py

@@ -0,0 +1,231 @@
+"""MCP server exposing KHDP authentication state + thin API access.
+
+This is the Tier 1 surface from PLAN.md. It runs over stdio so it can be
+spawned by any MCP-aware client (Claude Code, Codex, Gemini CLI, custom
+agents). The same tool set is reused across all wrappers, which is the
+whole point of MCP-as-foundation.
+
+The MCP server **never** accepts a password through tool arguments --
+passwords would otherwise flow through the LLM context window. Login
+is initiated out-of-band by the user via ``khdp login`` in their
+terminal; the MCP server reads the resulting token cache.
+
+Tools exposed:
+  - khdp_auth_status     : is the user logged in? when does the token expire?
+  - khdp_auth_refresh    : rotate the refresh token to extend the session.
+  - khdp_auth_logout     : delete the locally cached tokens.
+  - khdp_api_request     : authenticated passthrough to the KHDP API.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from typing import Any
+
+from khdp.oauth import AuthError
+from khdp.session import Session
+
+log = logging.getLogger(__name__)
+
+
+_TOOLS: list[dict[str, Any]] = [
+    {
+        "name": "khdp_auth_status",
+        "description": (
+            "Return whether the user is logged in to KHDP and, if so, when "
+            "the access token expires. Safe to call at any time; never "
+            "performs a network request."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "khdp_auth_refresh",
+        "description": (
+            "Rotate the refresh token to extend the session. Use when "
+            "khdp_auth_status reports is_expired=true. Fails with an "
+            "AuthError if there is no cached refresh token (the user "
+            "must run `khdp login` in a terminal first)."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "khdp_auth_logout",
+        "description": (
+            "Delete the locally cached KHDP tokens. KHDP does not expose "
+            "a refresh-token revocation endpoint, so this only clears "
+            "client-side state."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "khdp_api_request",
+        "description": (
+            "Make an authenticated HTTP request against the KHDP API. The "
+            "Authorization: Bearer header is added automatically. Use "
+            "this as the transport for any KHDP backend endpoint that "
+            "does not yet have a dedicated MCP tool."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "required": ["method", "path"],
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                    "description": "HTTP method.",
+                },
+                "path": {
+                    "type": "string",
+                    "description": (
+                        "API path (e.g. '/oauth/redirect-url') or "
+                        "absolute URL. Relative paths are resolved "
+                        "against KHDP_API_BASE (default https://khdp.net/_api)."
+                    ),
+                },
+                "query": {
+                    "type": "object",
+                    "additionalProperties": {"type": "string"},
+                    "description": "Query string parameters.",
+                },
+                "json": {
+                    "description": "JSON body for POST/PUT/PATCH.",
+                },
+            },
+            "additionalProperties": False,
+        },
+    },
+]
+
+
+def _result_text(payload: object) -> dict[str, Any]:
+    return {
+        "content": [
+            {"type": "text", "text": json.dumps(payload, indent=2, default=str, sort_keys=True)}
+        ]
+    }
+
+
+def _error_text(message: str) -> dict[str, Any]:
+    return {
+        "content": [{"type": "text", "text": f"Error: {message}"}],
+        "isError": True,
+    }
+
+
+def _dispatch(session: Session, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    try:
+        if name == "khdp_auth_status":
+            return _result_text(session.status())
+        if name == "khdp_auth_refresh":
+            tokens = session.store.load(session.config.app_id or None)
+            if not tokens or not tokens.refresh_token:
+                raise AuthError(
+                    "No refresh token cached. Run `khdp login` in a terminal first."
+                )
+            refreshed = session.auth.refresh(tokens.refresh_token)
+            if not refreshed.refresh_token:
+                refreshed.refresh_token = tokens.refresh_token
+            if not refreshed.app_id:
+                refreshed.app_id = tokens.app_id or session.config.app_id
+            session.store.save(refreshed)
+            return _result_text({"ok": True, "expires_at": refreshed.expires_at})
+        if name == "khdp_auth_logout":
+            deleted = session.logout()
+            return _result_text({"ok": True, "deleted": deleted})
+        if name == "khdp_api_request":
+            method = arguments["method"]
+            path = arguments["path"]
+            query = arguments.get("query") or None
+            body = arguments.get("json")
+            resp = session.authed_request(method, path, params=query, json=body)
+            try:
+                data: object = resp.json()
+            except ValueError:
+                data = resp.text
+            return _result_text({
+                "status": resp.status_code,
+                "reason": resp.reason_phrase,
+                "body": data,
+            })
+        return _error_text(f"Unknown tool: {name}")
+    except AuthError as exc:
+        return _error_text(str(exc))
+    except Exception as exc:
+        log.exception("Tool %s failed", name)
+        return _error_text(f"{type(exc).__name__}: {exc}")
+
+
+# --- Server wiring (official MCP SDK) ------------------------------------
+
+
+async def _run_async() -> None:
+    # Imported here so users running just the CLI don't need the MCP extra.
+    import mcp.types as mt
+    from mcp.server.lowlevel import Server
+    from mcp.server.stdio import stdio_server
+
+    server = Server("khdp")
+    session = Session.open()
+
+    @server.list_tools()
+    async def _list_tools() -> list[mt.Tool]:
+        return [
+            mt.Tool(
+                name=t["name"],
+                description=t["description"],
+                inputSchema=t["inputSchema"],
+            )
+            for t in _TOOLS
+        ]
+
+    @server.call_tool()
+    async def _call_tool(name: str, arguments: dict[str, Any] | None) -> list[mt.TextContent]:
+        result = _dispatch(session, name, arguments or {})
+        contents = result.get("content", [])
+        out: list[mt.TextContent] = []
+        for c in contents:
+            if c.get("type") == "text":
+                out.append(mt.TextContent(type="text", text=c["text"]))
+        if result.get("isError"):
+            raise RuntimeError(contents[0]["text"] if contents else "tool error")
+        return out
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+def run_stdio() -> None:
+    """Entry point used by the CLI and the ``khdp-mcp`` console script."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="[khdp-mcp] %(levelname)s %(message)s",
+    )
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(_run_async())
+
+
+def main() -> None:  # pragma: no cover
+    run_stdio()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

khdp/oauth.py

@@ -0,0 +1,220 @@
+"""KHDP authentication client.
+
+KHDP authenticates apps via an ``appId`` (UUID) registered with KHDP
+plus an allowlisted ``redirectUrl``. KHDP issues a Bearer
+``accessToken`` + ``refreshToken`` pair. This module wraps the two
+endpoints used by the CLI / MCP server:
+
+* ``POST /_api/oauth/login`` -- direct ``mail + password`` login.
+* ``POST /_api/member/refresh-token`` -- rotate an expired access token.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+import httpx
+
+from khdp.config import Config
+
+log = logging.getLogger(__name__)
+
+
+class AuthError(RuntimeError):
+    """Raised when KHDP rejects a login or refresh request."""
+
+
+# Backward-compat alias -- previous draft used the OIDC name.
+OAuthError = AuthError
+
+
+@dataclass
+class TokenSet:
+    """Bearer token pair issued by KHDP."""
+
+    access_token: str
+    refresh_token: str | None = None
+    # KHDP's payload uses ``expireTime`` as an absolute unix-millis timestamp.
+    # We normalise to seconds and store the absolute moment of expiry.
+    expires_at: float = 0.0
+    app_id: str = ""
+    obtained_at: float = field(default_factory=time.time)
+
+    @property
+    def is_expired(self) -> bool:
+        if self.expires_at == 0.0:
+            return False
+        # 30 second skew so the server doesn't reject a token we just refreshed.
+        return time.time() >= (self.expires_at - 30)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> TokenSet:
+        return cls(**payload)
+
+    @classmethod
+    def from_khdp_response(cls, payload: dict[str, Any], *, app_id: str) -> TokenSet:
+        """Normalise a KHDP token response.
+
+        KHDP's documented field is ``expireTime``. The shape observed in
+        the public ``khdp.net`` SPA bundle is:
+
+        ```json
+        { "accessToken": "...", "refreshToken": "...", "expireTime": 173... }
+        ```
+
+        ``expireTime`` is unix milliseconds in the SPA's localStorage
+        usage, but tolerate both seconds and milliseconds because
+        upstream documentation is not public.
+        """
+        access = payload.get("accessToken") or payload.get("access_token")
+        if not access:
+            raise AuthError(f"Login response missing accessToken: {payload}")
+        refresh = payload.get("refreshToken") or payload.get("refresh_token")
+        expire_raw = payload.get("expireTime") or payload.get("expire_time") or 0
+        try:
+            expire_num = float(expire_raw)
+        except (TypeError, ValueError):
+            expire_num = 0.0
+        # If the value looks like milliseconds (>= 10^12), convert to seconds.
+        if expire_num >= 1e12:
+            expire_num = expire_num / 1000.0
+        # If the value is < 10^9 it's almost certainly a relative duration
+        # in seconds (rare but seen on some KHDP environments).
+        if 0 < expire_num < 1e9:
+            expire_num = time.time() + expire_num
+        return cls(
+            access_token=access,
+            refresh_token=refresh,
+            expires_at=expire_num,
+            app_id=app_id,
+            obtained_at=time.time(),
+        )
+
+
+@dataclass
+class _Endpoints:
+    login: str
+    refresh: str
+    auto_login: str
+    consent: str
+
+
+class KhdpAuthClient:
+    """Thin client for KHDP's ``/_api/oauth/*`` and ``/_api/member/*`` routes.
+
+    Two flows are supported:
+
+    * :meth:`password_login` -- direct ``mail + password`` exchange
+      against ``POST /_api/oauth/login``. The KHDP-registered app is
+      identified by ``appId`` and ``redirectUrl`` (both required by the
+      backend even though no browser redirect is involved).
+    * :meth:`refresh` -- rotate an expired access token via
+      ``POST /_api/member/refresh-token``.
+
+    """
+
+    def __init__(self, config: Config, *, http_client: httpx.Client | None = None) -> None:
+        self.config = config
+        self._http = http_client or httpx.Client(
+            timeout=30.0,
+            headers={"User-Agent": "khdp/0.1.0"},
+        )
+        base = config.api_base.rstrip("/")
+        self._endpoints = _Endpoints(
+            login=f"{base}/oauth/login",
+            refresh=f"{base}/member/refresh-token",
+            auto_login=f"{base}/member/auto-login",
+            consent=f"{base}/oauth/consent",
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> KhdpAuthClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- public API --------------------------------------------------------
+
+    def password_login(self, *, email: str, password: str) -> TokenSet:
+        """Log in with email + password.
+
+        Requires ``app_id`` and ``redirect_url`` to be set on the config.
+        Both fields are validated server-side: ``appId`` must be a UUID
+        and ``redirectUrl`` must be a URL. ``password`` must be 8-50
+        characters; KHDP returns HTTP 400 with explicit field-level
+        errors for any violation.
+        """
+        if not self.config.app_id:
+            raise AuthError(
+                "config.app_id is required for KHDP login. "
+                "Register a KHDP app and set it via KHDP_APP_ID or khdp.local.toml."
+            )
+        if not self.config.redirect_url:
+            raise AuthError(
+                "config.redirect_url is required for KHDP login. "
+                "Set the value registered with the KHDP app (any allowlisted URL)."
+            )
+
+        body = {
+            "appId": self.config.app_id,
+            "redirectUrl": self.config.redirect_url,
+            "mail": email,
+            "password": password,
+        }
+        return self._post_token(self._endpoints.login, body)
+
+    def refresh(self, refresh_token: str) -> TokenSet:
+        """Rotate an expired access token.
+
+        KHDP returns HTTP 403 with message
+        ``"Refresh Token Is Not Validate"`` (their typo, preserved) when
+        the token has been revoked or expired beyond the refresh window.
+        """
+        return self._post_token(self._endpoints.refresh, {"refreshToken": refresh_token})
+
+    def auto_login(self, *, access_token: str, refresh_token: str) -> TokenSet:
+        """Sliding-refresh login used by the KHDP web client at startup.
+
+        Useful for re-establishing a session from a previously cached
+        token pair without prompting for a password.
+        """
+        body = {"accessToken": access_token, "refreshToken": refresh_token}
+        return self._post_token(self._endpoints.auto_login, body)
+
+    # -- internals --------------------------------------------------------
+
+    def _post_token(self, url: str, body: dict[str, Any]) -> TokenSet:
+        try:
+            resp = self._http.post(url, json=body)
+        except httpx.HTTPError as exc:
+            raise AuthError(f"KHDP endpoint unreachable ({url}): {exc}") from exc
+
+        if resp.status_code == 200:
+            try:
+                payload = resp.json()
+            except ValueError as exc:
+                raise AuthError(f"KHDP returned non-JSON success: {resp.text[:200]}") from exc
+            return TokenSet.from_khdp_response(payload, app_id=self.config.app_id)
+
+        # Surface the most useful piece of the JSON error body.
+        detail: str = resp.text[:400]
+        try:
+            payload = resp.json()
+            if isinstance(payload, dict):
+                msg = payload.get("message")
+                if isinstance(msg, list):
+                    detail = "; ".join(str(m) for m in msg)
+                elif isinstance(msg, str):
+                    detail = msg
+        except ValueError:
+            pass
+        raise AuthError(f"KHDP {resp.status_code} {url}: {detail}")

khdp/session.py

@@ -0,0 +1,127 @@
+"""Session helpers -- combine ``KhdpAuthClient`` and ``TokenStore`` to give
+callers a single ``access_token()`` style API that handles refresh
+transparently."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from khdp.config import Config, load_config
+from khdp.oauth import AuthError, KhdpAuthClient, TokenSet
+from khdp.token_store import TokenStore
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class Session:
+    config: Config
+    auth: KhdpAuthClient
+    store: TokenStore
+
+    @classmethod
+    def open(cls, *, config: Config | None = None) -> Session:
+        cfg = config or load_config()
+        return cls(
+            config=cfg,
+            auth=KhdpAuthClient(cfg),
+            store=TokenStore(cfg.token_dir, use_keyring=cfg.use_keyring),
+        )
+
+    def close(self) -> None:
+        self.auth.close()
+
+    def __enter__(self) -> Session:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+
+    def login(self, *, email: str, password: str) -> TokenSet:
+        tokens = self.auth.password_login(email=email, password=password)
+        self.store.save(tokens)
+        return tokens
+
+    def logout(self) -> bool:
+        """Delete locally cached tokens.
+
+        KHDP's public ``/_api`` surface does not expose a refresh-token
+        revocation endpoint at the time of writing. The web SPA logs
+        out by clearing local state and letting the access token expire
+        naturally; we follow the same approach. Returns ``True`` if a
+        token was deleted, ``False`` if there was nothing to delete.
+        """
+        return self.store.delete(self.config.app_id or None)
+
+    def status(self) -> dict[str, Any]:
+        tokens = self.store.load(self.config.app_id or None)
+        if not tokens:
+            return {
+                "authenticated": False,
+                "app_id": self.config.app_id or None,
+            }
+        return {
+            "authenticated": True,
+            "app_id": tokens.app_id or self.config.app_id,
+            "expires_at": tokens.expires_at,
+            "is_expired": tokens.is_expired,
+            "has_refresh_token": tokens.refresh_token is not None,
+        }
+
+    def access_token(self) -> str:
+        """Return a valid access token, refreshing if necessary.
+
+        Raises :class:`AuthError` if the user has never logged in or the
+        refresh token has been revoked.
+        """
+        tokens = self.store.load(self.config.app_id or None)
+        if tokens is None:
+            raise AuthError("Not logged in. Run `khdp login` first.")
+        if not tokens.is_expired:
+            return tokens.access_token
+        if not tokens.refresh_token:
+            raise AuthError("Access token expired and no refresh token is available.")
+        log.debug("Refreshing expired access token for app %s", self.config.app_id)
+        refreshed = self.auth.refresh(tokens.refresh_token)
+        if not refreshed.refresh_token:
+            # Some KHDP environments may omit refresh_token on refresh
+            # -- keep the previous one.
+            refreshed.refresh_token = tokens.refresh_token
+        if not refreshed.app_id:
+            refreshed.app_id = tokens.app_id or self.config.app_id
+        self.store.save(refreshed)
+        return refreshed.access_token
+
+    def authed_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> httpx.Response:
+        """Issue an authenticated request against the KHDP API base.
+
+        ``path`` may be a full URL or a path relative to ``config.api_base``.
+        """
+        url = path if path.startswith(("http://", "https://")) else (
+            self.config.api_base.rstrip("/") + "/" + path.lstrip("/")
+        )
+        token = self.access_token()
+        with httpx.Client(timeout=30.0) as http:
+            return http.request(
+                method.upper(),
+                url,
+                params=params,
+                json=json,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "User-Agent": "khdp/0.1.0",
+                },
+            )

khdp/token_store.py

@@ -0,0 +1,140 @@
+"""Persistent storage for KHDP access + refresh tokens.
+
+Two backends:
+
+* OS keyring (macOS Keychain, Windows Credential Manager, Secret Service
+  on Linux) -- used when the optional ``keyring`` extra is installed and
+  the user has not opted out via config.
+* JSON file under the user config dir, written with ``0o600`` so other
+  local users cannot read it.
+
+Each token set is keyed by ``app_id`` so multiple KHDP-registered apps
+can coexist on one machine.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from khdp.oauth import TokenSet
+
+log = logging.getLogger(__name__)
+
+_KEYRING_SERVICE = "khdp"
+
+
+def _restrict_permissions(path: Path) -> None:
+    """Best-effort 0o600 on POSIX. On Windows, file ACLs default to user-only
+    in the per-user config dir, which is acceptable for a public client."""
+    if sys.platform == "win32":
+        return
+    try:
+        os.chmod(path, 0o600)
+    except OSError:  # pragma: no cover
+        log.warning("Could not chmod %s -- token file permissions may be permissive.", path)
+
+
+class TokenStore:
+    """Stores and retrieves :class:`TokenSet` objects keyed by ``app_id``."""
+
+    def __init__(self, token_dir: Path, *, use_keyring: bool = True) -> None:
+        self.token_dir = token_dir
+        self.token_dir.mkdir(parents=True, exist_ok=True)
+        self._file = token_dir / "tokens.json"
+        self._keyring = self._maybe_load_keyring() if use_keyring else None
+
+    @staticmethod
+    def _maybe_load_keyring() -> Any:
+        try:
+            import keyring  # type: ignore[import-not-found]
+        except ImportError:
+            return None
+        try:
+            keyring.get_keyring()
+        except Exception:  # pragma: no cover
+            return None
+        return keyring
+
+    # -- public API -------------------------------------------------------
+
+    def save(self, tokens: TokenSet) -> None:
+        key = tokens.app_id or "default"
+        if self._keyring is not None:
+            try:
+                self._keyring.set_password(
+                    _KEYRING_SERVICE, key, json.dumps(tokens.to_dict())
+                )
+                self._write_index(key)
+                return
+            except Exception as exc:  # pragma: no cover
+                log.warning("Keyring write failed (%s); falling back to file.", exc)
+        self._write_file(key, tokens.to_dict())
+
+    def load(self, app_id: str | None = None) -> TokenSet | None:
+        key = app_id or "default"
+        if self._keyring is not None:
+            try:
+                raw = self._keyring.get_password(_KEYRING_SERVICE, key)
+            except Exception:  # pragma: no cover
+                raw = None
+            if raw:
+                return TokenSet.from_dict(json.loads(raw))
+        data = self._read_file()
+        entry = data.get(key)
+        if not entry or not isinstance(entry, dict) or "access_token" not in entry:
+            return None
+        return TokenSet.from_dict(entry)
+
+    def delete(self, app_id: str | None = None) -> bool:
+        key = app_id or "default"
+        deleted = False
+        if self._keyring is not None:
+            try:
+                self._keyring.delete_password(_KEYRING_SERVICE, key)
+                deleted = True
+            except Exception:  # pragma: no cover
+                pass
+        data = self._read_file()
+        if key in data:
+            del data[key]
+            self._write_file_raw(data)
+            deleted = True
+        return deleted
+
+    def list_apps(self) -> list[str]:
+        return sorted(self._read_file().keys())
+
+    # -- internals --------------------------------------------------------
+
+    def _read_file(self) -> dict[str, Any]:
+        if not self._file.is_file():
+            return {}
+        try:
+            with self._file.open("r", encoding="utf-8") as fh:
+                data = json.load(fh)
+        except (OSError, ValueError):
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _write_file(self, key: str, payload: dict[str, Any]) -> None:
+        data = self._read_file()
+        data[key] = payload
+        self._write_file_raw(data)
+
+    def _write_index(self, key: str) -> None:
+        data = self._read_file()
+        # Don't store the secret in the index -- just record presence.
+        data[key] = {"_in_keyring": True}
+        self._write_file_raw(data)
+
+    def _write_file_raw(self, data: dict[str, Any]) -> None:
+        tmp = self._file.with_suffix(".json.tmp")
+        with tmp.open("w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2, sort_keys=True)
+        tmp.replace(self._file)
+        _restrict_permissions(self._file)

khdp-0.1.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: khdp
+Version: 0.1.0
+Summary: KHDP connector. CLI + MCP server for Korea Health Data Platform, with wrappers for Claude Code, OpenAI Codex, and Gemini.
+Project-URL: Homepage, https://github.com/KoreaHealthDataPlatform/KHDPConnector
+Project-URL: Repository, https://github.com/KoreaHealthDataPlatform/KHDPConnector
+Project-URL: Issues, https://github.com/KoreaHealthDataPlatform/KHDPConnector/issues
+Project-URL: Documentation, https://github.com/KoreaHealthDataPlatform/KHDPConnector#readme
+Author-email: Korea Health Data Platform <vital@snu.ac.kr>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: healthcare,khdp,mcp,oauth,omop,vitaldb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=24.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# KHDPConnector
+
+Auth + MCP connector for the **Korea Health Data Platform (KHDP)**.
+
+`khdp-connector` is a CLI-first Python package that handles login
+against the KHDP central auth API and exposes the resulting Bearer
+session through a Model Context Protocol (MCP) server. The same MCP
+server backs thin wrappers for **Claude Code**, **OpenAI Codex CLI**,
+and **Gemini CLI** so KHDP authentication looks the same across every
+coding-agent surface.
+
+> **Status:** alpha. APIs and tool names will move during Phase 0–1 of
+> the [PLAN.md](./PLAN.md) roadmap.
+
+## How it talks to KHDP
+
+The connector uses KHDP's password-based auth API. It implements two
+endpoints that are safe for headless / CLI use:
+
+* `POST /_api/oauth/login {appId, redirectUrl, mail, password}` →
+  `{accessToken, refreshToken, expireTime}`
+* `POST /_api/member/refresh-token {refreshToken}` →
+  same shape, rotated.
+
+All subsequent KHDP API calls go out with `Authorization: Bearer
+<accessToken>`.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Claude Code   ·   Codex CLI   ·   Gemini CLI   ·  …       │
+│        │              │              │                      │
+│        └──────── MCP (stdio JSON-RPC) ───────┐             │
+│                                              ▼             │
+│                                    khdp-connector (this)   │
+│                                              │             │
+│                                              ▼             │
+│   POST /_api/oauth/login          POST /_api/member/...    │
+│       (login + refresh)               (any KHDP endpoint)  │
+│                          khdp.net                          │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+pipx install khdp-connector            # recommended; isolates from system Python
+# or
+pip install khdp-connector
+# or with OS-keychain support:
+pipx install 'khdp-connector[keyring]'
+```
+
+## One-time configuration
+
+You need a KHDP-registered `app_id` (UUID) and a registered
+`redirect_url`. Drop them into a config file or env vars:
+
+```toml
+# ./khdp.local.toml
+app_id       = "00000000-0000-0000-0000-000000000000"
+redirect_url = "https://example.org/khdp-cli"
+api_base     = "https://khdp.net/_api"  # default; override for staging
+```
+
+…or:
+
+```bash
+export KHDP_APP_ID=00000000-0000-0000-0000-000000000000
+export KHDP_REDIRECT_URL=https://example.org/khdp-cli
+```
+
+> **Don't have an `app_id` yet?** Coordinate with the KHDP team to
+> register a CLI-class app. snuh.ai's public `app_id` won't work for
+> the CLI — its `redirect_url` allowlist excludes anything outside
+> `snuh.ai`.
+
+## CLI usage
+
+```bash
+khdp login          # prompts for email + password (or use --email / --password-stdin)
+khdp status         # is a token cached? when does it expire?
+khdp refresh        # force a refresh-token rotation
+khdp api GET /member/me              # authenticated KHDP API call
+khdp logout         # delete cached tokens
+khdp config         # print resolved configuration
+khdp mcp            # run the MCP server on stdio (for agents)
+```
+
+Configuration resolution order (highest first):
+
+1. `KHDP_*` environment variables
+2. `khdp.local.toml` in the current working directory
+3. `~/.config/khdp/config.toml` (or platform equivalent)
+4. Built-in defaults
+
+For non-interactive use:
+
+```bash
+KHDP_EMAIL=me@example.com khdp login --password-stdin <<< "$KHDP_PASSWORD"
+```
+
+## MCP server
+
+```bash
+khdp mcp
+# or
+khdp-mcp
+```
+
+Tools exposed on `stdio`:
+
+| Tool | Purpose |
+| --- | --- |
+| `khdp_auth_status`  | Is the user logged in? When does the token expire? |
+| `khdp_auth_refresh` | Rotate the refresh token to extend the session. |
+| `khdp_auth_logout`  | Delete locally cached tokens. |
+| `khdp_api_request`  | Authenticated HTTP passthrough to the KHDP API. |
+
+The MCP server **never** accepts a password through tool arguments —
+passwords would otherwise flow through the LLM context window. Login
+is initiated out-of-band via `khdp login` in the user's terminal; the
+MCP server just reads the resulting token cache.
+
+Future tools (per [PLAN.md](./PLAN.md)) will add dataset I/O, OMOP
+queries, audit log retrieval, and IRB result-pinning.
+
+## Wrappers
+
+The same MCP server backs a thin wrapper per agent platform.
+
+### Claude Code
+
+```bash
+claude mcp add khdp -- khdp mcp
+cp -r wrappers/claude-code/skills/khdp-auth ~/.claude/skills/
+```
+
+### OpenAI Codex CLI
+
+Append `wrappers/codex/config.example.toml` to `~/.codex/config.toml`,
+copy `wrappers/codex/AGENTS.md` to your project root.
+
+### Gemini CLI
+
+Merge `wrappers/gemini/settings.example.json` into
+`~/.gemini/settings.json`, or install as a Gemini Extension under
+`.gemini/extensions/khdp/`.
+
+## Development
+
+```bash
+git clone https://github.com/KoreaHealthDataPlatform/KHDPConnector.git
+cd KHDPConnector
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e '.[dev,keyring]'
+pytest
+```
+
+## Security model
+
+- **No secret in the binary.** The CLI ships only the user-provided
+  `app_id`. There is no embedded client secret.
+- **Password never leaves the local machine** unencrypted; it goes
+  only to KHDP's TLS endpoint, never to the LLM, never to the MCP
+  context. The MCP tool surface deliberately omits a password
+  argument.
+- **Per-app token isolation.** Multiple KHDP apps on one machine are
+  kept separate by `app_id`.
+- **Token storage.** OS keychain (Keychain / Credential Manager /
+  Secret Service) when the `keyring` extra is installed; otherwise a
+  JSON file with `0600` permissions in the platform user-config dir.
+- **No revocation endpoint exposed by KHDP today.** `khdp logout` only
+  clears local state. Access tokens expire naturally; refresh tokens
+  go invalid the next time the access token is rotated.
+
+## Roadmap
+
+See [PLAN.md](./PLAN.md) for the full roadmap. The current
+implementation covers Phase 1 (auth) and a generic API passthrough.
+Dataset I/O, OMOP analysis, and IRB-grade result pinning land in later
+phases.
+
+## License
+
+Apache 2.0. See [LICENSE](./LICENSE).

khdp-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+khdp/__init__.py,sha256=2whrZIg8tIOrK6F6Aq8mqnHoAmppFe87xsjTB8PmH48,416
+khdp/__main__.py,sha256=jPHFv0QHhnOHeQV5pfpZKPZRTCTc7NGiJ8BhvRi3Iz0,83
+khdp/cli.py,sha256=yoGYO5yc_k1jXGhXAcc7prP4FS0AlEsD5Z1MFEYih8o,7270
+khdp/config.py,sha256=Frh0Ly8hN47RpzrJhPx8LRJDbK8i07EebfikVFPhWMw,3529
+khdp/mcp_server.py,sha256=0E4ZbgCZhYvUhaSlyj8L8hco8yH4NPStUTV1dVgNLIo,7957
+khdp/oauth.py,sha256=r6PKbDbuIzjB_LwAMPpU25k8WCQqiN5sILtI8fpITbw,7788
+khdp/session.py,sha256=zZnt5k7hxZdlSIrgtJ3nq1jjkhD2g51B7WhZWwOuHog,4317
+khdp/token_store.py,sha256=pnOSqE2Bl939g9GZhEXDvUjqRo_Bqc6hO7z9eSfS0HE,4732
+khdp-0.1.0.dist-info/METADATA,sha256=kG1ZLDitT45sphNSlSLLkerSq6K4P2QDQ-DIS0QQ2VE,8098
+khdp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+khdp-0.1.0.dist-info/entry_points.txt,sha256=unVt4c8rRTrhl0h79KMWwbYdPy9yexTTRNOqWmLN4cQ,71
+khdp-0.1.0.dist-info/licenses/LICENSE,sha256=wrtc4PGK8P_oVbmq6DHfcSzzTLu7Yz1pur-P7zHWlh8,762
+khdp-0.1.0.dist-info/RECORD,,

khdp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

khdp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+khdp = khdp.cli:main
+khdp-mcp = khdp.mcp_server:main

khdp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Korea Health Data Platform (KHDP)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.