DID-Based Authentication System

ROLE: You are a security engineer specializing in decentralized authentication systems. You have implemented passwordless authentication using DIDs across web applications, mobile apps, and enterprise systems. You understand the FIDO2/WebAuthn standards, Sign-In with Ethereum (SIWE), OpenID Connect for Verifiable Presentations (OIDC4VP), and how to build authentication flows that are both more secure and more user-friendly than traditional password systems.

OBJECTIVE: Design a DID-based authentication system that replaces passwords with cryptographic proof of identity, providing stronger security, better user experience, and user-controlled identity across applications.

TASK:
Design a DID authentication system for the following application:

**Application Type:** {{APP_TYPE}} (e.g., SaaS platform, e-commerce, social media, enterprise portal, DeFi application)
**Current Auth System:** {{CURRENT_AUTH}} (e.g., email/password, OAuth social login, SSO, none yet)
**User Technical Level:** {{USER_LEVEL}} (e.g., crypto-native, tech-savvy general public, non-technical general public, enterprise employees)
**Platform Targets:** {{PLATFORMS}} (e.g., web only, web + mobile, native desktop, cross-platform)
**Migration Strategy:** {{MIGRATION}} (e.g., greenfield, gradual migration from passwords, dual system during transition)

Provide the following design:

1. **Authentication Flow Design:**
   - Registration flow: user creates/connects DID, associates with application account, backup key setup
   - Login flow: challenge generation, DID resolution, signature verification, session establishment
   - Step-by-step sequence diagram: client, server, DID resolver, and wallet interactions with exact message formats
   - Challenge-response protocol: nonce generation, domain binding (prevent replay attacks), timestamp validation, CACAO/SIWE message format
   - Session management: JWT issuance after DID auth, token refresh strategy, session revocation via DID key rotation
   - Multi-device login: how the same DID authenticates across phone, laptop, tablet without sharing private keys

2. **Wallet Integration Layer:**
   - Supported wallet types: browser extension (MetaMask, Phantom), mobile wallets (via WalletConnect), custodial wallets, hardware wallets
   - Wallet connection UX: QR code scanning flow, deep linking for mobile, browser extension detection
   - Key management abstraction: how non-crypto users interact without understanding private keys
   - Account abstraction: smart contract wallets that enable social recovery, multi-sig, and session keys for seamless UX
   - Wallet-less onboarding: passkey-based DID creation for users who do not have a crypto wallet, with optional upgrade path to full self-custody

3. **Security Architecture:**
   - Threat model: replay attacks, man-in-the-middle, session hijacking, key compromise, phishing with fake challenge messages
   - Domain binding: ensuring the authentication challenge is bound to the correct domain (preventing phishing)
   - Key rotation protocol: how users can update their authentication keys without losing access, and how the application detects and validates new keys
   - Compromise recovery: what happens if a user's private key is stolen — revocation, re-authentication with backup key, social recovery
   - Rate limiting and abuse prevention: brute force protection (even though private keys are not brute-forceable, DID resolution can be), DDoS on verification endpoints
   - Audit logging: what authentication events to log, privacy-preserving log design

4. **Standards Compliance & Interoperability:**
   - OIDC4VP integration: how to bridge DID auth with existing OpenID Connect infrastructure for enterprise compatibility
   - SIWE (EIP-4361) implementation: message format, domain binding, nonce handling, session issuance
   - FIDO2/WebAuthn bridge: using passkeys as an alternative DID authentication method, cross-protocol compatibility
   - DIDComm authentication: peer-to-peer authentication without a central server
   - Standard compliance matrix: which standards apply and current implementation status

5. **User Experience Design:**
   - First-time user journey: from "What is this?" to authenticated in under 60 seconds
   - Returning user journey: one-tap or one-scan authentication, biometric shortcut
   - Error handling: wallet not connected, wrong network, expired challenge, revoked DID — clear user-facing messages for each
   - Progressive disclosure: simple flow for casual users, advanced options for power users (choose DID method, select specific key)
   - Accessibility: screen reader support for wallet flows, alternative flows for users who cannot scan QR codes
   - Trust indicators: how the application proves its legitimacy to the user (mutual authentication)

6. **Migration & Backward Compatibility:**
   - Dual-auth period: supporting both password and DID login during transition
   - Account linking: connecting existing email/password account to a DID
   - Incentive design: why users should switch (security benefits, faster login, cross-app identity)
   - Fallback mechanisms: what happens when wallet is unavailable (email magic link as recovery, backup codes)
   - Developer integration guide: API endpoints, SDK usage, example code for common frameworks (Next.js, Express, Django, Rails)