Controller Signers & Authentication

Controller supports multiple authentication methods (signers) for flexibility and security.

Supported Signer Types

Warning: Password authentication is non-recoverable. If users lose their password, they permanently lose account access. Do not use in production.

Configuring Auth Options

const controller = new Controller({
  signupOptions: [
    "webauthn",     // Passkeys
    "google",       // Google OAuth
    "discord",      // Discord OAuth
    "twitter",      // Twitter/X OAuth
    "argent",       // Argent wallet
    "braavos",      // Braavos wallet
    "metamask",     // MetaMask (desktop)
    "phantom-evm",  // Phantom (desktop)
    "rabby",        // Rabby (desktop)
    "walletconnect",// WalletConnect (desktop)
  ],
});

Order reflects UI order. With one option, branded buttons appear.

Dynamic Authentication

Override auth options per connection:

// Default options
const controller = new Controller({
  signupOptions: ["webauthn", "google", "discord"],
});

// Branded Phantom flow
await controller.connect(["phantom-evm"]);

// Branded Google flow
await controller.connect(["google"]);

Branded Buttons

Single signer config shows branded styling:

// Shows "sign up with Phantom" button with Phantom branding
const controller = new Controller({
  signupOptions: ["phantom-evm"],
});

Passkey Authentication

Platform support: iOS (Face ID/Touch ID), Android, Windows Hello, password managers (Bitwarden, 1Password).

Passkeys are backed up via:

• •Apple: iCloud Keychain
• •Android: Google account
• •Windows: Windows account

Social Login

Uses Auth0 + Turnkey wallet infrastructure:

1. •Popup OAuth flow (fallback to redirect if blocked)
2. •OIDC token validation with nonce
3. •Turnkey wallet creation linked to social account

Native app limitation: OAuth may not work in webviews. Use passkeys for native apps.

External Wallets

Starknet Wallets

• •Argent: Advanced security features, account management
• •Braavos: Built-in security features

EVM Wallets (Desktop Only)

• •MetaMask: Popular browser extension
• •Rabby: Security-focused multi-chain
• •Phantom: Multi-chain with EVM support

Cross-Platform

• •WalletConnect: QR code or deep link connection

Note: EVM wallets are automatically hidden on mobile browsers.

Chain Switching

const success = await controller.externalSwitchChain(
  "metamask",  // wallet type
  chainId      // target chain (hex)
);

Braavos does not support chain switching.

Transaction Confirmation

const response = await controller.externalWaitForTransaction(
  "metamask",
  txHash,
  30000 // timeout ms
);

if (response.success) {
  console.log("Receipt:", response.result);
} else {
  console.error("Error:", response.error);
}

Multi-Signer Management

Add backup signers via Settings > Signer(s) > Add Signer (Mainnet only).

To remove a signer:

1. •Navigate to Settings > Signer(s)
2. •Find the signer to remove
3. •Click Remove option

Best practices:

• •Add 2-3 different signer types for recovery
• •Test each auth method periodically
• •Remove compromised signers promptly

Account Synchronization

Argent and Braavos wallets auto-sync when user switches accounts in wallet. Controller registers accountsChanged listener and updates state automatically.

Note: Account synchronization is currently only available for Starknet wallets (Argent and Braavos). Other external wallets maintain existing connection behavior.

Platform-Specific Configuration

const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

const authOptions = isMobile
  ? ["webauthn", "google", "discord", "argent", "braavos"]
  : ["webauthn", "google", "discord", "argent", "braavos", "metamask", "walletconnect"];

await controller.connect(authOptions);