cartridge-gg/controller-signers

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