controller-signers

name	controller-signers
description	Configure authentication methods for Cartridge Controller including passkeys, social login, and external wallets. Use when implementing user authentication, adding multiple signers for account recovery, customizing signup options, or integrating external wallets like MetaMask or Phantom. Covers WebAuthn passkeys, Google/Discord/Twitter OAuth, wallet connections, and dynamic authentication flows.

Controller Signers & Authentication

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

Supported Signer Types

Type	Description	Best For
webauthn	Passkey (biometric/hardware key)	Primary auth, most secure
google	Google OAuth	Easy onboarding
discord	Discord OAuth	Gaming communities
twitter	Twitter/X OAuth	Social integration
argent	Argent wallet (Starknet)	Starknet native users
braavos	Braavos wallet (Starknet)	Starknet native users
metamask	MetaMask (desktop only)	EVM users
phantom-evm	Phantom EVM mode (desktop only)	Multi-chain users
rabby	Rabby wallet (desktop only)	Security-focused users
walletconnect	WalletConnect (desktop only)	Cross-device
password	Email/password	Testing only

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);