メインコンテンツまでスキップ

ゲスト認証モデル

メルカリ公式アプリの検索は ログインなし でも動きます。本ライブラリも同じ前提です。

何が「ゲストの身元」か​

要素役割保存場所（既定）
RSA 秘密鍵リクエストごとの DPoP JWT 署名dpop_key.pem + .meta.json
device_uuidDPoP クレーム / X-DEVICE-ID上記 meta + session.json
access_token (PFAT)任意の Bearer。無くても検索可session.json

検索に必須なのは DPoP 側です。データセンター IP などから PFAT を取れなくても、 mode: "dpop_only" のまま検索できます。

ライブラリがやること​

MercariClient() を作ると:

  1. session_path から MercariSession を読む（無ければ空）
  2. keystore_path から DPoP 鍵を load_or_create（無ければ生成して保存）
  3. ライブ API 呼び出し前に ensure_guest_auth()（auto_bootstrap=True 時）
    • 期限切れ Bearer は送らない（クリアして DPoP のみ）
    • PFAT はベストエフォート（失敗しても ok: True）
    • セッションをディスクに保存

呼び出し側が トークンを手で組み立てる必要はありません。

import mercari

c = mercari.MercariClient()  # 既定パスに identity を永続化
print(c.auth_status())
# guest_ready=True, mode=dpop_only | bearer, usable=True

c.ensure_guest_auth(try_pfat=False)  # 明示的に DPoP だけ用意

長時間・同じインスタンス​

同じプロセス内では 同じ MercariClient インスタンス を使い回してください。

プロセスを跨ぐ場合は 同じパス を指定します:

from pathlib import Path

base = Path.home() / ".mercari_guest"
c = mercari.MercariClient(
    session_path=base / "session.json",
    keystore_path=base / "dpop_key.pem",
)

2 回目以降も device_uuid は同じ鍵ストアから復元されます。

秘密情報の扱い​

  • session.json にトークンが載ることがある → リポジトリにコミットしない
  • ensure_guest_session の steps ログは トークンを redact する
  • 通常の成功パスでフル Bearer / フル JWT を print しない

購入などログイン必須 API は別途 set_token / キャプチャ import が必要です（検索ゲストとは別レイヤ）。

ステータス確認​

st = c.auth_status()
# has_dpop_key, guest_ready, bearer_ready, usable, mode, device_uuid, expired, ...
フィールド意味
guest_readyDPoP 鍵 + device uuid あり → ゲスト検索可能
bearer_ready未期限切れ access_token あり
usable検索できる（guest または bearer）
mode"bearer" / "dpop_only" / "none"