Passwordless Authentication with Passkeys 🔑

Never ask your users for passwords again! VaultysId makes implementing passkey and FIDO2 authentication incredibly simple in your P2P applications.

🎯 Why Passkeys?

The Problem with Passwords

• 🔓 81% of breaches involve compromised passwords
• 😫 Password fatigue - users have 100+ passwords to manage
• 🎯 Phishing targets - passwords can be stolen
• ⏰ Time wasted - password resets cost time and money

The Passkey Solution

• 🔐 Cryptographically secure - private keys never leave the device
• 👆 One touch login - biometric or security key authentication
• 🚫 Phishing resistant - credentials bound to origin
• 😊 Better UX - faster, simpler login experience

🚀 Quick Start

Enable Passkey Authentication in 3 Lines

import { VaultysId } from '@vaultys/id';

// That's it! Your users can now login with biometrics
const identity = await VaultysId.authenticate({
  passkey: true
});

📚 Complete Implementation

1. Initial Registration (One-time Setup)

import { VaultysId } from '@vaultys/id';
import { setupVaultysPeerSDK } from '@vaultys/peer-sdk';

async function registerNewUser() {
  try {
    // Register with passkey
    const identity = await VaultysId.register({
      username: 'alice@example.com',
      displayName: 'Alice Smith',
      passkey: true,  // Enable FIDO2/WebAuthn
      
      // Optional configurations
      authenticatorSelection: {
        authenticatorAttachment: 'platform', // Use device biometrics
        userVerification: 'preferred',
        requireResidentKey: true
      }
    });

    console.log('✅ Registered with DID:', identity.did);
    console.log('🔑 Passkey created successfully!');

    // Initialize P2P with authenticated identity
    const peer = setupVaultysPeerSDK({ identity });
    await peer.initialize(identity.did);

    return { identity, peer };
  } catch (error) {
    console.error('Registration failed:', error);
    // Fallback to other auth methods if needed
  }
}

2. Subsequent Logins (Passwordless)

async function loginWithPasskey() {
  try {
    // Authenticate with biometric/security key
    const identity = await VaultysId.authenticate({
      passkey: true,
      // Optional: Add timeout
      timeout: 60000, // 60 seconds
    });

    console.log('✅ Authenticated as:', identity.did);
    
    // User is now logged in without any password!
    const peer = setupVaultysPeerSDK({ identity });
    await peer.initialize(identity.did);

    return { identity, peer };
  } catch (error) {
    console.error('Authentication failed:', error);
    // Handle fallback authentication
  }
}

3. Fallback Options

async function authenticateWithFallback() {
  const identity = await VaultysId.authenticate({
    passkey: true,
    
    // Fallback options
    fallbackToPin: true,      // Allow PIN as fallback
    fallbackToPassword: false, // We don't want passwords!
    
    // UI customization
    ui: {
      title: 'Sign in to P2P Chat',
      subtitle: 'Use your fingerprint or security key'
    }
  });

  return identity;
}

🔧 Advanced Configuration

Platform-Specific Settings

// For mobile apps
const mobileConfig = {
  passkey: true,
  authenticatorSelection: {
    authenticatorAttachment: 'platform', // Device biometrics
    userVerification: 'required'
  }
};

// For desktop with security keys
const desktopConfig = {
  passkey: true,
  authenticatorSelection: {
    authenticatorAttachment: 'cross-platform', // USB security keys
    userVerification: 'preferred'
  }
};

// Auto-detect and configure
const identity = await VaultysId.authenticate({
  passkey: true,
  ...(isMobile() ? mobileConfig : desktopConfig)
});

Multi-Device Support

// Register multiple devices for the same user
async function addNewDevice(existingIdentity: Identity) {
  const newCredential = await VaultysId.addPasskey({
    identity: existingIdentity,
    deviceName: 'iPhone 15 Pro',
    
    // This device's specific settings
    authenticatorSelection: {
      authenticatorAttachment: 'platform'
    }
  });

  console.log('✅ New device added:', newCredential.id);
}

Recovery Options

// Setup recovery in case user loses access to passkeys
async function setupRecovery(identity: Identity) {
  // Add recovery email
  await identity.addRecoveryMethod({
    type: 'email',
    value: 'alice@example.com'
  });

  // Generate recovery codes
  const recoveryCodes = await identity.generateRecoveryCodes();
  console.log('Save these recovery codes:', recoveryCodes);

  // Add backup authenticator
  await identity.addBackupAuthenticator({
    type: 'totp', // Time-based one-time password
    name: 'Authenticator App'
  });
}

🎨 UI/UX Best Practices

1. Progressive Enhancement

// Check if passkeys are supported
if (await VaultysId.isPasskeySupported()) {
  // Show passkey option prominently
  showPasskeyLogin();
} else {
  // Fallback to traditional auth
  showAlternativeLogin();
}

2. Clear User Communication

