# kuauth

kuauth は京都大学の SSO (シングルサインオン) サービスに対する統一 Python クライアントです。KULASIS（教務情報システム）、KULMS（学習管理システム）、MyKULINE（図書館 OPAC）、PandA（旧 LMS）の 4 つのサービスを単一のセッションで認証・操作できます。Shibboleth IdP や ECS CAS など各サービス固有の認証フローを自動処理し、ログイン後は標準的な `get()` / `post()` メソッドで各エンドポイントにアクセスできます。

ライブラリは httpx をベースとしており、HTTP/2 対応、自動リダイレクト追跡、レガシーシステムの文字エンコーディング（Shift_JIS）自動処理などを提供します。OTP（ワンタイムパスワード）認証には 3 つの方式（固定コード、TOTP シークレット、コールバック関数）をサポートしており、対話的スクリプトから cron/CI での無人実行まで柔軟に対応できます。

## KyotoUAuth - メイン認証クラス

`KyotoUAuth` は京都大学 IdP に対する認証セッションを管理するコアクラスです。ユーザー名、パスワード、OTP 情報を保持し、内部で httpx.Client を共有して各サービスクライアントに認証済みセッションを提供します。コンテキストマネージャとしても使用でき、リソースの自動クリーンアップが可能です。

```python
from kuauth import KyotoUAuth, KULASIS, KULMS, MyKULINE, PandA

# 方法1: TOTP シークレットを使用（cron/CI 向け自動実行）
auth = KyotoUAuth(
    username="a0123456",
    password="your-password",
    totp_secret="JBSWY3DPEHPK3PXP"  # 認証アプリ登録時の QR から取得
)
auth.login()

# 認証状態の確認
print(f"ログイン済み: {auth.is_authenticated}")  # True
print(f"ユーザー名: {auth.username}")  # a0123456

# 各サービスにアクセス
kulasis = KULASIS(auth)
kulms = KULMS(auth)
mykuline = MyKULINE(auth)
panda = PandA(auth)

# セッションのクローズ
auth.close()

# 方法2: コンテキストマネージャで自動クローズ
with KyotoUAuth(
    username="a0123456",
    password="your-password",
    otp_callback=lambda: input("OTP を入力: ")  # 対話的入力
) as auth:
    auth.login()
    print(KULMS(auth).get("/portal").text)

# 方法3: 固定 OTP コードを使用（1回限り）
auth = KyotoUAuth(
    username="a0123456",
    password="your-password",
    onetime_password="424242"  # 認証アプリに表示された6桁コード
).login()
```

## KULASIS - 教務情報システムクライアント

KULASIS は京都大学の教務情報システム（www.k.kyoto-u.ac.jp）にアクセスするためのクライアントです。Shibboleth 認証を経由し、レスポンスの文字エンコーディング（Shift_JIS/CP932）を自動的に処理します。時間割、成績、シラバスなどの教務情報を取得できます。

```python
from kuauth import KyotoUAuth, KULASIS

auth = KyotoUAuth(
    username="a0123456",
    password="your-password",
    totp_secret="JBSWY3DPEHPK3PXP"
).login()

kulasis = KULASIS(auth)

# トップページの取得（Shift_JIS は自動デコード）
top_page = kulasis.get("/student/la/top")
print(f"ステータス: {top_page.status_code}")
print(top_page.text[:500])  # 日本語が正しく表示される

# 学部生向けページ
undergraduate = kulasis.get("/student/u/t/top")
print(undergraduate.text)

# 任意のパスへの POST リクエスト
response = kulasis.post("/student/some/endpoint", data={"key": "value"})

# 絶対 URL も指定可能
response = kulasis.get("https://www.k.kyoto-u.ac.jp/student/la/top")

auth.close()
```

## KULMS - 学習管理システムクライアント

KULMS は Sakai ベースの学習管理システム（lms.gakusei.kyoto-u.ac.jp）にアクセスするためのクライアントです。Shibboleth コンテナ認証を経由し、コース情報、お知らせ、課題などを取得できます。

```python
from kuauth import KyotoUAuth, KULMS

auth = KyotoUAuth(
    username="a0123456",
    password="your-password",
    totp_secret="JBSWY3DPEHPK3PXP"
).login()

kulms = KULMS(auth)

# ポータルページの取得
portal = kulms.get("/portal")
print(portal.text)

# サイト一覧（コース一覧）の取得
sites = kulms.get("/direct/site.json")
print(sites.json())

# お知らせの取得（JSON API）
announcements = kulms.get("/direct/announcement/user.json")
for item in announcements.json().get("announcement_collection", []):
    print(f"- {item.get('title')}")

# 特定サイトの情報取得
site_id = "~a0123456"  # ユーザーのマイワークスペース
site_info = kulms.get(f"/direct/site/{site_id}.json")
print(site_info.json())

auth.close()
```

## MyKULINE - 図書館 OPAC クライアント

MyKULINE は京都大学図書館の OPAC システム（kuline.kulib.kyoto-u.ac.jp）にアクセスするためのクライアントです。Shibboleth 認証に加えて同意ページの処理と EPPN 交換フローを自動処理します。蔵書検索、貸出状況確認、予約などが可能です。

