True passkey implement
This commit is contained in:
qingjie.du
195
PASSKEY.md
Normal file
195
PASSKEY.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# MCPletA2A Passkey 認証
|
||||
|
||||
真正の WebAuthn/FIDO2 Passkey 認証。外部 amiPro FIDO2 サーバーと連携。
|
||||
|
||||
## アーキテクチャ
|
||||
|
||||
```
|
||||
Host (Node.js)
|
||||
│
|
||||
├── PasskeyServer ──→ ブラウザページ起動（自己完結型フロー）
|
||||
│ │
|
||||
│ ├── userId 入力
|
||||
│ ├── FIDO2 サーバーにユーザー確認
|
||||
│ ├── 未登録 → 自動で Passkey 登録（Touch ID 等）
|
||||
│ ├── 認証（Touch ID 等）
|
||||
│ └── 結果を Host に HTTP callback
|
||||
│
|
||||
├── PasskeyPlatformService ──→ AmiProFIDO2Client ──→ FIDO2 Server
|
||||
│ (統一管理: 登録/認証/セッション) (https://fido2.epk.amipro.me)
|
||||
│
|
||||
└── PasskeyAPIServer (REST proxy, port 8443)
|
||||
/api/passkey/attestation/options
|
||||
/api/passkey/attestation/result
|
||||
/api/passkey/assertion/options
|
||||
/api/passkey/assertion/result
|
||||
```
|
||||
|
||||
## ファイル構成
|
||||
|
||||
```
|
||||
platform_impl/src/passkey/
|
||||
├── amipro-fido2-client.ts # amiPro FIDO2 サーバー REST クライアント
|
||||
├── platform-service.ts # 統一 Passkey 管理サービス
|
||||
├── passkey-server.ts # ブラウザ WebAuthn 式典サーバー（自己完結型ページ）
|
||||
├── api-server.ts # REST API プロキシ
|
||||
├── index.ts # エクスポート
|
||||
├── storage.ts # IPasskeyStorage インターフェース (ローカル用、予備)
|
||||
├── challenge-manager.ts # チャレンジ管理 (ローカル用、予備)
|
||||
├── fido2-backend.ts # FIDO2 検証 (ローカル用、予備)
|
||||
├── client.ts # ブラウザ側 WebAuthn クライアント
|
||||
└── mcplet-helper.ts # MCPlet ツール統合ヘルパー
|
||||
```
|
||||
|
||||
## 設定
|
||||
|
||||
```yaml
|
||||
# reference_impl/config/reference.yaml
|
||||
passkey:
|
||||
mode: https # localhost | https
|
||||
rpId: a2a-demo.mcplet.ai # WebAuthn Relying Party ID
|
||||
fido2ServerUrl: https://fido2.epk.amipro.me # 外部 FIDO2 サーバー
|
||||
apiPort: 8443 # REST API ポート
|
||||
```
|
||||
|
||||
## ユーザーフロー
|
||||
|
||||
### 新規ユーザー（未登録）
|
||||
|
||||
```
|
||||
ブラウザページ起動
|
||||
↓
|
||||
1. userId 入力（または自動入力）
|
||||
↓
|
||||
2. FIDO2 サーバーに問い合わせ → "ユーザーが存在しません"
|
||||
↓
|
||||
3. 自動で登録モードに切替 → Touch ID 等で Passkey 登録
|
||||
↓
|
||||
4. 登録成功 → 自動で認証に進む
|
||||
↓
|
||||
5. Touch ID 等で認証
|
||||
↓
|
||||
6. session + username を Host に返却
|
||||
```
|
||||
|
||||
### 既存ユーザー（登録済み）
|
||||
|
||||
```
|
||||
ブラウザページ起動
|
||||
↓
|
||||
1. userId 入力（または自動入力）
|
||||
↓
|
||||
2. FIDO2 サーバーに問い合わせ → OK（allowCredentials 返却）
|
||||
↓
|
||||
3. Touch ID 等で認証
|
||||
↓
|
||||
4. session + username を Host に返却
|
||||
```
|
||||
|
||||
## amiPro FIDO2 Server API
|
||||
|
||||
| エンドポイント | 説明 |
|
||||
|--------------|------|
|
||||
| `POST /attestation/options` | 登録オプション取得（challenge + publicKey params） |
|
||||
| `POST /attestation/result` | 登録結果送信（attestationObject 検証） |
|
||||
| `POST /assertion/options` | 認証オプション取得（challenge + allowCredentials） |
|
||||
| `POST /assertion/result` | 認証結果送信（signature 検証） |
|
||||
| `POST /usr/validsession` | セッション検証 |
|
||||
| `POST /usr/delsession` | ログアウト |
|
||||
|
||||
エンコーディング: Base64URL（dfido2-lib.js 互換）
|
||||
|
||||
## 開発環境セットアップ
|
||||
|
||||
### 1. /etc/hosts
|
||||
|
||||
```
|
||||
127.0.0.1 a2a-demo.mcplet.ai
|
||||
```
|
||||
|
||||
### 2. 自己署名証明書の生成
|
||||
|
||||
```bash
|
||||
cd platform_impl
|
||||
mkdir -p certs
|
||||
openssl req -x509 -newkey rsa:2048 \
|
||||
-keyout certs/key.pem -out certs/cert.pem \
|
||||
-days 365 -nodes -subj "/CN=a2a-demo.mcplet.ai" \
|
||||
-addext "subjectAltName=DNS:a2a-demo.mcplet.ai,IP:127.0.0.1"
|
||||
```
|
||||
|
||||
### 3. 証明書の信頼（macOS）
|
||||
|
||||
```bash
|
||||
# Admin 権限あり
|
||||
sudo security add-trusted-cert -d -r trustRoot \
|
||||
-k /Library/Keychains/System.keychain certs/cert.pem
|
||||
|
||||
# Admin 権限なし（Edge で有効、Chrome は完全再起動が必要）
|
||||
security add-trusted-cert -r trustRoot \
|
||||
-k ~/Library/Keychains/login.keychain-db certs/cert.pem
|
||||
```
|
||||
|
||||
### 4. テスト
|
||||
|
||||
```bash
|
||||
cd platform_impl
|
||||
|
||||
# API 接続テストのみ
|
||||
npx tsx test-passkey.ts
|
||||
|
||||
# 統一フロー（自動登録+認証）
|
||||
npx tsx test-passkey.ts test a2a-test-user
|
||||
|
||||
# 新規ユーザー（userId 手入力）
|
||||
npx tsx test-passkey.ts new
|
||||
```
|
||||
|
||||
## 重要な注意事項
|
||||
|
||||
### WebAuthn rpId とドメインの一致
|
||||
|
||||
WebAuthn は rpId がブラウザページのドメインと一致することを要求する。
|
||||
`http://127.0.0.1` のページでは rpId `a2a-demo.mcplet.ai` は使用不可。
|
||||
必ず /etc/hosts + HTTPS（または Chrome flag）で一致させること。
|
||||
|
||||
### Passkey のブラウザ間共有
|
||||
|
||||
macOS の Touch ID / iCloud キーチェーンで作成された Passkey はブラウザ間で共有される。
|
||||
ただし Chrome の `--user-data-dir=tmp` で起動すると隔離プロファイルとなり、
|
||||
プラットフォーム Passkey にアクセスできない。常にデフォルトブラウザを使用すること。
|
||||
|
||||
### 本番環境 vs 開発環境
|
||||
|
||||
| 項目 | 開発環境 | 本番環境 |
|
||||
|------|---------|---------|
|
||||
| 証明書 | 自己署名 + キーチェーン信頼 | 正規 SSL 証明書 |
|
||||
| rpId | a2a-demo.mcplet.ai (hosts) | 実ドメイン (DNS) |
|
||||
| FIDO2 server | fido2.epk.amipro.me | 同 or 専用サーバー |
|
||||
| `PASSKEY_DEV_HTTP` | 設定可（Chrome flag 必要） | 不使用 |
|
||||
|
||||
## Platform 統合
|
||||
|
||||
### base-agent.ts での Passkey 呼び出し
|
||||
|
||||
```typescript
|
||||
// action 型ツールで auth.required === 'passkey' の場合、自動で仪式を開始
|
||||
if (tool.meta.mcpletType === 'action' && tool.meta.auth?.required === 'passkey') {
|
||||
const assertion = await this.performPasskeyCeremony(tool);
|
||||
if (!assertion) {
|
||||
return this.errorResult(toolName, 'Passkey authentication failed', 'AUTH_FAILED');
|
||||
}
|
||||
callParams = { ...args, _mcplet_auth: assertion };
|
||||
}
|
||||
```
|
||||
|
||||
### MCPletHost 初期化
|
||||
|
||||
```typescript
|
||||
if (config.passkey) {
|
||||
this.passkeyPlatformService = new PasskeyPlatformService(rpId, fido2ServerUrl);
|
||||
this.passkeyAPIServer = new PasskeyAPIServer(platformService, rpId, origin);
|
||||
this.passkeyAPIServer.start(config.passkey.apiPort || 8443);
|
||||
this.passkeyServer = new PasskeyServer(rpId, fido2ServerUrl);
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user