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