{"_id":"@burnt-labs/xion-auth-sdk","_rev":"12-9dd808dd8a4477a82254a6f3bccfe03d","name":"@burnt-labs/xion-auth-sdk","dist-tags":{"latest":"0.3.2"},"versions":{"0.3.2":{"name":"@burnt-labs/xion-auth-sdk","version":"0.3.2","keywords":["xion","blockchain","authentication","web3","cosmos"],"author":{"name":"Burnt Labs"},"license":"MIT","_id":"@burnt-labs/xion-auth-sdk@0.3.2","maintainers":[{"name":"burntfilament","email":"filament@burnt.com"},{"name":"burnt_val","email":"val@burnt.com"},{"name":"devops.burnt.com","email":"devops@burnt.com"}],"dist":{"shasum":"a16ee75c267cb92152c37055869e8efa494ef922","tarball":"https://registry.npmjs.org/@burnt-labs/xion-auth-sdk/-/xion-auth-sdk-0.3.2.tgz","fileCount":17,"integrity":"sha512-OjzQzUucBMTqGnSrplHZ3/EWXju5eeMALelPq6B1r0JKjCX9AeNTJpMMv6YGHCwSNrsgscTB8nVj033QbhNdbw==","signatures":[{"sig":"MEUCIB3D+mSBbBvzY2n7i+m+E5jtWlpcbHUprf2+VNa/bNaiAiEAnJdnYKV3/8IZdg0TW5SRRBZFrsCRbGjThMHcNUpeUc0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46937},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","scripts":{"dev":"tsc --watch","build":"tsc","publish":"npm publish --access public","prepublishOnly":"npm run build"},"_npmUser":{"name":"devops.burnt.com","email":"devops@burnt.com"},"_npmVersion":"11.6.4","description":"Secure iframe-based SDK for XION authentication and transaction signing","directories":{},"_nodeVersion":"22.14.0","dependencies":{"@burnt-labs/abstraxion-core":"^1.0.0-alpha.56"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.3"},"_npmOperationalInternal":{"tmp":"tmp/xion-auth-sdk_0.3.2_1785528633631_0.6170973377217861","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-07-31T20:10:33.455Z","modified":"2026-08-24T08:11:36.128Z","0.1.0":"2025-11-22T18:20:08.886Z","0.2.0":"2025-11-23T16:44:05.917Z","0.2.1":"2025-11-23T16:46:07.457Z","0.3.0":"2025-12-03T12:33:55.379Z","0.3.1":"2025-12-03T12:35:02.887Z","0.4.0":"2026-03-09T20:43:52.646Z","0.3.2":"2026-07-31T20:10:33.797Z"},"author":{"name":"Burnt Labs"},"license":"MIT","keywords":["xion","blockchain","authentication","web3","cosmos"],"description":"Secure iframe-based SDK for XION authentication and transaction signing","maintainers":[{"email":"filament@burnt.com","name":"burntfilament"},{"email":"val@burnt.com","name":"burnt_val"},{"email":"ertemann@burnt.com","name":"ertemann"},{"email":"zaphod@burnt.com","name":"zaphodthebeebs"},{"email":"devops@burnt.com","name":"devops.burnt.com"}],"readme":"# @burnt/xion-sdk\n\nSecure iframe-based SDK for XION authentication and transaction signing.\n\n## Features\n\n- 🔒 **Secure by Design**: JWTs never exposed to parent application\n- 🎯 **Simple API**: `connect()`, `signTransaction()`, `disconnect()`\n- 🔐 **Multiple Auth Methods**: Email OTP, SMS, OAuth (Google), WebAuthn, Passwords, TOTP, Web3 wallets\n- 📦 **TypeScript**: Full type safety included\n- ⚡ **Lightweight**: Minimal dependencies\n- 🌐 **Cross-Origin Isolation**: Iframe runs on separate domain for maximum security\n\n## Installation\n\n```bash\nnpm install @burnt/xion-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { XionSDK } from '@burnt/xion-sdk';\n\n// Initialize the SDK\nconst sdk = new XionSDK({\n  proxyUrl: 'https://xion-proxy.burnt.com',\n  iframeUrl: 'https://auth.burnt.com',\n  network: 'testnet-2'\n});\n\n// Listen for authentication events\nsdk.on('authenticated', ({ address }) => {\n  console.log('User authenticated:', address);\n});\n\nsdk.on('disconnected', () => {\n  console.log('User disconnected');\n});\n\nsdk.on('error', ({ error }) => {\n  console.error('SDK error:', error);\n});\n\n// Connect wallet (prompts user to authenticate)\nconst { address } = await sdk.connect();\nconsole.log('Connected with address:', address);\n\n// Sign a transaction\nconst signedTx = await sdk.signTransaction({\n  messages: [\n    {\n      typeUrl: '/cosmos.bank.v1beta1.MsgSend',\n      value: {\n        fromAddress: address,\n        toAddress: 'xion1...',\n        amount: [{ denom: 'uxion', amount: '1000' }]\n      }\n    }\n  ],\n  fee: {\n    amount: [{ denom: 'uxion', amount: '5000' }],\n    gas: '200000'\n  },\n  memo: 'Test transaction'\n});\n\n// Disconnect\nawait sdk.disconnect();\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nnew XionSDK(config: XionSDKConfig)\n```\n\n**Config Options:**\n\n- `proxyUrl` (string, required): URL of the XION authentication backend API\n- `iframeUrl` (string, required): URL where the iframe authentication app is hosted\n- `network` ('testnet-2' | 'mainnet', required): XION network to use\n- `containerElement` (HTMLElement, optional): Custom container for iframe (defaults to document.body)\n\n### Methods\n\n#### `connect()`\n\nAuthenticate the user and establish a session.\n\n```typescript\nasync connect(): Promise<{ address: string }>\n```\n\n**Returns:** Promise resolving to user's XION address\n\n**Throws:** Error if authentication fails or user cancels\n\n#### `disconnect()`\n\nDisconnect the user and clear the session.\n\n```typescript\nasync disconnect(): Promise<void>\n```\n\n#### `getAddress()`\n\nGet the current user's XION address.\n\n```typescript\ngetAddress(): string | null\n```\n\n**Returns:** Address if connected, null otherwise\n\n#### `isAuthenticated()`\n\nCheck if user is currently authenticated.\n\n```typescript\nisAuthenticated(): boolean\n```\n\n**Returns:** True if authenticated, false otherwise\n\n#### `signTransaction()`\n\nSign a transaction. Requires user to be authenticated.\n\n```typescript\nasync signTransaction(txData: TransactionData): Promise<SignedTransaction>\n```\n\n**Parameters:**\n\n- `txData`: Transaction data including messages, fee, and optional memo\n\n**Returns:** Promise resolving to signed transaction\n\n**Throws:** Error if not authenticated or signing fails\n\n#### `destroy()`\n\nCleanup and remove the iframe from DOM.\n\n```typescript\ndestroy(): void\n```\n\n### Events\n\nListen to events using the `on()` method:\n\n```typescript\nsdk.on('authenticated', ({ address }) => { ... });\nsdk.on('disconnected', () => { ... });\nsdk.on('error', ({ error }) => { ... });\nsdk.on('ready', () => { ... });\n```\n\n**Event Types:**\n\n- `authenticated`: User successfully authenticated - `{ address: string }`\n- `disconnected`: User disconnected - `{}`\n- `error`: An error occurred - `{ error: string, code?: string }`\n- `ready`: Iframe is ready - `{}`\n\nYou can also use `once()` for one-time listeners and `off()` to remove listeners.\n\n## Security Model\n\n### How It Works\n\n1. **Iframe Isolation**: The authentication UI runs in a separate iframe on a different origin\n2. **No JWT Exposure**: Session JWTs are stored only in the iframe's isolated localStorage\n3. **MessageChannel Communication**: Parent app and iframe communicate via MessageChannel (not simple postMessage)\n4. **User Consent**: Every sensitive action (auth, signing) requires explicit user approval via UI\n\n### What Parent App Can Access\n\n✅ XION address (public information)\n✅ Transaction signing capability (via user approval)\n✅ Authentication state (connected/disconnected)\n\n### What Parent App Cannot Access\n\n❌ Session JWTs or tokens\n❌ User credentials\n❌ Authentication provider details\n❌ Private keys or signing credentials\n\n## Development\n\n### Building from Source\n\n```bash\ngit clone https://github.com/burnt-labs/xion-auth-sdk\ncd xion-auth-sdk/sdk\nnpm install\nnpm run build\n```\n\n### Running Tests\n\n```bash\nnpm test\n```\n\n## Examples\n\nSee the [demo application](../example/auth-demo-2-host) for a complete integration example.\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: https://github.com/burnt-labs/xion-auth-sdk/issues\n- Documentation: https://docs.burnt.com\n\n## License\n\nMIT\n","readmeFilename":"README.md"}