Passkey Authentication Integration for Revolutionary Farmers

📝 Task Description

Integrate Passkey authentication (WebAuthn/FIDO2) using passkey-kit to eliminate passwords and seed phrases from Revolutionary Farmers platform. Enable users to authenticate using biometrics or secure devices, improving security while simplifying the user experience for farmers, merchants, and buyers across desktop and mobile devices.

🎨 Deliverable

• Complete Passkey authentication system replacing traditional email/password flows
• Seamless registration and login experience using WebAuthn
• Integration with existing user roles (Farmer/Merchant, Buyer)
• Stellar Soroban smart contract integration for identity management
• Cross-platform compatibility (desktop and mobile browsers)
• Comprehensive documentation for developers and deployment
• Fallback authentication methods for unsupported devices

📋 Requirements

1. Passkey Registration Flow

• Initial Setup:
  • User selects role (Farmer/Merchant or Buyer)
  • System prompts for Passkey creation
  • Biometric authentication or device PIN verification
  • Passkey credential stored securely on device
  • User identity linked to Stellar account/contract

2. Passkey Login Flow

• Authentication Process:
  • User clicks "Login with Passkey"
  • System requests biometric/device authentication
  • WebAuthn credential verification
  • Automatic session establishment
  • Redirect to appropriate dashboard based on role

3. Cross-Platform Support

• Desktop Browsers:
  • Chrome 67+, Firefox 60+, Safari 14+, Edge 18+
  • Windows Hello, Touch ID, Face ID support
  • USB security keys (YubiKey, etc.)
• Mobile Devices:
  • iOS Safari 14+ with Face ID/Touch ID
  • Android Chrome 70+ with fingerprint/face unlock
  • Platform authenticators and roaming authenticators

4. Stellar Integration

• Blockchain Identity:
  • Link Passkey credentials to Stellar public keys
  • Smart contract deployment for identity verification
  • Soroban contract integration for user roles and permissions
  • Automatic wallet generation tied to Passkey identity

5. Fallback Authentication

• Legacy Support:
  • Email/password option for unsupported browsers
  • Recovery mechanisms for lost devices
  • Account migration from traditional auth to Passkeys
  • Admin recovery procedures

📋 Technical Requirements

Dependencies and Setup

```json { "dependencies": { "@passkey-kit/core": "^latest", "@passkey-kit/next": "^latest", "@stellar/stellar-sdk": "^latest", "@stellar/soroban-client": "^latest" } } ```

WebAuthn Configuration

• Relying Party Setup:
  • Configure RP ID and origin for Revolutionary Farmers domain
  • Set up challenge generation and verification
  • Implement credential storage and retrieval
  • Handle attestation and assertion flows

Database Schema Updates

```sql -- Extend existing user table ALTER TABLE users ADD COLUMN passkey_credential_id TEXT; ALTER TABLE users ADD COLUMN passkey_public_key TEXT; ALTER TABLE users ADD COLUMN webauthn_user_id TEXT UNIQUE; ALTER TABLE users ADD COLUMN stellar_public_key TEXT;

-- New table for Passkey credentials CREATE TABLE passkey_credentials ( id UUID PRIMARY KEY, user_id UUID REFERENCES users(id), credential_id TEXT UNIQUE NOT NULL, public_key TEXT NOT NULL, counter BIGINT DEFAULT 0, device_type TEXT, created_at TIMESTAMP DEFAULT NOW(), last_used_at TIMESTAMP ); ```

API Endpoints

• POST /api/auth/passkey/register/begin - Start registration
• POST /api/auth/passkey/register/complete - Complete registration
• POST /api/auth/passkey/login/begin - Start authentication
• POST /api/auth/passkey/login/complete - Complete authentication
• GET /api/auth/passkey/credentials - List user credentials
• DELETE /api/auth/passkey/credentials/:id - Remove credential

Stellar Soroban Integration

