@bounded-sh/client 0.0.1

package/dist/auth/providers/phantom-wallet-provider.d.ts

@@ -0,0 +1,117 @@
+import type { EVMTransaction, SolTransaction, TransactionResult, User, AuthProvider, SetOptions } from '@bounded-sh/core';
+import { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
+export type PhantomProviderType = 'injected' | 'google' | 'apple' | 'deeplink' | 'phantom';
+export interface PhantomWalletConfig {
+    appId?: string;
+    /** Providers to use for authentication. Accepts string[] for convenience (e.g., ["injected"]) */
+    providers?: PhantomProviderType[] | string[];
+    autoConnect?: boolean;
+    /** Theme for the connect modal: 'light' or 'dark'. Defaults to 'dark'. */
+    theme?: 'light' | 'dark';
+    /** App name displayed in the connect modal */
+    appName?: string;
+    /** App icon URL displayed in the connect modal */
+    appIcon?: string;
+    /** Custom title shown at the top of the login modal. Overrides the default "Log in to your account". */
+    modalTitle?: string;
+    /** Custom subtitle shown below the title in the login modal. */
+    modalSubtitle?: string;
+}
+/**
+ * Per-call overrides for `login()`. All fields are optional and take precedence
+ * over the values set in `PhantomWalletConfig` during `init()`.
+ */
+export interface LoginOptions {
+    /** Override the modal theme just for this login call. */
+    theme?: 'light' | 'dark';
+    /** Override the modal title just for this login call. */
+    modalTitle?: string;
+    /** Override the modal subtitle just for this login call. */
+    modalSubtitle?: string;
+}
+export declare class PhantomWalletProvider implements AuthProvider {
+    private static instance;
+    private containerElement;
+    private networkUrl;
+    private root;
+    private phantomMethods;
+    private config;
+    private resolvedProviders;
+    private pendingLogin;
+    private loginInProgress;
+    private autoLoginInProgress;
+    private initPromise;
+    private loginOverrides;
+    /** Temporarily override modal appearance for a single login() call. Cleared automatically after login settles. */
+    setLoginOverrides(opts: LoginOptions | null): void;
+    /** Callback to swap to a Mobile Wallet Adapter provider when the user clicks "Connect Mobile Wallet" */
+    onSwitchToMWA: (() => Promise<AuthProvider>) | null;
+    constructor(networkUrl?: string | null, config?: PhantomWalletConfig);
+    private initializeAsync;
+    /**
+     * Check if social login providers are configured (non-injected providers).
+     */
+    private hasSocialProviders;
+    static getInstance(networkUrl: string | null, config: PhantomWalletConfig): PhantomWalletProvider;
+    private resolveProviders;
+    /**
+     * Patch the Phantom extension's provider to gracefully handle `phantom_getFeatures`
+     * instead of throwing. Some SDKs probe this method to check feature support, but the
+     * extension doesn't implement it, causing noisy console errors.
+     */
+    private patchPhantomGetFeatures;
+    private initialize;
+    private ensureReady;
+    private ensureSolanaReady;
+    /**
+     * Get the list of available (configured) providers for this wallet.
+     */
+    getAvailableProviders(): PhantomProviderType[];
+    /**
+     * Login using the Phantom connect modal. A custom modal is rendered with the
+     * discovered wallets and configured social providers instead of the SDK's
+     * built-in modal.
+     */
+    login(): Promise<User | null>;
+    restoreSession(): Promise<User | null>;
+    private awaitTopLevelConnect;
+    address(): Promise<string | null>;
+    runTransaction(_evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    /**
+     * Signs a Solana transaction without submitting it.
+     *
+     * This method handles blockhash automatically if not set - you do NOT need to
+     * set recentBlockhash on the transaction before calling this method.
+     * The network/RPC URL is derived from the provider's configuration (set during initialization).
+     *
+     * @param transaction - The transaction to sign (Transaction or VersionedTransaction)
+     * @returns The signed transaction
+     */
+    signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    /**
+     * Signs and submits a Solana transaction to the network.
+     *
+     * This method handles blockhash and transaction confirmation automatically - you do NOT need to
+     * set recentBlockhash or lastValidBlockHeight on the transaction before calling this method.
+     * The network/RPC URL is derived from the provider's configuration (set during initialization).
+     *
+     * @param transaction - The transaction to sign and submit (Transaction or VersionedTransaction)
+     * @param feePayer - Optional fee payer public key. If not provided and the transaction doesn't
+     *                   already have a feePayer set, the connected wallet address will be used.
+     *                   Useful for co-signing scenarios where a different account pays the fees.
+     * @returns The transaction signature
+     */
+    signAndSubmitTransaction(transaction: Transaction | VersionedTransaction, feePayer?: PublicKey): Promise<string>;
+    signMessage(message: string): Promise<string>;
+    logout(): Promise<void>;
+    getNativeMethods(): Promise<any>;
+    private getRpcUrl;
+    private signAndSendViaPhantom;
+    private submitSignedTransaction;
+    private submitSignedTransactionWithBlockhash;
+}
+declare global {
+    interface Window {
+        CUSTOM_TAROBASE_APP_ID_HEADER?: string;
+    }
+}

package/dist/auth/providers/privy-expo-provider.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Privy Expo Auth Provider — React Native implementation of AuthProvider.
+ *
+ * Uses @privy-io/expo instead of @privy-io/react-auth.
+ * Persists the session through getActiveSessionManager() (the RN store on React
+ * Native), and mints it via the SIWS wallet-signature path — identical to
+ * Phantom/MWA — so no Privy-specific backend verification is required.
+ *
+ * IMPORTANT — Expo/RN consumers must:
+ *   1. Install polyfills: fast-text-encoding, react-native-get-random-values
+ *   2. Install @privy-io/expo, @privy-io/expo-native-extensions
+ *   3. Call ReactNativeSessionManager.configure({ storage, atob }) at startup
+ *   4. Call setPlatform({ ... }) from @bounded-sh/web at startup
+ *   5. Wrap their app tree with PrivyProvider from @privy-io/expo
+ *   6. Create this provider and pass the Privy hooks/methods via setPrivyMethods()
+ *
+ * Unlike the web PrivyWalletProvider which renders a hidden React DOM tree
+ * to host Privy's React context, this provider expects the RN app itself
+ * to render <PrivyProvider> and then bridge the hooks via setPrivyMethods().
+ */
+import type { EVMTransaction, SolTransaction, TransactionResult, AuthProvider, User, SetOptions } from '@bounded-sh/core';
+import { PublicKey, Connection, Transaction, VersionedTransaction } from '@solana/web3.js';
+export interface PrivyExpoMethods {
+    /** Whether Privy SDK is fully initialized. */
+    isReady: boolean;
+    /** Whether the user is authenticated. */
+    isAuthenticated: boolean;
+    /** The user object from usePrivy(). */
+    user: any;
+    /** Trigger Privy login UI. Returns the user on success. */
+    login: () => Promise<any>;
+    /** Log out from Privy. */
+    logout: () => Promise<void>;
+    /** Get an access token from Privy. */
+    getAccessToken: () => Promise<string | null>;
+    /** Get the Privy identity token. */
+    getIdentityToken: () => Promise<string | null>;
+    /**
+     * Get the embedded Solana wallet provider.
+     * Comes from useEmbeddedSolanaWallet().
+     */
+    getWalletProvider: () => Promise<{
+        address: string;
+        signMessage: (message: Uint8Array) => Promise<{
+            signature: Uint8Array;
+        }>;
+        signTransaction: (transaction: Transaction | VersionedTransaction) => Promise<{
+            signedTransaction: Uint8Array;
+        }>;
+        signAndSendTransaction: (transaction: Transaction | VersionedTransaction, connection: Connection) => Promise<{
+            signature: string;
+        }>;
+    } | null>;
+}
+export declare class PrivyExpoProvider implements AuthProvider {
+    private networkUrl;
+    private privyMethods;
+    private appId;
+    constructor(appId: string, networkUrl?: string | null);
+    /**
+     * Bridge Privy hooks from the app's React tree into this provider.
+     *
+     * Call this from a component rendered inside <PrivyProvider>:
+     * ```tsx
+     * const privy = usePrivy();
+     * const wallet = useEmbeddedSolanaWallet();
+     * const { getAccessToken } = usePrivy();
+     * const { getIdentityToken } = useIdentityToken();
+     *
+     * useEffect(() => {
+     *   provider.setPrivyMethods({
+     *     isReady: privy.isReady,
+     *     isAuthenticated: !!privy.user,
+     *     user: privy.user,
+     *     login: privy.login,
+     *     logout: privy.logout,
+     *     getAccessToken,
+     *     getIdentityToken,
+     *     getWalletProvider: async () => {
+     *       if (!wallet.wallets[0]) return null;
+     *       const provider = await wallet.wallets[0].getProvider();
+     *       return {
+     *         address: wallet.wallets[0].address,
+     *         signMessage: provider.signMessage,
+     *         signTransaction: provider.signTransaction,
+     *         signAndSendTransaction: provider.signAndSendTransaction,
+     *       };
+     *     },
+     *   });
+     * }, [privy.isReady, privy.user, wallet.wallets]);
+     * ```
+     */
+    setPrivyMethods(methods: PrivyExpoMethods): void;
+    login(): Promise<User | null>;
+    runTransaction(_evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    signMessage(message: string): Promise<string>;
+    signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    signAndSubmitTransaction(transaction: Transaction | VersionedTransaction, feePayer?: PublicKey): Promise<string>;
+    restoreSession(): Promise<User | null>;
+    logout(): Promise<void>;
+    getNativeMethods(): Promise<any>;
+    /**
+     * Mint a Tarobase session from a Privy Solana wallet by signing the canonical
+     * SIWS challenge (nonce -> genSolanaMessage -> wallet.signMessage). This reuses
+     * createSessionWithSignature — the exact path Phantom, the mobile wallet
+     * adapter, and the guest device-key use — so the bounded /session issuer mints
+     * the session with no Privy-specific verification (it arrives as a Solana
+     * wallet signature, defaulting to authMethod 'phantom' server-side).
+     */
+    private createSession;
+    private getWalletOrThrow;
+    private signAndSubmitInternal;
+    private getRpcUrl;
+    private ensureReady;
+}

package/dist/auth/providers/privy-wallet-provider.d.ts

@@ -0,0 +1,80 @@
+import type { EVMTransaction, SolTransaction, TransactionResult, AuthProvider, User, SetOptions } from '@bounded-sh/core';
+import { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
+export declare class PrivyWalletProvider implements AuthProvider {
+    private static instance;
+    private containerElement;
+    private networkUrl;
+    private chainId;
+    private root;
+    private privyMethods;
+    private privyConfig;
+    private pendingLogin;
+    private pendingTransaction;
+    private pendingSignTransaction;
+    private pendingSignMessage;
+    private pendingSignAndSubmitTransaction;
+    constructor(appName: string | null, appLogoUrl: string | null, privyConfig?: {
+        appId: string;
+        config: any;
+    }, networkUrl?: string | null);
+    static getInstance(appName: string | null, appLogoUrl: string | null, privyConfig: any): PrivyWalletProvider;
+    private initialize;
+    login(): Promise<User | null>;
+    getNativeMethods(): Promise<any>;
+    logout(): Promise<void>;
+    runTransaction(_evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    /**
+     * Signs a Solana transaction without submitting it.
+     *
+     * This method handles blockhash automatically if not set - you do NOT need to
+     * set recentBlockhash on the transaction before calling this method.
+     * The network/RPC URL is derived from the provider's configuration (set during initialization).
+     *
+     * @param transaction - The transaction to sign (Transaction or VersionedTransaction)
+     * @returns The signed transaction
+     */
+    signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    /**
+     * Signs and submits a Solana transaction to the network.
+     *
+     * This method handles blockhash and transaction confirmation automatically - you do NOT need to
+     * set recentBlockhash or lastValidBlockHeight on the transaction before calling this method.
+     * The network/RPC URL is derived from the provider's configuration (set during initialization).
+     *
+     * @param transaction - The transaction to sign and submit (Transaction or VersionedTransaction)
+     * @param feePayer - Optional fee payer public key. If not provided and the transaction doesn't
+     *                   already have a feePayer set, the connected wallet address will be used.
+     *                   Useful for co-signing scenarios where a different account pays the fees.
+     * @returns The transaction signature
+     */
+    signAndSubmitTransaction(transaction: Transaction | VersionedTransaction, feePayer?: PublicKey): Promise<string>;
+    private getRpcUrl;
+    /**
+     * Internal sign transaction - serializes and signs via Privy
+     * Returns the raw result from Privy (Uint8Array)
+     * This mirrors exactly what runTransaction was doing
+     */
+    private signTransactionRaw;
+    /**
+     * Deserialize a signed transaction from Uint8Array to Transaction object
+     */
+    private deserializeSignedTransaction;
+    /**
+     * Internal sign and submit - handles Surfnet vs non-Surfnet logic
+     * This is the core submission logic used by both signAndSubmitTransaction and runTransaction
+     *
+     * For Surfnet: sign with signTransactionRaw, then sendRawTransaction
+     * For non-Surfnet: use Privy's signAndSendTransaction (combined operation)
+     */
+    private signAndSubmitInternal;
+    signMessage(message: string): Promise<string>;
+    restoreSession(): Promise<User | null>;
+    private createSession;
+    /**
+     * Waits for a wallet matching the session address to appear in the wallets array.
+     * This handles the timing gap where Privy's embedded wallet (created for email login users)
+     * may not yet be in the useWallets() array when signTransaction is called immediately after login.
+     */
+    private waitForMatchingWallet;
+    private ensureReady;
+}

package/dist/auth/providers/sol/sol-utils.d.ts

@@ -0,0 +1,2 @@
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+export declare function deserializeTransaction(tx: string | Buffer): Promise<Transaction | VersionedTransaction>;

package/dist/auth/providers/solana-mobile-wallet-provider.d.ts

@@ -0,0 +1,155 @@
+import type { EVMTransaction, SolTransaction, TransactionResult, User, AuthProvider, SetOptions } from '@bounded-sh/core';
+import { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
+export interface SolanaMobileWalletConfig {
+    /** App identity shown to the wallet during authorization */
+    appIdentity?: {
+        name?: string;
+        uri?: string;
+        icon?: string;
+    };
+    /** Solana cluster: 'mainnet-beta' | 'devnet' | 'testnet' */
+    cluster?: string;
+    /** Theme for any UI elements: 'light' or 'dark' */
+    theme?: 'light' | 'dark';
+}
+/**
+ * Detects whether the current environment is a mobile browser capable of
+ * Mobile Wallet Adapter (MWA) communication.
+ *
+ * Returns true on Android browsers (Chrome, etc.) where MWA intents work,
+ * or inside a Seeker/Saga in-app browser context.
+ */
+export declare function isMobileWalletAvailable(): boolean;
+/**
+ * Registers Mobile Wallet Adapter as a wallet-standard wallet so it appears
+ * in wallet selection UIs and can be discovered by other wallet-standard consumers.
+ *
+ * Call this once at app startup (in a browser-only / non-SSR context).
+ *
+ * @param config - App identity and optional remote host authority for desktop QR code support
+ */
+export declare function registerMobileWalletAdapter(config?: {
+    appIdentity?: {
+        name?: string;
+        uri?: string;
+        icon?: string;
+    };
+    chains?: string[];
+    remoteHostAuthority?: string;
+    /**
+     * Optional custom wallet-not-found handler. If omitted, the SDK installs
+     * a no-op (NOT the library default) — see comment below.
+     */
+    onWalletNotFound?: (mobileWalletAdapter: any) => Promise<void>;
+}): Promise<void>;
+/**
+ * SolanaMobileWalletProvider implements the AuthProvider interface using
+ * Solana Mobile's wallet-standard wrapper (`LocalSolanaMobileWalletAdapterWallet`).
+ *
+ * Why wallet-standard and not the raw MWA protocol: as of
+ * `@solana-mobile/wallet-standard-mobile@0.5.0+`, the wallet's internal
+ * `#transact` calls `checkLocalNetworkAccessPermission()` before opening the
+ * localhost WebSocket. That helper renders a three-stage UX flow Solana
+ * Mobile designed specifically to defuse Chrome's Local Network Access
+ * permission dialog (which renders with disabled buttons on Android Chrome,
+ * the source of the long-running Seeker MWA bug):
+ *
+ *   1. "Allow connections to your wallet" informational modal.
+ *   2. Chrome's permission prompt (interactive because it's spawned as a
+ *      fresh user gesture from step 1).
+ *   3. "Ready to connect!" success modal.
+ *
+ * `checkLocalNetworkAccessPermission` is internal to the library — it's not
+ * exported. The only way to invoke it is to go through the wallet's
+ * `standard:connect` / `solana:sign*` features, which is what this provider
+ * does.
+ *
+ * Notes on UX: login uses two wallet popups in succession — `standard:connect`
+ * (authorize) and `solana:signMessage` (sign the Tarobase nonce). The
+ * previous implementation combined both inside a single `transact` callback;
+ * splitting them is the cost of going through wallet-standard, and is
+ * acceptable given the alternative was broken on Seeker.
+ */
+export declare class SolanaMobileWalletProvider implements AuthProvider {
+    private static instance;
+    private networkUrl;
+    private config;
+    private appIdentity;
+    /** Raw cluster name (e.g. 'mainnet-beta'); mapped via mapChainToWalletStandard. */
+    private cluster;
+    /** LocalSolanaMobileWalletAdapterWallet, lazy-constructed in ensureWallet(). */
+    private wallet;
+    constructor(networkUrl?: string | null, config?: SolanaMobileWalletConfig);
+    static getInstance(networkUrl: string | null, config: SolanaMobileWalletConfig): SolanaMobileWalletProvider;
+    /** Lazy-construct LocalSolanaMobileWalletAdapterWallet on first need. */
+    private ensureWallet;
+    /**
+     * Ensure the wallet has an active authorization. After a Tarobase session
+     * is restored from storage on cold-start, `wallet.accounts` is empty until
+     * we silently reconnect from the AuthorizationCache. If the cache is also
+     * empty, fall back to interactive `login()` (which surfaces the three-stage
+     * Solana Mobile LNA flow + wallet popups).
+     *
+     * Returns the wallet-standard `WalletAccount` to use for sign operations.
+     */
+    private ensureAuthorized;
+    /** Returns the active wallet-standard chain identifier (e.g. 'solana:mainnet'). */
+    private getChain;
+    /**
+     * Cached MWA auth_token returned by `wallet.authorize()`. Reused by
+     * subsequent native transact() calls (signMessage / signTransaction)
+     * so the user doesn't get the wallet-pick popup on every operation.
+     * Persisted to platform storage and hydrated by the constructor on
+     * native; cleared by logout() and on `ERROR_REAUTHORIZE`.
+     */
+    private nativeAuthToken;
+    /** Cached public key string for the connected MWA wallet (native). */
+    private nativeAddress;
+    /**
+     * Dynamically import and unwrap `transact` from the MWA web3js
+     * package. The package is externalized in rollup.config.js so this
+     * resolves to `lib/cjs/index.native.js` (TurboModule-backed) on
+     * Metro and `lib/esm/index.browser.js` (WebSocket) on webpack/vite
+     * per their respective platform conditions. Handles Metro's CJS-to-
+     * ESM interop variance (`mod.transact` vs `mod.default?.transact`).
+     */
+    private loadTransact;
+    /**
+     * Cache and persist a fresh MWA auth_token + address. Called from
+     * `_loginNative` after a successful authorize. Storage failures are
+     * non-fatal (next cold-start re-auths).
+     */
+    private persistNativeAuth;
+    /** Clear cached + persisted native auth state. */
+    private clearNativeAuth;
+    /**
+     * Classify an MWA-native error as a user cancellation. User-cancel
+     * shouldn't surface as a red console.error; callers can swallow or
+     * show a softer message. MWA spec codes plus the same substring
+     * checks the web path uses to catch wallet-specific phrasing.
+     */
+    private isNativeUserCancel;
+    /**
+     * Native MWA login via @solana-mobile/mobile-wallet-adapter-protocol-web3js.
+     * Used in true React Native (Expo) environments where wallet-standard-mobile's
+     * web universal-link path doesn't apply. Does authorize + signMessage in a
+     * single transact() roundtrip — intent-based MWA doesn't need the two-popup
+     * dance the web path uses (no Chrome activation-loss concern). Persists the
+     * resulting auth_token so cold-start can reauthorize without a fresh popup.
+     */
+    private _loginNative;
+    login(): Promise<User | null>;
+    restoreSession(): Promise<User | null>;
+    logout(): Promise<void>;
+    signMessage(message: string): Promise<string>;
+    signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    signAndSubmitTransaction(transaction: Transaction | VersionedTransaction, feePayer?: PublicKey): Promise<string>;
+    runTransaction(_evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    getNativeMethods(): Promise<any>;
+    private getRpcUrl;
+}
+declare global {
+    interface Window {
+        CUSTOM_TAROBASE_APP_ID_HEADER?: string;
+    }
+}

package/dist/auth/providers/transaction-utils.d.ts

@@ -0,0 +1,10 @@
+import { Connection } from '@solana/web3.js';
+/**
+ * Extracts a human-readable error message from Solana transaction logs.
+ */
+export declare function extractTransactionError(err: any, logMessages?: string[] | null): string;
+/**
+ * Polls getSignatureStatuses until the transaction is confirmed, then checks for errors.
+ * Throws if the transaction failed on-chain. Returns parsed transaction info on success.
+ */
+export declare function confirmAndCheckTransaction(connection: Connection, signature: string): Promise<any>;

package/dist/global.d.ts

@@ -0,0 +1,13 @@
+import { AuthProvider, User, ClientConfig } from '@bounded-sh/core';
+import { LoginOptions } from './auth';
+export declare function init(newConfig: Partial<ClientConfig>): Promise<void>;
+export declare function onAuthStateChanged(callback: (user: User | null) => void): void;
+export declare function onAuthLoadingChanged(callback: (loading: boolean) => void): void;
+export declare function setAuthLoading(loading: boolean): void;
+export declare function getAuthLoading(): boolean;
+export declare function login(options?: LoginOptions): Promise<User | null>;
+export type { LoginOptions };
+export declare function logout(): Promise<void>;
+export declare function setCurrentUser(user: User | null): void;
+export declare function getCurrentUser(): User | null;
+export declare function setAuthProviderInstance(provider: AuthProvider): void;