@burnt/xion-sdk

Secure iframe-based SDK for XION authentication and transaction signing.

Features

• 🔒 Secure by Design: JWTs never exposed to parent application
• 🎯 Simple API: connect(), signTransaction(), disconnect()
• 🔐 Multiple Auth Methods: Email OTP, SMS, OAuth (Google), WebAuthn, Passwords, TOTP, Web3 wallets
• 📦 TypeScript: Full type safety included
• ⚡ Lightweight: Minimal dependencies
• 🌐 Cross-Origin Isolation: Iframe runs on separate domain for maximum security

Installation

npm install @burnt/xion-sdk

Quick Start

import { XionSDK } from '@burnt/xion-sdk';

// Initialize the SDK
const sdk = new XionSDK({
  proxyUrl: 'https://xion-proxy.burnt.com',
  iframeUrl: 'https://auth.burnt.com',
  network: 'testnet-2'
});

// Listen for authentication events
sdk.on('authenticated', ({ address }) => {
  console.log('User authenticated:', address);
});

sdk.on('disconnected', () => {
  console.log('User disconnected');
});

sdk.on('error', ({ error }) => {
  console.error('SDK error:', error);
});

// Connect wallet (prompts user to authenticate)
const { address } = await sdk.connect();
console.log('Connected with address:', address);

// Sign a transaction
const signedTx = await sdk.signTransaction({
  messages: [
    {
      typeUrl: '/cosmos.bank.v1beta1.MsgSend',
      value: {
        fromAddress: address,
        toAddress: 'xion1...',
        amount: [{ denom: 'uxion', amount: '1000' }]
      }
    }
  ],
  fee: {
    amount: [{ denom: 'uxion', amount: '5000' }],
    gas: '200000'
  },
  memo: 'Test transaction'
});

// Disconnect
await sdk.disconnect();

API Reference

Constructor

new XionSDK(config: XionSDKConfig)

Config Options:

• proxyUrl (string, required): URL of the XION authentication backend API
• iframeUrl (string, required): URL where the iframe authentication app is hosted
• network ('testnet-2' | 'mainnet', required): XION network to use
• containerElement (HTMLElement, optional): Custom container for iframe (defaults to document.body)

Methods

connect()

Authenticate the user and establish a session.

async connect(): Promise<{ address: string }>

Returns: Promise resolving to user's XION address

Throws: Error if authentication fails or user cancels

disconnect()

Disconnect the user and clear the session.

async disconnect(): Promise<void>

getAddress()

Get the current user's XION address.

getAddress(): string | null

Returns: Address if connected, null otherwise

isAuthenticated()

Check if user is currently authenticated.

isAuthenticated(): boolean

Returns: True if authenticated, false otherwise

signTransaction()

Sign a transaction. Requires user to be authenticated.

async signTransaction(txData: TransactionData): Promise<SignedTransaction>

Parameters:

• txData: Transaction data including messages, fee, and optional memo

Returns: Promise resolving to signed transaction

Throws: Error if not authenticated or signing fails

destroy()

Cleanup and remove the iframe from DOM.

destroy(): void

Events

Listen to events using the on() method:

sdk.on('authenticated', ({ address }) => { ... });
sdk.on('disconnected', () => { ... });
sdk.on('error', ({ error }) => { ... });
sdk.on('ready', () => { ... });

Event Types:

• authenticated: User successfully authenticated - { address: string }
• disconnected: User disconnected - {}
• error: An error occurred - { error: string, code?: string }
• ready: Iframe is ready - {}

You can also use once() for one-time listeners and off() to remove listeners.

Security Model

How It Works

1. Iframe Isolation: The authentication UI runs in a separate iframe on a different origin
2. No JWT Exposure: Session JWTs are stored only in the iframe's isolated localStorage
3. MessageChannel Communication: Parent app and iframe communicate via MessageChannel (not simple postMessage)
4. User Consent: Every sensitive action (auth, signing) requires explicit user approval via UI

What Parent App Can Access

✅ XION address (public information) ✅ Transaction signing capability (via user approval) ✅ Authentication state (connected/disconnected)

What Parent App Cannot Access

❌ Session JWTs or tokens ❌ User credentials ❌ Authentication provider details ❌ Private keys or signing credentials

Development

Building from Source

git clone https://github.com/burnt-labs/xion-auth-sdk
cd xion-auth-sdk/sdk
npm install
npm run build

Running Tests

npm test

Examples

See the demo application for a complete integration example.

Support

For issues and questions:

• GitHub Issues: https://github.com/burnt-labs/xion-auth-sdk/issues
• Documentation: https://docs.burnt.com

License

MIT