• Smart Contract Functions:
  • register_user(passkey_id, public_key, role) - Register new user
  • authenticate_user(passkey_id, signature) - Verify authentication
  • update_role(user_id, new_role) - Role management
  • get_user_info(passkey_id) - Retrieve user data

Security Considerations

• WebAuthn Security:
  • Implement proper challenge generation (32+ bytes random)
  • Verify origin and RP ID on all requests
  • Counter validation to prevent replay attacks
  • Attestation verification for high-security scenarios
• Stellar Security:
  • Secure key derivation from Passkey credentials
  • Multi-signature support for high-value operations
  • Rate limiting on authentication attempts

📋 Content Updates Required

Copy (EN/ES)

• Registration Flow:
  • EN: "Secure your account with Passkey", "Use your fingerprint or face to sign in"
  • ES: "Asegura tu cuenta con Passkey", "Usa tu huella o rostro para iniciar sesión"
• Login Interface:
  • EN: "Sign in with Passkey", "Touch sensor or look at camera"
  • ES: "Iniciar sesión con Passkey", "Toca el sensor o mira la cámara"
• Error Messages:
  • EN: "Passkey not supported on this device", "Authentication failed, please try again"
  • ES: "Passkey no compatible con este dispositivo", "Autenticación falló, intenta de nuevo"
• Success States:
  • EN: "Passkey created successfully!", "Welcome back!"
  • ES: "¡Passkey creado exitosamente!", "¡Bienvenido de vuelta!"

User Interface Updates

• Login Modal Redesign:
  • Primary "Sign in with Passkey" button
  • Secondary "Use email/password" fallback
  • Clear device compatibility indicators
• Registration Flow:
  • Passkey setup wizard with step-by-step guidance
  • Device compatibility check
  • Biometric setup instructions
• Account Settings:
  • Passkey management interface
  • Add/remove credentials
  • Device list with last used timestamps

💡 Additional Notes

Reference Implementation

• Study existing implementations:
  • stellar-passkey repository for Stellar-specific patterns
  • passkey-kit documentation and examples
  • Oppia demo for Next.js integration patterns

Browser Compatibility Strategy

• Progressive Enhancement:
  • Feature detection for WebAuthn support
  • Graceful fallback to traditional authentication
  • Clear messaging about browser requirements
• Testing Matrix:
  • Chrome/Edge on Windows with Windows Hello
  • Safari on macOS with Touch ID
  • Chrome on Android with fingerprint
  • Safari on iOS with Face ID/Touch ID

User Experience Considerations

• Onboarding:
  • Clear explanation of Passkey benefits
  • Step-by-step setup guide with screenshots
  • Troubleshooting common issues
• Error Handling:
  • Specific error messages for different failure modes
  • Recovery options for each error type
  • Support contact information

Deployment Considerations

• Vercel Configuration:
  • Environment variables for WebAuthn settings
  • Domain configuration for RP ID
  • HTTPS enforcement (required for WebAuthn)
• Monitoring:
  • Authentication success/failure rates
  • Browser compatibility metrics
  • User adoption tracking

Future Enhancements

• Advanced Features:
  • Multi-device Passkey sync
  • Enterprise authentication policies
  • Hardware security key support
  • Conditional UI for seamless authentication

✅ Definition of Done

• Passkey registration flow implemented and tested across target browsers
• Passkey authentication flow working with biometric and device PIN methods
• Integration with existing user role system (Farmer/Merchant, Buyer)
• Stellar Soroban smart contracts deployed and integrated
• Database schema updated with Passkey credential storage
• API endpoints implemented with proper security measures
• Fallback authentication maintained for unsupported devices
• Cross-platform testing completed (desktop and mobile)
• Error handling and user feedback implemented
• All copy localized (EN/ES) and integrated with i18n system
• Account management interface for Passkey credentials
• Documentation created for developers and deployment
• Security audit completed for WebAuthn implementation
• Performance testing shows no degradation in auth flow
• Analytics tracking implemented for adoption metrics
• Vercel deployment configuration documented
• User onboarding flow updated with Passkey setup
• Support documentation created for troubleshooting