Skip to content

Commit e8b39bb

Browse files
ginjapanginjapan
committed
Initial setup: OIDC provider with Koa.js, interaction routes, and configuration
1 parent 779a141 commit e8b39bb

File tree

9 files changed

+5193
-5238
lines changed

9 files changed

+5193
-5238
lines changed

‎docs/requirements/general_specs.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# General Specifications
2+
3+
## System Architecture
4+
5+
### Components
6+
1. **OIDC Provider (node-oidc-provider)**
7+
- Handles OIDC authentication flows
8+
- Issues ID tokens containing DIDs
9+
- Manages client registrations and interactions
10+
11+
2. **Frontend Server (Next.js)**
12+
- Server-side rendered login interface
13+
- Handles Web3Auth MPC initialization
14+
- Manages DID generation and VC issuance
15+
- Processes OIDC interactions
16+
17+
3. **Web3Auth MPC Core Kit**
18+
- Generates and manages Ed25519 key shares
19+
- Implements 2-of-3 threshold signature scheme
20+
- Provides secure key management without full key reconstruction
21+
22+
4. **Sphereon SSI SDK (Veramo)**
23+
- DID generation and management
24+
- VC issuance and verification
25+
- Custom KMS integration with Web3Auth MPC
26+
27+
### Data Flow
28+
1. Client initiates OIDC authorization request
29+
2. Frontend server renders login form
30+
3. User authenticates and triggers MPC key generation
31+
4. DID is generated using MPC key material
32+
5. Optional VC issuance occurs
33+
6. OIDC interaction completes with DID in ID token
34+
35+
## Technical Specifications
36+
37+
### Key Management
38+
- **Key Type**: Ed25519
39+
- **Threshold Scheme**: 2-of-3
40+
- **Share Distribution**:
41+
- Server-side share
42+
- Client-side share
43+
- Cloud backup share
44+
- **Security Requirements**:
45+
- No full key reconstruction
46+
- Secure share storage
47+
- Encrypted communication between shares
48+
49+
### DID Specifications
50+
- **Method**: did:key
51+
- **Key Type**: Ed25519
52+
- **Format**: Base58 encoded public key
53+
- **Storage**: Persistent database with user association
54+
55+
### VC Specifications
56+
- **Format**: JWT VC
57+
- **Issuer**: User's DID
58+
- **Optional Claims**:
59+
- Login proof
60+
- Authentication timestamp
61+
- Additional user attributes
62+
63+
### OIDC Integration
64+
- **ID Token Claims**:
65+
```json
66+
{
67+
"sub": "did:key:z6Mkw...",
68+
"did": "did:key:z6Mkw..."
69+
}
70+
```
71+
- **Required Endpoints**:
72+
- `/authorize`
73+
- `/interaction/:uid/login`
74+
- `/token`
75+
76+
## Implementation Details
77+
78+
### Custom KMS Implementation
79+
```typescript
80+
interface Web3AuthMpcKMS {
81+
// Key management
82+
generateKey(): Promise<Key>;
83+
getKey(keyRef: string): Promise<Key>;
84+
85+
// Signing operations
86+
sign(data: Buffer, keyRef: string): Promise<Buffer>;
87+
verify(data: Buffer, signature: Buffer, keyRef: string): Promise<boolean>;
88+
}
89+
```
90+
91+
### DID Generation Flow
92+
1. Initialize Web3Auth MPC
93+
2. Generate key shares
94+
3. Create did:key using public key material
95+
4. Store DID and key references
96+
5. Return DID for OIDC integration
97+
98+
### VC Issuance Flow
99+
1. Prepare VC claims
100+
2. Sign VC using MPC shares
101+
3. Verify VC signature
102+
4. Store VC if needed
103+
5. Return signed VC
104+
105+
## Security Considerations
106+
107+
### Key Share Management
108+
- Secure storage of server-side share
109+
- Encrypted client-side share storage
110+
- Secure backup share management
111+
- Regular key rotation policies
112+
113+
### Communication Security
114+
- TLS for all network communications
115+
- Encrypted share exchange
116+
- Secure session management
117+
- Protection against replay attacks
118+
119+
### Access Control
120+
- Role-based access control for key operations
121+
- Audit logging for all key operations
122+
- Rate limiting for authentication attempts
123+
- Session timeout policies
124+
125+
## Testing Requirements
126+
127+
### Unit Tests
128+
- MPC key generation and management
129+
- DID generation and verification
130+
- VC issuance and verification
131+
- OIDC token generation
132+
133+
### Integration Tests
134+
- End-to-end authentication flow
135+
- MPC share communication
136+
- DID integration with OIDC
137+
- VC issuance and verification
138+
139+
### Security Tests
140+
- Key share security
141+
- Communication encryption
142+
- Access control enforcement
143+
- Session management
144+
145+
## Deployment Considerations
146+
147+
### Environment Requirements
148+
- Node.js runtime
149+
- Secure key storage
150+
- Database for DID/VC persistence
151+
- Network access for MPC communication
152+
153+
### Scaling Considerations
154+
- Horizontal scaling of OIDC provider
155+
- Load balancing for frontend servers
156+
- Database sharding for DID storage
157+
- Caching strategies for VC verification
158+
159+
### Monitoring and Logging
160+
- Authentication success/failure rates
161+
- Key operation metrics
162+
- DID generation statistics
163+
- VC issuance tracking

