146 lines
3.7 KiB
Markdown
146 lines
3.7 KiB
Markdown
# 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エコシステムとの統合 |