@blazium/ton-connect-mobile 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,271 @@
+# TON Connect Mobile SDK
+
+Production-ready TON Connect Mobile SDK for React Native and Expo. This SDK implements the real TonConnect protocol for mobile applications using deep links and callbacks.
+
+## Features
+
+- ✅ **Real TonConnect Protocol** - Implements the actual protocol, not a mock
+- ✅ **Deep Link Wallet Connection** - Connect to wallets via deep links
+- ✅ **Session Persistence** - Maintains connection across app restarts
+- ✅ **Transaction Signing** - Send and sign transactions
+- ✅ **Signature Verification** - Verifies wallet signatures
+- ✅ **Cross-Platform** - Works with Expo Managed, Expo Bare, and React Native CLI
+- ✅ **TypeScript** - Fully typed with TypeScript
+- ✅ **Production Ready** - No placeholders, no mocks, ready for production use
+
+## Installation
+
+```bash
+npm install @blazium/ton-connect-mobile
+```
+
+### Required Dependencies
+
+**IMPORTANT**: You must install `react-native-get-random-values` for secure random number generation:
+
+```bash
+npm install react-native-get-random-values
+```
+
+Then import it at the very top of your entry file (before any other imports):
+
+```typescript
+import 'react-native-get-random-values';
+// ... other imports
+```
+
+### Peer Dependencies
+
+The SDK requires one of the following storage solutions:
+
+- `@react-native-async-storage/async-storage` (for React Native CLI)
+- Expo's built-in AsyncStorage (for Expo)
+
+For Expo projects, also install:
+
+```bash
+npx expo install expo-linking expo-crypto @react-native-async-storage/async-storage
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { TonConnectMobile } from '@blazium/ton-connect-mobile';
+
+const ton = new TonConnectMobile({
+  manifestUrl: 'https://example.com/tonconnect-manifest.json',
+  scheme: 'myapp', // Your app's deep link scheme
+});
+```
+
+### Connect to Wallet
+
+```typescript
+try {
+  const wallet = await ton.connect();
+  console.log('Connected to:', wallet.name);
+  console.log('Address:', wallet.address);
+  console.log('Public Key:', wallet.publicKey);
+} catch (error) {
+  if (error instanceof UserRejectedError) {
+    console.log('User rejected the connection');
+  } else if (error instanceof ConnectionTimeoutError) {
+    console.log('Connection timed out');
+  } else {
+    console.error('Connection failed:', error.message);
+  }
+}
+```
+
+### Listen to Status Changes
+
+```typescript
+ton.onStatusChange((status) => {
+  if (status.connected) {
+    console.log('Wallet:', status.wallet?.name);
+    console.log('Address:', status.wallet?.address);
+  } else {
+    console.log('Disconnected');
+  }
+});
+```
+
+### Send Transaction
+
+```typescript
+try {
+  const response = await ton.sendTransaction({
+    validUntil: Date.now() + 5 * 60 * 1000, // 5 minutes
+    messages: [
+      {
+        address: 'EQD0vdSA_NedR9uvbgN9EikRX-suesDxGeFg69XQMavfLqIo',
+        amount: '10000000', // 0.01 TON in nanotons
+      },
+    ],
+  });
+
+  console.log('Transaction BOC:', response.boc);
+  console.log('Signature:', response.signature);
+  
+  // IMPORTANT: Transaction signatures must be verified server-side
+  // The SDK does not perform cryptographic signature verification
+  // Use @ton/core or @ton/crypto on your backend to verify signatures
+} catch (error) {
+  if (error instanceof UserRejectedError) {
+    console.log('User rejected the transaction');
+  } else if (error instanceof TransactionTimeoutError) {
+    console.log('Transaction timed out');
+  } else if (error instanceof TransactionInProgressError) {
+    console.log('Transaction already in progress');
+  } else {
+    console.error('Transaction failed:', error.message);
+  }
+}
+```
+
+### Disconnect
+
+```typescript
+await ton.disconnect();
+```
+
+## Configuration
+
+### Expo Setup
+
+In your `app.json` or `app.config.js`, configure the deep link scheme:
+
+```json
+{
+  "expo": {
+    "scheme": "myapp"
+  }
+}
+```
+
+### React Native CLI Setup
+
+For iOS, add to `ios/YourApp/Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>myapp</string>
+    </array>
+  </dict>
+</array>
+```
+
+For Android, add to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity>
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="myapp" />
+  </intent-filter>
+</activity>
+```
+
+## Manifest File
+
+Create a `tonconnect-manifest.json` file on your server with the following structure:
+
+```json
+{
+  "url": "https://yourdomain.com",
+  "name": "Your App Name",
+  "iconUrl": "https://yourdomain.com/icon.png"
+}
+```
+
+The manifest URL must be accessible via HTTPS.
+
+## API Reference
+
+### `TonConnectMobile`
+
+Main SDK class.
+
+#### Constructor
+
+```typescript
+new TonConnectMobile(config: TonConnectMobileConfig)
+```
+
+**Config Options:**
+
+- `manifestUrl` (required): URL to your TonConnect manifest file
+- `scheme` (required): Your app's deep link scheme
+- `storageKeyPrefix` (optional): Prefix for storage keys (default: `'tonconnect_'`)
+- `connectionTimeout` (optional): Connection timeout in ms (default: `300000`)
+- `transactionTimeout` (optional): Transaction timeout in ms (default: `300000`)
+
+#### Methods
+
+- `connect(): Promise<WalletInfo>` - Connect to a wallet
+- `disconnect(): Promise<void>` - Disconnect from wallet
+- `sendTransaction(request: SendTransactionRequest): Promise<TransactionResponse>` - Send transaction
+- `getStatus(): ConnectionStatus` - Get current connection status
+- `onStatusChange(callback: StatusChangeCallback): () => void` - Subscribe to status changes
+- `destroy(): void` - Cleanup resources
+
+### Error Classes
+
+- `TonConnectError` - Base error class
+- `ConnectionTimeoutError` - Connection request timed out
+- `ConnectionInProgressError` - Connection request already in progress
+- `TransactionTimeoutError` - Transaction request timed out
+- `TransactionInProgressError` - Transaction request already in progress
+- `UserRejectedError` - User rejected the request
+
+## Architecture
+
+The SDK uses an adapter-based architecture:
+
+- **Core** - Pure TypeScript protocol implementation (no platform dependencies)
+- **Expo Adapter** - Expo-specific implementation using `expo-linking` and `expo-crypto`
+- **React Native Adapter** - React Native CLI implementation using `react-native` Linking
+
+The core module is platform-agnostic and can be used in any JavaScript environment.
+
+## Example
+
+See the `example/` directory for a complete Expo example app demonstrating:
+
+- Connecting to a wallet
+- Receiving wallet information
+- Sending transactions
+- Handling errors
+
+## Security Notes
+
+### Transaction Signature Verification
+
+⚠️ **IMPORTANT**: The SDK does NOT perform cryptographic verification of transaction signatures. The `verifyTransactionSignature()` function only validates format, not cryptographic correctness.
+
+**You MUST verify transaction signatures server-side** using proper TON libraries:
+- `@ton/core` - For BOC parsing and transaction verification
+- `@ton/crypto` - For cryptographic operations
+
+### Random Number Generation
+
+The SDK requires `react-native-get-random-values` for cryptographically secure random number generation. Make sure to import it at the top of your entry file.
+
+### Session Storage
+
+Sessions are stored in AsyncStorage (unencrypted). For production apps handling sensitive data, consider:
+- Using encrypted storage (iOS Keychain, Android EncryptedSharedPreferences)
+- Implementing additional security measures for sensitive wallet data
+
+## License
+
+MIT
+

package/dist/adapters/expo.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Expo platform adapter
+ * Handles deep linking, storage, and crypto for Expo environments
+ */
+import { PlatformAdapter } from '../types';
+/**
+ * Expo platform adapter implementation
+ */
+export declare class ExpoAdapter implements PlatformAdapter {
+    private urlListeners;
+    private subscription;
+    constructor();
+    private setupURLListener;
+    openURL(url: string): Promise<boolean>;
+    getInitialURL(): Promise<string | null>;
+    addURLListener(callback: (url: string) => void): () => void;
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+    randomBytes(length: number): Promise<Uint8Array>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}

package/dist/adapters/expo.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Expo platform adapter
+ * Handles deep linking, storage, and crypto for Expo environments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpoAdapter = void 0;
+// Dynamic imports to handle optional dependencies
+let Linking;
+let Crypto;
+let AsyncStorage;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    Linking = require('expo-linking');
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    Crypto = require('expo-crypto');
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    AsyncStorage = require('@react-native-async-storage/async-storage').default;
+}
+catch {
+    // Dependencies not available
+}
+/**
+ * Expo platform adapter implementation
+ */
+class ExpoAdapter {
+    constructor() {
+        this.urlListeners = [];
+        this.subscription = null;
+        // Set up URL listener
+        this.setupURLListener();
+    }
+    setupURLListener() {
+        if (!Linking) {
+            return;
+        }
+        // Listen for deep links when app is already open
+        this.subscription = Linking.addEventListener('url', (event) => {
+            this.urlListeners.forEach((listener) => listener(event.url));
+        });
+    }
+    async openURL(url) {
+        if (!Linking) {
+            throw new Error('expo-linking is not available');
+        }
+        try {
+            const canOpen = await Linking.canOpenURL(url);
+            if (!canOpen) {
+                return false;
+            }
+            await Linking.openURL(url);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async getInitialURL() {
+        if (!Linking) {
+            return null;
+        }
+        try {
+            return await Linking.getInitialURL();
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    addURLListener(callback) {
+        this.urlListeners.push(callback);
+        // Return unsubscribe function
+        return () => {
+            const index = this.urlListeners.indexOf(callback);
+            if (index > -1) {
+                this.urlListeners.splice(index, 1);
+            }
+        };
+    }
+    async setItem(key, value) {
+        if (!AsyncStorage) {
+            throw new Error('@react-native-async-storage/async-storage is not available');
+        }
+        try {
+            await AsyncStorage.setItem(key, value);
+        }
+        catch (error) {
+            throw new Error(`Failed to set storage item: ${error?.message || error}`);
+        }
+    }
+    async getItem(key) {
+        if (!AsyncStorage) {
+            return null;
+        }
+        try {
+            return await AsyncStorage.getItem(key);
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    async removeItem(key) {
+        if (!AsyncStorage) {
+            return;
+        }
+        try {
+            await AsyncStorage.removeItem(key);
+        }
+        catch (error) {
+            // Ignore errors on remove
+        }
+    }
+    async randomBytes(length) {
+        if (Crypto) {
+            try {
+                // Use expo-crypto for random bytes
+                const randomString = await Crypto.getRandomBytesAsync(length);
+                return randomString;
+            }
+            catch (error) {
+                // Fall through to crypto.getRandomValues check
+            }
+        }
+        // HIGH FIX: Try crypto.getRandomValues as fallback
+        // eslint-disable-next-line no-undef
+        if (typeof globalThis !== 'undefined' && globalThis.crypto && globalThis.crypto.getRandomValues) {
+            const bytes = new Uint8Array(length);
+            globalThis.crypto.getRandomValues(bytes);
+            return bytes;
+        }
+        // HIGH FIX: Throw error instead of using insecure Math.random()
+        throw new Error('Cryptographically secure random number generation not available. ' +
+            'Please ensure expo-crypto is installed or use react-native-get-random-values');
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        if (this.subscription) {
+            this.subscription.remove();
+            this.subscription = null;
+        }
+        this.urlListeners = [];
+    }
+}
+exports.ExpoAdapter = ExpoAdapter;

package/dist/adapters/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Platform adapter exports
+ */
+export { ExpoAdapter } from './expo';
+export { ReactNativeAdapter } from './react-native';
+export { WebAdapter } from './web';

package/dist/adapters/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Platform adapter exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebAdapter = exports.ReactNativeAdapter = exports.ExpoAdapter = void 0;
+var expo_1 = require("./expo");
+Object.defineProperty(exports, "ExpoAdapter", { enumerable: true, get: function () { return expo_1.ExpoAdapter; } });
+var react_native_1 = require("./react-native");
+Object.defineProperty(exports, "ReactNativeAdapter", { enumerable: true, get: function () { return react_native_1.ReactNativeAdapter; } });
+var web_1 = require("./web");
+Object.defineProperty(exports, "WebAdapter", { enumerable: true, get: function () { return web_1.WebAdapter; } });

package/dist/adapters/react-native.d.ts

@@ -0,0 +1,25 @@
+/**
+ * React Native platform adapter
+ * Handles deep linking and storage for React Native CLI environments
+ */
+import { PlatformAdapter } from '../types';
+/**
+ * React Native platform adapter implementation
+ */
+export declare class ReactNativeAdapter implements PlatformAdapter {
+    private urlListeners;
+    private subscription;
+    constructor();
+    private setupURLListener;
+    openURL(url: string): Promise<boolean>;
+    getInitialURL(): Promise<string | null>;
+    addURLListener(callback: (url: string) => void): () => void;
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+    randomBytes(length: number): Promise<Uint8Array>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}

package/dist/adapters/react-native.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * React Native platform adapter
+ * Handles deep linking and storage for React Native CLI environments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReactNativeAdapter = void 0;
+// Dynamic imports to handle optional dependencies
+let Linking;
+let AsyncStorage;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const RN = require('react-native');
+    Linking = RN.Linking;
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    AsyncStorage = require('@react-native-async-storage/async-storage').default;
+}
+catch {
+    // Dependencies not available
+}
+/**
+ * React Native platform adapter implementation
+ */
+class ReactNativeAdapter {
+    constructor() {
+        this.urlListeners = [];
+        this.subscription = null;
+        // Set up URL listener
+        this.setupURLListener();
+    }
+    setupURLListener() {
+        if (!Linking) {
+            return;
+        }
+        // Listen for deep links when app is already open
+        this.subscription = Linking.addEventListener('url', (event) => {
+            this.urlListeners.forEach((listener) => listener(event.url));
+        });
+    }
+    async openURL(url) {
+        if (!Linking) {
+            throw new Error('react-native Linking is not available');
+        }
+        try {
+            const canOpen = await Linking.canOpenURL(url);
+            if (!canOpen) {
+                return false;
+            }
+            await Linking.openURL(url);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async getInitialURL() {
+        if (!Linking) {
+            return null;
+        }
+        try {
+            return await Linking.getInitialURL();
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    addURLListener(callback) {
+        this.urlListeners.push(callback);
+        // Return unsubscribe function
+        return () => {
+            const index = this.urlListeners.indexOf(callback);
+            if (index > -1) {
+                this.urlListeners.splice(index, 1);
+            }
+        };
+    }
+    async setItem(key, value) {
+        if (!AsyncStorage) {
+            throw new Error('@react-native-async-storage/async-storage is not available');
+        }
+        try {
+            await AsyncStorage.setItem(key, value);
+        }
+        catch (error) {
+            throw new Error(`Failed to set storage item: ${error?.message || error}`);
+        }
+    }
+    async getItem(key) {
+        if (!AsyncStorage) {
+            return null;
+        }
+        try {
+            return await AsyncStorage.getItem(key);
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    async removeItem(key) {
+        if (!AsyncStorage) {
+            return;
+        }
+        try {
+            await AsyncStorage.removeItem(key);
+        }
+        catch (error) {
+            // Ignore errors on remove
+        }
+    }
+    async randomBytes(length) {
+        // HIGH FIX: Use crypto.getRandomValues if available (with polyfill)
+        // eslint-disable-next-line no-undef
+        if (typeof globalThis !== 'undefined' && globalThis.crypto && globalThis.crypto.getRandomValues) {
+            const bytes = new Uint8Array(length);
+            globalThis.crypto.getRandomValues(bytes);
+            return bytes;
+        }
+        // HIGH FIX: Throw error instead of using insecure Math.random()
+        throw new Error('Cryptographically secure random number generation not available. ' +
+            'Please install react-native-get-random-values: npm install react-native-get-random-values');
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        if (this.subscription) {
+            this.subscription.remove();
+            this.subscription = null;
+        }
+        this.urlListeners = [];
+    }
+}
+exports.ReactNativeAdapter = ReactNativeAdapter;

package/dist/adapters/web.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Web platform adapter
+ * Handles deep linking and storage for web environments
+ */
+import { PlatformAdapter } from '../types';
+/**
+ * Web platform adapter implementation
+ * Uses browser APIs for deep linking and localStorage for storage
+ */
+export declare class WebAdapter implements PlatformAdapter {
+    private urlListeners;
+    private isListening;
+    constructor();
+    private setupURLListener;
+    private handleURLChange;
+    openURL(url: string): Promise<boolean>;
+    getInitialURL(): Promise<string | null>;
+    addURLListener(callback: (url: string) => void): () => void;
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+    randomBytes(length: number): Promise<Uint8Array>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}