‎docs/requirements/requirments.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
## 🎯 目的（Goal）
2+
3+
OIDCログインフロー中に、秘密鍵を一切復元せずに安全にEd25519署名を行う構成を構築する。
4+
Web3AuthのMPC Core Kitを活用し、Sphereon SSI SDK（Veramoベース）と統合して、DID生成・VC発行・OIDCログインまでを完結させる。
5+
ログイン後にはDIDをOIDCのIDトークンに含める。
6+
7+
---
8+
9+
## ⚙️ 使用する技術要素（Tech Stack）
10+
11+
- **OIDC Provider**: node-oidc-provider
12+
- **Frontend**: SSR対応（例：Next.js）
13+
- **DID/VC管理**: Sphereon SSI SDK（Veramoベース）
14+
- **KMS**: Web3Auth MPC Core Kit（Custom KMSとして実装）
15+
- **DID方式**: did:key（Ed25519鍵ベース）
16+
- **VC形式**: JWT VC（任意）
17+
18+
---
19+
20+
## 🧩 構成概要（Architecture）
21+
22+
```
23+
[Client App]
24+
└─ OIDC SDK → /authorize
25+
26+
[Frontend Server (Next.js SSR)]
27+
└─ /interaction/:uid/login
28+
└─ Loginフォーム送信後：
29+
├─ Web3Auth MPC鍵を生成（Ed25519鍵のshareを複数端末に）
30+
├─ Veramo Agent経由でDID生成（Sphereon SDK）
31+
├─ 必要に応じてVC発行
32+
├─ DIDをDBに保存
33+
└─ interactionFinished()でOIDCフロー完了通知
34+
35+
[node-oidc-provider]
36+
└─ ID Token発行
37+
└─ sub: DID（または claims.did に含める）
38+
```
39+
40+
---
41+
42+
## 🔐 要件（Requirements）
43+
44+
### 🔑 1. Ed25519鍵管理
45+
- Web3Auth MPCでEd25519鍵を生成
46+
- 鍵shareは少なくとも2-of-3（例：サーバー / クライアント / クラウド）
47+
- 秘密鍵は一切復元しない
48+
- Veramoの `sign()` に対応するようCustomKMSを実装（`IKeyManagementSystem`）
49+
50+
### 🪪 2. DID生成
51+
- DIDは `did:key` を使用
52+
- Veramo Agent経由で生成
53+
- 鍵素材はWeb3Auth MPCで生成された鍵を使用
54+
55+
### 📄 3. VC発行（任意）
56+
- VCはSphereon SDKでJWT形式で発行
57+
- 発行者は自身のDID
58+
- 必要であれば「ログイン証明」VCとして出力
59+
60+
### 🧾 4. OIDC連携
61+
- OIDC IDトークンには以下のいずれかの形式でDIDを含める：
62+
```json
63+
{
64+
"sub": "did:key:z6Mkw...",
65+
"did": "did:key:z6Mkw..."
66+
}
67+
```
68+
- `/interaction/:uid/login` にログインフォーム + 処理ロジック
69+
- OIDC Provider へ `interactionFinished()` で戻す
70+
71+
---
72+
73+
## 📦 期待される成果物（Deliverables）
74+
75+
- `Web3AuthMpcKMS.ts`：Veramo KMSのカスタム実装（MPC経由の署名対応）
76+
- `agent.ts`：Veramo Agentの定義（上記KMSを登録）
77+
- `interactionLogin.ts`：SSRログイン画面 & 処理（Next.js）
78+
- DID生成ロジック：Veramo agent 経由で `did:key` を作成
79+
- VC発行ロジック：JWT署名もMPC署名で実行
80+
- node-oidc-provider設定：subまたはclaims.didにDIDを含める
81+
82+
---
83+
84+
## 🧪 テスト想定（Optional）
85+
86+
- MPC署名でVeramo `agent.keyManagerSign` が正常に動作すること
87+
- MPC鍵から生成されたDIDで、正しいJWT VCが署名されること
88+
- OIDC IDトークンにDIDが正しく埋め込まれて返ること
89+
90+
---
91+
92+
## 🧠 備考（Notes）
93+
94+
- MPCの署名実行には複数端末/環境間のセッションが必要になることを想定して設計する
95+
- サーバー側とクライアント側における `share` 保管・通信方式は分離して設計可能
96+
- 必要に応じてQRコード連携やローカルストレージ活用も検討
97+

0 commit comments

Comments
 (0)