add claude

2025-06-01 21:39:53 +09:00
parent 3459231bba
commit 4246f718ef
80 changed files with 7249 additions and 0 deletions
--- a/docs/ATPROTO.md
+++ b/docs/ATPROTO.md
@ -0,0 +1,146 @@
+# atproto連携ガイド
+
+## 概要
+
+ai.cardは、atproto（AT Protocol）と完全に統合されており、以下の機能を提供します：
+
+1. **atproto認証**: DIDベースの分散型認証
+2. **データ主権**: カードデータをユーザーのPDSに保存
+3. **相互運用性**: 他のatproto対応アプリとの連携
+
+## 認証フロー
+
+### 1. ログイン
+
+```javascript
+// フロントエンド
+const response = await authService.login(identifier, password);
+// identifier: ハンドル（user.bsky.social）またはDID
+// password: アプリパスワード（メインパスワードではない）
+```
+
+### 2. アプリパスワードの作成
+
+1. https://bsky.app/settings/app-passwords にアクセス
+2. 新しいアプリパスワードを作成
+3. ai.cardでそのパスワードを使用
+
+### 3. セッション管理
+
+- JWTトークンで24時間有効
+- Cookieとヘッダーの両方をサポート
+- 自動更新機能なし（再ログインが必要）
+
+## データ保存
+
+### カードコレクションのLexicon
+
+```json
+{
+  "lexicon": 1,
+  "id": "ai.card.collection",
+  "defs": {
+    "main": {
+      "type": "record",
+      "record": {
+        "type": "object",
+        "properties": {
+          "cardId": { "type": "integer" },
+          "cp": { "type": "integer" },
+          "status": { "type": "string" },
+          "skill": { "type": "string" },
+          "obtainedAt": { "type": "string" },
+          "isUnique": { "type": "boolean" },
+          "uniqueId": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+### データ同期
+
+```bash
+# カードをPDSに同期
+POST /api/v1/sync/cards
+{
+  "atproto_session": "session-string-from-login"
+}
+
+# PDSからインポート
+POST /api/v1/sync/import
+
+# PDSにエクスポート
+POST /api/v1/sync/export
+```
+
+## セキュリティ
+
+### 1. 認証情報の取り扱い
+
+- **メインパスワードは使用しない**: 必ずアプリパスワードを使用
+- **セッション文字列の保護**: atprotoセッションは暗号化して保存
+- **HTTPS必須**: 本番環境では必ずHTTPS経由で通信
+
+### 2. データ検証
+
+- サーバー側でカードデータの整合性をチェック
+- uniqueカードはグローバルレジストリで重複防止
+- PDSのデータも信頼せず、常に検証
+
+### 3. 権限管理
+
+現在の制限：
+- ユーザーはPDSのデータを自由に編集可能
+- OAuth 2.1 scope実装待ち
+
+対策：
+- サーバー側検証で不正データを無効化
+- ゲームプレイ時は常にサーバーチェック
+
+## APIエンドポイント
+
+### 認証
+
+```
+POST   /api/v1/auth/login      - ログイン
+POST   /api/v1/auth/logout     - ログアウト
+GET    /api/v1/auth/verify     - セッション確認
+POST   /api/v1/auth/verify-did - DID検証（公開）
+```
+
+### 同期
+
+```
+POST   /api/v1/sync/cards      - 双方向同期
+POST   /api/v1/sync/export     - PDSへエクスポート
+POST   /api/v1/sync/import     - PDSからインポート
+GET    /api/v1/sync/verify/:id - カード所有確認
+```
+
+## トラブルシューティング
+
+### ログインできない
+
+1. アプリパスワードを使用しているか確認
+2. ハンドルまたはDIDが正しいか確認
+3. PDSが稼働しているか確認
+
+### データが同期されない
+
+1. atprotoセッションが有効か確認
+2. PDSの容量制限を確認
+3. ネットワーク接続を確認
+
+### カードが表示されない
+
+1. `/api/v1/sync/import`でPDSからインポート
+2. ブラウザキャッシュをクリア
+3. 再ログイン
+
+## 今後の予定
+
+1. **OAuth 2.1対応**: より細かい権限管理
+2. **リアルタイム同期**: WebSocketでの即時反映
+3. **他アプリ連携**: atprotoエコシステムとの統合