@@ -68,13 +68,15 @@ The QR code encodes a URL containing an Out-of-Band invitation with the followin
6868```
6969
7070** URL Format** : The invitation is encoded as a URL parameter:
71+
7172```
7273https://example.com/login?_oob={url-encoded-invitation-json}
7374```
7475
7576### Goal Code
7677
7778The ` goal_code ` field MUST be set to ` "login" ` to indicate this invitation is for website authentication. This allows wallets to:
79+
7880- Recognize the invitation as a login request
7981- Apply appropriate security policies
8082- Display relevant UI to the user (e.g., "Login to website")
@@ -139,6 +141,7 @@ Sent by the wallet to initiate the login process after scanning the QR code.
139141```
140142
141143** Field Descriptions** :
144+
142145- ` from ` : The wallet's newly created DID for this connection
143146- ` to ` : The website's DID from the scanned QR code
144147- ` session_token ` : (Optional) JWT or session token from a previous session for reconnection
@@ -162,6 +165,7 @@ Sent by the website to confirm the authenticated session has been established.
162165```
163166
164167** Field Descriptions** :
168+
165169- ` thid ` : Thread ID referencing the original session-login message ID
166170
167171## Protocol Flow
@@ -202,31 +206,36 @@ Sent by the website to confirm the authenticated session has been established.
202206## Security Considerations
203207
204208### DID Authentication
209+
205210- Wallets MUST create a unique DID for each website connection to prevent correlation
206211- Websites MUST verify that the ` from ` DID in the session-login message is valid and properly formatted
207212- Both parties SHOULD use did:peer:4 long-form DIDs for enhanced security and offline resolution
208213- Websites SHOULD verify that the DID document can be resolved and contains valid verification methods
209214- The encrypted nature of DIDComm messages provides authentication through the encryption itself
210215
211216### Session Management
217+
212218- Session tokens SHOULD use JWT format with appropriate expiration times
213219- Websites SHOULD implement session timeout and renewal mechanisms
214220- Session tokens MUST be transmitted over encrypted channels only
215221- Websites SHOULD allow users to view and revoke active sessions
216222
217223### Privacy Protection
224+
218225- Profile information sharing MUST be optional and user-controlled
219226- Websites SHOULD only request the minimum necessary user information
220227- Wallets SHOULD allow users to create pseudonymous profiles for each connection
221228- Connection DIDs SHOULD NOT be reused across different websites
222229
223230### Message Security
231+
224232- All messages MUST be encrypted using DIDComm encryption
225233- Messages SHOULD include ` created_time ` to prevent replay attacks
226234- Websites SHOULD validate message timestamps and reject stale messages
227235- Both parties SHOULD implement message ordering and duplicate detection
228236
229237### QR Code Security
238+
230239- QR codes SHOULD include the website's DID and optionally additional context
231240- Websites MAY include a session ID or nonce in the QR code URL to track login attempts
232241- QR codes SHOULD be regenerated periodically if they include session-specific data
@@ -235,25 +244,29 @@ Sent by the website to confirm the authenticated session has been established.
235244## Implementation Notes
236245
237246### QR Code Generation
247+
238248- QR codes SHOULD encode the website's DID, optionally as a URL with an Out-of-Band invitation
239249- Format: ` https://example.com/login?_oob={url-encoded-invitation-json} ` where the invitation contains the website's DID
240250- Alternative format: Direct DID encoding in QR code for simpler implementations
241251- QR codes SHOULD use error correction level L for better scannability
242252- Websites MAY refresh QR codes periodically for enhanced security
243253
244254### Mediator Support
255+
245256- Wallets SHOULD register new connection DIDs with their configured mediator
246257- Websites SHOULD support receiving messages through mediators
247258- Mediator endpoints MUST support DIDComm v2 message forwarding
248259- Wallets MAY use different mediators for different connections
249260
250261### Session Establishment
262+
251263- Websites SHOULD provide both session tokens and redirect URLs
252264- Mobile wallets SHOULD support deep linking to return to the website
253265- Desktop websites SHOULD auto-refresh to complete the login
254266- Websites SHOULD provide visual feedback during the authentication process
255267
256268### Error Handling
269+
257270- Both parties SHOULD implement timeout handling for each protocol state
258271- Wallets SHOULD provide clear error messages to users
259272- Websites SHOULD log authentication failures for security monitoring
@@ -262,6 +275,7 @@ Sent by the website to confirm the authenticated session has been established.
262275## Extensibility
263276
264277### Optional Features
278+
265279Implementations MAY extend this protocol with additional features:
266280
267281- ** Challenge-response authentication** : Adding an additional challenge step for enhanced security
@@ -271,6 +285,7 @@ Implementations MAY extend this protocol with additional features:
271285- ** Social recovery** : Allowing account recovery through trusted contacts
272286
273287### Custom Fields
288+
274289Implementations MAY add custom fields to message bodies using namespaced keys:
275290
276291``` json
0 commit comments