card/docs/ATPROTO.md

atproto連携ガイド

概要

ai.cardは、atproto（AT Protocol）と完全に統合されており、以下の機能を提供します：

1. atproto認証: DIDベースの分散型認証
2. データ主権: カードデータをユーザーのPDSに保存
3. 相互運用性: 他のatproto対応アプリとの連携

認証フロー

1. ログイン

// フロントエンド
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

{
  "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" }
        }
      }
    }
  }
}

データ同期

# カードを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エコシステムとの統合