Skip to content

Security: mirute02/limitchecker

Security

docs/security.md

セキュリティ / プライバシー方針

本リポジトリは最終的に GitHub で公開する。当面は private だが、private → public の切り替え時に git 履歴の全コミットがそのまま公開されるため、「公開直前に掃除する」方式は成立しない。 1コミット目から本方針を適用する。

万一コミットしてしまった秘密は、履歴を書き換えても漏れたものとして扱い、必ず再発行する。

1. リポジトリと APK に入れないもの

対象 理由
hub の認証トークン これ1つで全マシンの状態を読める
Tailscale のアドレス・ホスト名 内部ネットワーク構成の露出
マシン名の実値(設定例を除く) 所属や環境の推測材料になる
署名鍵 (*.jks / *.keystore) 同一パッケージ名の偽アプリを配布可能になる
google-services.json 等 プロジェクト ID と API キーを含む
statusLine / フックのキャプチャ結果 セッション ID と作業ディレクトリを含む
作業マシンの絶対パス ユーザ名・顧客名・案件名が混ざる

実値はすべて .env(gitignore 済み)に置き、リポジトリには .env.example のみ置く。

コミットメールは GitHub の noreply アドレスを使う(本リポジトリの user.email に設定済み)。 実際のメールアドレスを履歴に残さないため。

2. 収集データの最小化

このアプリは「残量」と「エージェントが止まっているか」だけを知りたい。 それ以上は取得しない。設計上の不変条件として扱う。

  • 会話内容は一切読まない・送らない。 ~/.claude/projects/**/*.jsonl を読む場合も 集計値のみを取り出し、本文・プロンプト・ファイル名を hub へ送らない
  • 作業ディレクトリはフルパスを送らない。 既定は basename のみ (<ホーム>/clients/<顧客名>/repo → repo)。送信しない設定も用意する
  • セッション ID は hub 内部のキーに留める。 通知本文やウィジェットに表示しない
  • マシン名はユーザが設定した短いラベルのみ。 ホスト名を自動取得しない

2.5 アカウント認証情報に触れない(不変条件)

残量はアカウントに紐づくが、limitchecker はアカウントの認証情報を一切扱わない。

  • ~/.claude/.credentials.json(Claude Code の OAuth トークン)を読まない・コピーしない・送らない
  • Codex CLI の認証情報も同様に読まない
  • Anthropic / OpenAI の API キーを要求しない。設定項目としても用意しない

残量は、すでにログイン済みの CLI が取得した結果を statusLine とフック経由で受け取るだけで足りる。 認証は CLI 側が持ち、limitchecker はその出力を見る立場に徹する。

この結果、リポジトリを clone した第三者が得るのは「自分の CLI の出力を自分で見る仕組み」だけになり、 アプリ自体が認証情報の保管場所にならない。Android アプリが持つ秘密は hub のトークン1つに限られる。

アカウントの同定

複数マシンの残量を1組に畳むにはアカウントの同定が必要だが、 メールアドレスや組織 ID を識別子に使わない。 ユーザが設定で宣言したラベル (LIMITCHECKER_CLAUDE_ACCOUNT 等)で突き合わせる。個人情報を送らずに済み、 仕事用と個人用のアカウント併用も表現できる。

3. hub 実装ルール

  • 待ち受けアドレス: 既定 127.0.0.1。Tailscale アドレスは明示設定時のみ。 0.0.0.0 はコード側で拒否する(設定ミスによる全世界公開を防ぐ)
  • 認証: 固定トークンを Authorization ヘッダで受ける。比較は hmac.compare_digest で定数時間比較する(タイミング攻撃対策)
  • 既定トークンを持たない: 未設定なら起動を拒否する。「とりあえず動く」状態を作らない
  • ログ: Authorization ヘッダとトークンを出力しない。リクエストボディもそのまま出さない
  • 入力検証: machine id / session id は [A-Za-z0-9_-]{1,64} に制限する。 ファイル名やログに使う値なので、パストラバーサルとログ汚染を防ぐ
  • エラー応答: 内部パスやスタックトレースを返さない

3.5 接続コード(ペアリング)

43文字のトークンを手で転記させないため、6桁のコードで一度だけ交換する (POST /pair)。この経路だけは認証なしで受ける。トークンを渡すための 入口なので、認証を要求したら意味がない。

短いコードは総当たりが効く。次の4つを必ず揃える。

防御 内容
有効期限 5分。過ぎたら記録ごと消す
試行回数 5回で打ち切り、記録を消す。誤りも回数に数える(数えないと無制限に試せる)
使い捨て 成功したら即座に消す
平文を保存しない コードは保存せず、SHA-256 のハッシュを hmac.compare_digest で比較する

失敗の理由を返さない。 期限切れと誤りを区別させると、 有効なコードが存在するかどうかを外から探れてしまう。

POST /pair のボディ上限は 1KB。コードは数字4〜12桁に限る。

4. Android 実装ルール

  • トークンは Android Keystore の鍵で暗号化して保存する。 平文で SharedPreferences や DataStore に置かない。鍵は端末内に留まり、対応端末では TEE / StrongBox に格納されるため、アプリ領域を吸い出されても復号できない。 Keystore が使えない端末では保存せず、その旨を画面に出す(平文にフォールバックしない)
  • 鍵に setUserAuthenticationRequired は付けない。画面ロック中もウィジェットが 残量を取りに行くため。ロック中に読めないと機能が成立しない
  • トークンは入力欄で伏せ字にし、保存後に読み返して表示しない。ログにも例外にも出さない
  • android:allowBackup="false" と dataExtractionRules で端末バックアップ対象から除外する
  • 全コンポーネントを android:exported="false"(ウィジェットのレシーバ等、必要なものを除く)
  • 平文 HTTP は Tailscale 内に限るため network_security_config で接続先ホストを限定する
  • スクリーンショットを課題に添付する際は、マシン名・パス・残量以外を写さない
  • 依存を追加したら、ビルド後の APK で権限と公開コンポーネントを実測する。 マニフェストを読むだけでは足りない(実際に WorkManager が追加する4権限を見落とした)

5. リポジトリ運用

  • .gitignore を先に置く(実施済み)
  • .githooks/pre-commit で、秘密らしき文字列と絶対パスの混入をコミット前に検出する (git config core.hooksPath .githooks で有効化)
  • ドキュメント・テストのサンプル JSON は合成値のみ。実機の出力を貼らない
  • public 化の直前に、履歴全体を対象としたスキャンを1回実施する

There aren't any published security advisories