@bounded-sh/core 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,157 @@
+import { PublicKey, TransactionInstruction, Transaction, VersionedTransaction } from "@solana/web3.js";
+import { SetOptions } from "./client/operations";
+export interface AuthProvider {
+    login(): Promise<User | null>;
+    runTransaction(evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    signMessage(message: string): Promise<string>;
+    signMessageMock?(message: string): Promise<string>;
+    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>;
+    restoreSession(): Promise<User | null>;
+    logout(): Promise<void>;
+    getNativeMethods(): Promise<any>;
+}
+export interface User {
+    /**
+     * Universal stable identity of the user (resolves @user.id). For wallet/SIWS
+     * logins this EQUALS `address`; for email/social (Bounded Better Auth) logins
+     * it is the account identity (and `address` may be null). Derived from the
+     * idToken's `custom:userId` claim, falling back to `custom:walletAddress` for
+     * tokens minted before the claim-split. Used for ownership/membership/identity.
+     *
+     * Optional for backwards compatibility: existing apps that only read
+     * `user.address` keep working unchanged. New code should prefer `user.id` as
+     * the principal. Always present for a session derived from a real idToken;
+     * may be undefined only for legacy/manually-constructed User objects.
+     */
+    id?: string;
+    /**
+     * REAL onchain wallet address. Present for wallet/SIWS logins; `null` for
+     * email-only logins (which have no wallet until they link one). Kept for
+     * backwards compatibility — for wallet users `id === address`.
+     */
+    address: string;
+    /**
+     * Verified, lowercased email of the user — present only for email-login
+     * (Bounded Better Auth) sessions; `null`/absent for wallet/SIWS sessions.
+     * Resolves @user.email in offchain policies.
+     */
+    email?: string | null;
+    /**
+     * True when this is a zero-friction GUEST (anonymous) session created via
+     * `signInAnonymously()` — a durable device-keypair identity that owns data
+     * but has no email/real credential yet. Mirrors Firebase's `user.isAnonymous`
+     * / Supabase's `is_anonymous`. Flips to `false` once the guest is upgraded
+     * (links an email/social credential), with `id` preserved across the upgrade.
+     * Apps use this to decide whether to show an "upgrade / save your account"
+     * prompt. `false`/absent for real (email/social/wallet) logins.
+     */
+    isAnonymous?: boolean;
+    provider: AuthProvider;
+}
+export interface EVMTransaction {
+    contractAddress: string;
+    contractAbi: string | any;
+    functionName: string;
+    value: string;
+    txArgs: any[];
+}
+export interface SolTransaction {
+    appId: string;
+    txArgs: any[];
+    lutKey: PublicKey | null;
+    /** Complete set of LUT addresses to use (includes lutKey when present). When provided, takes precedence over lutKey. */
+    additionalLutAddresses?: string[];
+    network: string;
+    preInstructions: TransactionInstruction[];
+    /** Base64-encoded VersionedTransaction prebuilt server-side for sponsorship and/or required co-signers. */
+    signedTransaction?: string;
+}
+export interface TransactionResult {
+    transactionSignature?: any;
+    signedTransaction?: any;
+    blockNumber: number;
+    gasUsed: string;
+    data?: any;
+}
+export interface TransactionReceipt {
+}
+export interface SubscriptionOptions {
+    /**
+     * Structured MongoDB-style filter (same shape as GetOptions.filter), e.g.
+     * `{ status: "open", amount: { $gt: 10 } }`. Deterministic; the live feed only
+     * delivers documents matching the filter (and obeying the read rule).
+     */
+    filter?: Record<string, any>;
+    /**
+     * Sort spec applied server-side to the live feed (same shape/semantics as
+     * GetOptions.sort), e.g. `{ createdAt: -1 }` (1 = asc, -1 = desc). The server
+     * sorts the read-authorized result set before delivering it.
+     */
+    sort?: Record<string, number>;
+    prompt?: string;
+    /**
+     * Include documents from sub-paths (nested collections) in the live feed, same
+     * as GetOptions.includeSubPaths. The server applies it to both initial data and
+     * deltas.
+     */
+    includeSubPaths?: boolean;
+    /** Relationship shape for joined data (e.g., { owner: {}, posts: { comments: {} } }) */
+    shape?: Record<string, any>;
+    /** Maximum number of items to return (opt-in pagination) */
+    limit?: number;
+    /** Opaque cursor for cursor-based pagination (used with limit) */
+    cursor?: string;
+    /** Override the app ID for this subscription (instead of the configured default) */
+    appId?: string;
+    onData?: (data: any) => void;
+    onError?: (error: any) => void;
+    /**
+     * @internal Per-subscription auth override. The server `WalletClient` sets this
+     * (via `subscribe()`) so the WS connection authenticates as that wallet's
+     * identity instead of the ambient `BOUNDED_PRIVATE_KEY` env keypair. Mirrors
+     * `RequestOverrides`; only the fields the subscribe path consumes. App code
+     * never sets this — it's threaded internally.
+     */
+    _overrides?: {
+        _getAuthHeaders?: () => Promise<Record<string, string>>;
+        _walletAddress?: string;
+        _clearAuth?: () => Promise<void>;
+    };
+}
+export type TransactionOptions = {
+    shouldSubmit?: boolean;
+};
+export interface OffchainInstruction {
+    type: 'set' | 'delete';
+    path: string;
+    data?: Record<string, any>;
+}
+export interface OffchainTransaction {
+    id: string;
+    version: 1;
+    feePayer: string;
+    instructions: OffchainInstruction[];
+    message: string;
+    createdAt: number;
+    expiresAt: number;
+    appId: string;
+    nonce: string;
+}
+export interface SignedOffchainTransaction {
+    transaction: OffchainTransaction;
+    signature: string;
+}

package/dist/utils/api.d.ts

@@ -0,0 +1,11 @@
+declare global {
+    interface Window {
+        CUSTOM_TAROBASE_APP_ID_HEADER?: string;
+    }
+}
+export declare function makeApiRequest(method: string, urlPath: string, data?: any, _overrides?: {
+    headers?: Record<string, string>;
+    _getAuthHeaders?: () => Promise<Record<string, string>>;
+    _clearAuth?: () => Promise<void>;
+    timeout?: number;
+}): Promise<any>;

package/dist/utils/auth-api.d.ts

@@ -0,0 +1,10 @@
+export declare function genNonce(): Promise<any>;
+export declare function genAuthNonce(): Promise<any>;
+export declare function createSessionWithSignature(address: string, message: string, signature: string): Promise<any>;
+export declare function refreshSession(refreshToken: string, issuer?: string): Promise<any>;
+/**
+ * Revoke a session's refresh-token family server-side (logout). Best-effort: if the
+ * call fails the local logout still proceeds. Routes to the minting issuer.
+ */
+export declare function revokeSession(refreshToken: string, issuer?: string): Promise<void>;
+export declare function signSessionCreateMessage(_signMessageFunction: (message: string) => Promise<string>): Promise<void>;

package/dist/utils/core-platform.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Safe base64 helpers for tarobase-core.
+ *
+ * Uses the global atob/btoa when available (browser, RN with polyfill),
+ * falls back to the 'buffer' package (Node.js / SSR / RN without polyfill).
+ *
+ * These are used instead of bare `atob()`/`btoa()` so the core package
+ * works in React Native without requiring the consumer to polyfill globals.
+ */
+export declare function safeAtob(input: string): string;
+export declare function safeBtoa(input: string): string;
+/**
+ * Decode a base64url-encoded string (used by JWT payloads).
+ * Normalises base64url → standard base64 before decoding.
+ */
+export declare function decodeBase64Url(input: string): string;

package/dist/utils/rn-session-manager.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Session manager for React Native environments.
+ *
+ * Drop-in replacement for WebSessionManager that uses a pluggable
+ * StorageAdapter instead of browser localStorage, and a pluggable
+ * base64-decode instead of the browser's atob().
+ *
+ * Consumers must call ReactNativeSessionManager.configure() once at
+ * startup to supply these adapters (e.g. MMKV, AsyncStorage wrapper,
+ * base64 polyfill).
+ */
+/**
+ * Synchronous storage adapter for React Native session persistence.
+ *
+ * **Security: tokens (access, identity, refresh) are stored as plaintext JSON.**
+ * Use an encrypted storage backend in production — for example:
+ *   - MMKV with an encryption key (`new MMKV({ encryptionKey: '...' })`)
+ *   - expo-secure-store
+ *   - react-native-keychain
+ *
+ * Plaintext token storage on a rooted/jailbroken device is a credential theft risk.
+ */
+export interface RNStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface RNSessionConfig {
+    storage: RNStorageAdapter;
+    /** base64 → binary string (replaces browser atob). */
+    atob: (input: string) => string;
+}
+export declare class ReactNativeSessionManager {
+    private static TAROBASE_SESSION_STORAGE_KEY;
+    /**
+     * Must be called once before any other method.
+     *
+     * ```ts
+     * import { ReactNativeSessionManager } from '@bounded-sh/core';
+     * import { MMKV } from 'react-native-mmkv';
+     * import { decode } from 'base-64';
+     *
+     * const mmkv = new MMKV();
+     * ReactNativeSessionManager.configure({
+     *   storage: {
+     *     getItem: (k) => mmkv.getString(k) ?? null,
+     *     setItem: (k, v) => mmkv.set(k, v),
+     *     removeItem: (k) => mmkv.delete(k),
+     *   },
+     *   atob: decode,
+     * });
+     * ```
+     */
+    static configure(cfg: RNSessionConfig): void;
+    /**
+     * Whether configure() has been called. This is the canonical "are we on
+     * React Native?" signal used by getActiveSessionManager(): RN consumers MUST
+     * call configure() at startup, while web/Node never do. Far more reliable
+     * than sniffing `typeof window` (React Native defines a global `window`, so
+     * that test misclassifies RN as web and routes session writes to a
+     * non-existent localStorage).
+     */
+    static isConfigured(): boolean;
+    private static getStorage;
+    private static decodeBase64;
+    /**
+     * Decode a base64url-encoded string (used by JWT payloads).
+     * Normalises base64url → standard base64 before decoding.
+     */
+    private static decodeBase64Url;
+    static storeSession(address: string, accessToken: string, idToken: string, refreshToken: string, issuer?: string): Promise<void>;
+    static getSession(): Promise<{
+        address: string;
+        session: any;
+    } | null>;
+    static clearSession(): void;
+    static isAuthenticated(): boolean;
+    static getIdToken(): string | null;
+    /** The issuer base that minted this session (for routing silent refresh). */
+    static getIssuer(): string | null;
+    static getRefreshToken(): string | null;
+    static updateIdTokenAndAccessToken(idToken: string, accessToken: string, refreshToken?: string): Promise<void>;
+}
+export {};

package/dist/utils/server-session-manager.d.ts

@@ -0,0 +1,35 @@
+import { Keypair } from "@solana/web3.js";
+/**
+ * Server-side SessionManager
+ * --------------------------
+ *  • Default singleton via `ServerSessionManager.instance` (reads keypair from env)
+ *  • Per-keypair instances via `ServerSessionManager.forKeypair(kp)`
+ *  • Keeps session data in-memory for the life of the instance
+ *  • If `getSession()` finds no cached session it calls `createSession()`
+ *    to obtain fresh tokens.
+ */
+export interface ServerSession {
+    address: string;
+    accessToken: string;
+    idToken: string;
+    refreshToken: string;
+}
+export declare class ServerSessionManager {
+    static readonly instance: ServerSessionManager;
+    private session;
+    private pendingSession;
+    private readonly keypair;
+    private constructor();
+    /**
+     * Create a session manager for a specific keypair.
+     * Each instance has its own independent session cache.
+     */
+    static forKeypair(keypair: Keypair): ServerSessionManager;
+    private createSession;
+    getSession(): Promise<ServerSession>;
+    setSession(session: ServerSession): void;
+    clearSession(): void;
+    isAuthenticated(): boolean;
+    getIdToken(): string | null;
+    getRefreshToken(): string | null;
+}

package/dist/utils/session-manager.d.ts

@@ -0,0 +1,31 @@
+import { WebSessionManager } from './web-session-manager';
+/**
+ * The shared static shape of both client session managers. WebSessionManager
+ * (localStorage) and ReactNativeSessionManager (pluggable StorageAdapter) expose
+ * an identical static API over the SAME storage key, so either one is a drop-in
+ * for the other.
+ */
+export type ClientSessionManager = typeof WebSessionManager;
+/**
+ * Return the active CLIENT session manager for the current runtime.
+ *
+ * This is the single source of truth for "which store holds the session token"
+ * and MUST be used everywhere the client reads/writes the session (login,
+ * restore, logout, and — critically — the per-request auth-header path in
+ * utils.ts). Previously this decision was made ad-hoc with
+ * `typeof window !== 'undefined' ? WebSessionManager : ReactNativeSessionManager`,
+ * which is wrong on React Native: RN defines a global `window`, so that test
+ * picked WebSessionManager and then hit a non-existent `localStorage` — the
+ * session was silently dropped (or threw), so every authenticated request 403'd.
+ *
+ * Decision rule: if a consumer configured the React Native session manager
+ * (ReactNativeSessionManager.configure(), which RN apps call once at startup and
+ * web/Node never do), we're on RN — use it. Otherwise use the localStorage-backed
+ * WebSessionManager (which itself no-ops gracefully in Node/SSR where there is no
+ * `window`). This changes ONLY React Native behavior; web and Node are unchanged.
+ *
+ * NOTE: this intentionally does NOT cover the SERVER (keypair) path — callers that
+ * branch on `isServer` keep using ServerSessionManager and only fall through to
+ * getActiveSessionManager() for the browser/RN client case.
+ */
+export declare function getActiveSessionManager(): ClientSessionManager;