```python
from kuauth import KyotoUAuth, MyKULINE

auth = KyotoUAuth(
    username="a0123456",
    password="your-password",
    totp_secret="JBSWY3DPEHPK3PXP"
).login()

mykuline = MyKULINE(auth)

# 検索ページの取得
search_page = mykuline.get("/opac/opac_search/")
print(search_page.text)

# セキュアページへのアクセス（認証が必要なページ）
secure_page = mykuline.get("/opac/opac_secure/opac_search/")
print(secure_page.text)

# 蔵書検索の実行
search_results = mykuline.get("/opac/opac_search/", params={
    "searchWord": "Python",
    "searchTarget": "title"
})
print(search_results.text)

# 貸出状況の確認
loan_status = mykuline.get("/opac/opac_secure/opac_loan/")
print(loan_status.text)

auth.close()
```

## PandA - 旧学習管理システムクライアント

PandA は ECS が運用する旧 Sakai LMS（panda.ecs.kyoto-u.ac.jp）にアクセスするためのクライアントです。Shibboleth ではなく ECS 独自の CAS サーバーで認証するため、OTP は不要でユーザー名とパスワードのみで認証できます。

```python
from kuauth import KyotoUAuth, PandA

# PandA は OTP 不要（CAS 認証のため）
auth = KyotoUAuth(
    username="a0123456",
    password="your-password"
    # totp_secret は不要
)
# login() を明示的に呼ばなくても、PandA アクセス時に CAS 認証が実行される

panda = PandA(auth)

# ポータルページの取得
portal = panda.get("/portal")
print(portal.text)

# サイト情報の取得
sites = panda.get("/direct/site.json")
print(sites.json())

# 課題一覧の取得
assignments = panda.get("/direct/assignment/my.json")
print(assignments.json())

# リソースの取得
resources = panda.get("/direct/content/site/~a0123456.json")
print(resources.json())

auth.close()
```

## 例外処理

kuauth は認証やサービスアクセスの各段階で適切な例外を発生させます。`KuauthError` を基底クラスとして、認証失敗、OTP 要求、同意要求、SP アクセスエラーを区別できます。

```python
from kuauth import (
    KyotoUAuth, KULMS,
    KuauthError,
    AuthenticationError,
    OTPRequiredError,
    ConsentRequiredError,
    SPAccessError
)

try:
    # OTP 設定なしでログインを試行
    auth = KyotoUAuth(
        username="a0123456",
        password="wrong-password"
    ).login()
except OTPRequiredError as e:
    # OTP が必要だが設定されていない
    print(f"OTP が必要です: {e}")
except AuthenticationError as e:
    # パスワードまたは OTP が拒否された
    print(f"認証エラー: {e}")
except KuauthError as e:
    # その他の kuauth エラー
    print(f"エラー: {e}")

# サービスアクセス時のエラー処理
try:
    auth = KyotoUAuth(
        username="a0123456",
        password="your-password",
        totp_secret="JBSWY3DPEHPK3PXP"
    ).login()

    kulms = KULMS(auth)
    response = kulms.get("/nonexistent/path")
    response.raise_for_status()
except SPAccessError as e:
    # Shibboleth ハンドオフ失敗
    print(f"サービスアクセスエラー: {e}")
except ConsentRequiredError as e:
    # 同意ページの自動処理失敗
    print(f"同意が必要です: {e}")
finally:
    auth.close()
```

## 複数サービスの同時利用

kuauth の主な利点は単一の認証セッションで複数の京大サービスに同時アクセスできることです。一度のログインで KULASIS、KULMS、MyKULINE、PandA すべてにアクセスでき、セッション管理のオーバーヘッドを最小化できます。

```python
from kuauth import KyotoUAuth, KULASIS, KULMS, MyKULINE, PandA

# 単一の認証セッションを作成
with KyotoUAuth(
    username="a0123456",
    password="your-password",
    totp_secret="JBSWY3DPEHPK3PXP"
) as auth:
    auth.login()

    # 全サービスのクライアントを初期化
    kulasis = KULASIS(auth)
    kulms = KULMS(auth)
    mykuline = MyKULINE(auth)
    panda = PandA(auth)

    # 並行してデータを取得
    print("=== KULASIS ===")
    print(kulasis.get("/student/la/top").text[:200])

    print("\n=== KULMS ===")
    kulms_portal = kulms.get("/portal")
    print(kulms_portal.text[:200])

    print("\n=== MyKULINE ===")
    print(mykuline.get("/opac/opac_search/").text[:200])

    print("\n=== PandA ===")
    print(panda.get("/portal").text[:200])

# コンテキストマネージャ終了時に自動クローズ
```

## まとめ

kuauth は京都大学の複数の Web サービス（KULASIS、KULMS、MyKULINE、PandA）に対して統一的な認証とアクセス手段を提供するライブラリです。Shibboleth IdP の複雑なフロー（パスワード認証、OTP、同意ページ、SAML レスポンス）を自動処理し、開発者はシンプルな `get()` / `post()` メソッドでサービスを利用できます。TOTP シークレットによる無人実行、コールバック関数による対話的入力、固定 OTP コードの 3 方式をサポートしており、様々なユースケースに対応できます。

主な統合パターンとしては、(1) 成績・時間割の自動取得スクリプト、(2) LMS のお知らせや課題を監視する Bot、(3) 図書館の貸出状況通知システム、(4) 複数サービスのデータを統合するダッシュボードアプリケーションなどが考えられます。HAR ファイルから URL とフォーム構造を特定すれば、ライブラリが提供しない個別エンドポイントも `post()` メソッドで自由に呼び出せる設計になっています。