Sui Passkey

SUI Passkey Integration

Passwordless authentication using WebAuthn and device biometrics.

Overview

Passkey provides:

• Biometric authentication (Face ID, Touch ID, Windows Hello)
• No passwords or seed phrases
• Hardware-backed security
• Cross-device sync (via iCloud, Google)

Use Cases

• Consumer apps requiring easy login
• Mobile-first applications
• Security-critical applications
• Enterprise SUI apps

Quick Start

Register Passkey

import { PasskeyProvider } from '@mysten/wallet-standard';

async function registerPasskey(username: string) {
  const provider = new PasskeyProvider();

  // Create passkey credential
  const credential = await navigator.credentials.create({
    publicKey: {
      challenge: new Uint8Array(32), // Random challenge
      rp: {
        name: 'My SUI App',
        id: window.location.hostname
      },
      user: {
        id: new Uint8Array(16),
        name: username,
        displayName: username
      },
      pubKeyCredParams: [{ alg: -7, type: 'public-key' }],
      authenticatorSelection: {
        authenticatorAttachment: 'platform',
        userVerification: 'required'
      }
    }
  });

  // Derive SUI address from passkey
  const address = provider.getAddress(credential);

  return { credential, address };
}

Authenticate with Passkey

async function authenticatePasskey() {
  const credential = await navigator.credentials.get({
    publicKey: {
      challenge: new Uint8Array(32),
      rpId: window.location.hostname,
      userVerification: 'required'
    }
  });

  return credential;
}

Sign Transaction

async function signWithPasskey(tx: Transaction) {
  const provider = new PasskeyProvider();

  // Get passkey credential
  const credential = await authenticatePasskey();

  // Sign transaction
  const signature = await provider.signTransaction(tx, credential);

  return signature;
}

React Hook

function usePasskey() {
  const [address, setAddress] = useState<string | null>(null);
  const [isRegistered, setIsRegistered] = useState(false);

  const register = async (username: string) => {
    const { credential, address } = await registerPasskey(username);

    // Store credential ID
    localStorage.setItem('passkey_credential_id', credential.id);
    localStorage.setItem('passkey_address', address);

    setAddress(address);
    setIsRegistered(true);
  };

  const authenticate = async () => {
    const credential = await authenticatePasskey();

    if (credential) {
      const storedAddress = localStorage.getItem('passkey_address');
      setAddress(storedAddress);
    }
  };

  const signTransaction = async (tx: Transaction) => {
    return await signWithPasskey(tx);
  };

  return { address, isRegistered, register, authenticate, signTransaction };
}

Move Contract

// Passkey addresses are regular SUI addresses
// No special Move code needed!

public fun create_profile(
    name: String,
    ctx: &mut TxContext
) {
    let user = tx_context::sender(ctx);  // Works with passkey!
    // ...
}

Best Practices

• Check WebAuthn browser support
• Fallback to traditional wallet
• Handle credential loss scenarios
• Test on multiple devices
• Provide backup authentication

Browser Compatibility

• ✅ Chrome/Edge (Windows, macOS, Android)
• ✅ Safari (macOS, iOS)
• ✅ Firefox (Windows, macOS)
• ⚠️ Check mobile browser support

Common Mistakes

❌ Not checking WebAuthn browser support

• Problem: App crashes on unsupported browsers
• Fix: Check window.PublicKeyCredential before registering passkey

❌ No fallback authentication method

• Problem: Users locked out if passkey device is lost
• Fix: Offer traditional wallet connection as fallback

❌ Storing credential ID without encryption

• Problem: XSS attacks can steal credential reference
• Fix: Encrypt credential ID before localStorage, or use sessionStorage

❌ Not handling "user cancelled" flow

• Problem: App stuck in loading state
• Fix: Catch AbortError, show "Authentication cancelled" message

❌ Using wrong authenticator attachment

• Problem: Requires USB key instead of platform biometrics
• Fix: Set authenticatorAttachment: 'platform' for Face ID/Touch ID

❌ Not testing on multiple devices

• Problem: Works on desktop, fails on mobile
• Fix: Test registration and authentication on iOS, Android, desktop

❌ Missing user verification requirement

• Problem: Security risk, no biometric check
• Fix: Set userVerification: 'required' for all operations

❌ Not providing credential recovery flow

• Problem: Users lose access if they reset device
• Fix: Implement account recovery via email or backup passkey

Query Passkey docs:

const passkeyInfo = await sui_docs_query({
  type: "github",
  target: "sui-core",
  query: "passkey WebAuthn implementation examples"
});

Secure, user-friendly authentication with no passwords!

Converted and distributed by TomeVault — claim your Tome and manage your conversions.