const identity = await VaultysId.authenticate({
  passkey: true,
  ui: {
    title: 'Welcome Back! 👋',
    subtitle: 'Sign in with your fingerprint or face',
    instruction: 'Touch the sensor or look at your camera',
    errorMessage: 'Not recognized. Try again or use PIN.'
  }
});

3. Smooth Onboarding Flow

async function onboardNewUser() {
  // Step 1: Explain benefits
  await showOnboardingScreen({
    title: 'Say Goodbye to Passwords! 🎉',
    benefits: [
      '🔐 More secure than passwords',
      '⚡ Login in under 2 seconds',
      '🔒 Your biometric data never leaves your device'
    ]
  });

  // Step 2: Register with passkey
  const identity = await VaultysId.register({
    username: getUserEmail(),
    passkey: true,
    ui: {
      title: 'Setup Secure Login',
      subtitle: 'This replaces your password forever'
    }
  });

  // Step 3: Confirm success
  await showSuccessScreen({
    message: 'You\'re all set! Next time, just use your fingerprint.'
  });

  return identity;
}

🔒 Security Considerations

Credential Storage

// VaultysId handles secure storage automatically
const identity = await VaultysId.authenticate({
  passkey: true,
  storage: {
    // Credentials stored in secure enclave
    type: 'secure',
    // Encrypted at rest
    encryption: true,
    // Biometric protection
    requireBiometric: true
  }
});

Session Management

// Configure session security
const peer = setupVaultysPeerSDK({
  identity,
  session: {
    // Require re-authentication after 30 minutes
    timeout: 30 * 60 * 1000,
    // Require passkey for sensitive operations
    requireReauth: ['deleteAccount', 'exportKeys'],
    // Lock on background
    lockOnBackground: true
  }
});

📱 Platform Support

Platform	Support	Authentication Method
iOS 16+	✅ Full	Face ID, Touch ID
Android 9+	✅ Full	Fingerprint, Face Unlock
Windows 10+	✅ Full	Windows Hello, Security Keys
macOS 12+	✅ Full	Touch ID, Security Keys
Linux	✅ Partial	Security Keys
Chrome 67+	✅ Full	All methods
Safari 14+	✅ Full	All methods
Firefox 60+	✅ Full	Security Keys
Edge 79+	✅ Full	All methods

🎯 Real-World Example

P2P Chat with Passkey Auth

// Complete example: P2P chat with passwordless login
import { VaultysId } from '@vaultys/id';
import { setupVaultysPeerSDK } from '@vaultys/peer-sdk';

class SecureP2PChat {
  private identity?: Identity;
  private peer?: PeerService;

  async initialize() {
    // Try to authenticate with existing passkey
    try {
      this.identity = await VaultysId.authenticate({
        passkey: true,
        ui: {
          title: 'Welcome to Secure Chat',
          subtitle: 'Verify your identity'
        }
      });
    } catch (error) {
      // First time user - register
      this.identity = await this.register();
    }

    // Setup P2P with authenticated identity
    this.peer = setupVaultysPeerSDK({ 
      identity: this.identity,
      lazyConnect: true 
    });
    
    await this.peer.initialize(this.identity.did);
    
    console.log('🚀 Secure P2P chat ready!');
    console.log('🔐 Authenticated as:', this.identity.did);
    console.log('🔑 No passwords were harmed in this process!');
  }

  private async register() {
    const email = prompt('Enter your email:');
    const name = prompt('Enter your name:');

    return await VaultysId.register({
      username: email,
      displayName: name,
      passkey: true,
      ui: {
        title: 'Create Your Secure Account',
        subtitle: 'No passwords needed, ever!'
      }
    });
  }

  async sendSecureMessage(toDid: string, message: string) {
    if (!this.peer) throw new Error('Not initialized');
    
    // Messages are automatically encrypted with your DID
    await this.peer.sendMessage(toDid, message);
  }
}

// Usage
const chat = new SecureP2PChat();
await chat.initialize();
// User is now logged in with just their fingerprint!

🚨 Troubleshooting

Common Issues and Solutions

Issue	Solution
"Passkey not supported"	Check browser compatibility, update to latest version
"User cancelled"	Provide clear instructions, offer alternative auth
"Timeout error"	Increase timeout value, check device settings
"Invalid domain"	Ensure HTTPS and correct rpId configuration
"Attestation failed"	Check server attestation settings

Debug Mode

// Enable debug logging for troubleshooting
const identity = await VaultysId.authenticate({
  passkey: true,
  debug: true, // Shows detailed logs
  onError: (error) => {
    console.error('Auth error:', error);
    // Send to error tracking service
  }
});

📚 Learn More

• WebAuthn Specification
• FIDO2 Documentation
• VaultysId Documentation
• Browser Compatibility

🎉 Conclusion

With VaultysId and Vaultys Peer SDK, implementing secure, passwordless authentication has never been easier. Your users will love the simplicity, and you'll love the security. No more password resets, no more breaches, just simple, secure authentication with passkeys!

Remember: Every password you eliminate makes the internet a safer place! 🌍🔐