better-near-auth 0.3.3 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@
 
 </div>
 
-This [Better Auth](https://better-auth.com) plugin enables secure authentication via NEAR wallets and keypairs by following the [NEP-413 standard](https://github.com/near/NEPs/blob/master/neps/nep-0413.md). It leverages [near-sign-verify](https://github.com/elliotBraem/near-sign-verify), [near-kit](https://kit.near.tools/), and [Hot Connect](https://github.com/azbang/hot-connector) to provide a complete drop-in solution with session management, secure defaults, and automatic profile integration.
+This [Better Auth](https://better-auth.com) plugin enables secure authentication via NEAR wallets and keypairs by following the [NEP-413 standard](https://github.com/near/NEPs/blob/master/neps/nep-0413.md). It leverages [near-sign-verify](https://github.com/elliotBraem/near-sign-verify), [near-kit](https://kit.near.tools/), and [NEAR Connect](https://github.com/azbang/near-connect) to provide a complete drop-in solution with session management, secure defaults, and automatic profile integration.
 
 ## Installation
 
@@ -57,7 +57,7 @@ npm install better-near-auth
     export const authClient = createAuthClient({
         plugins: [
             siwnClient({
-                domain: "myapp.com", // this doesn't actually do anything yet... taking suggestions
+                recipient: "myapp.com",
                 networkId: "mainnet", // optional, default is "mainnet"
             })
         ],
@@ -66,42 +66,9 @@ npm install better-near-auth
 
 ## Usage
 
-### Two-Step Authentication Flow
-
-The plugin uses a secure two-step authentication process:
-
-1. **Step 1**: Connect wallet and cache nonce
-2. **Step 2**: Sign message and authenticate
-
-```ts title="two-step-auth.ts"
-// Step 1: Connect wallet and get nonce
-await authClient.requestSignIn.near(
-  { recipient: "myapp.com" },
-  {
-    onSuccess: () => {
-      console.log("Wallet connected, nonce cached!");
-    },
-    onError: (error) => {
-      console.error("Wallet connection failed:", error.message);
-    }
-  }
-);
-
-// Step 2: Sign message and authenticate
-await authClient.signIn.near(
-  { recipient: "myapp.com" },
-  {
-    onSuccess: () => {
-      console.log("Successfully signed in!");
-    },
-    onError: (error) => {
-      console.error("Sign in failed:", error.message);
-    }
-  }
-);
-```
+### Single-Step Authentication Flow
 
-### Complete React Component Example
+The plugin uses a single-step authentication flow that automatically handles both wallet connection and message signing:
 
 ```tsx title="LoginButton.tsx"
 import { authClient } from "./auth-client";
@@ -109,56 +76,71 @@ import { useState } from "react";
 
 export function LoginButton() {
   const { data: session } = authClient.useSession();
-  const [isConnectingWallet, setIsConnectingWallet] = useState(false);
   const [isSigningIn, setIsSigningIn] = useState(false);
-  
-  // Get account ID from near-kit client
-  const accountId = authClient.near.getAccountId();
 
   if (session) {
     return (
       <div>
         <p>Welcome, {session.user.name}!</p>
-        <button onClick={() => authClient.signOut()}>Sign out</button>
+        <button onClick={() => authClient.near.disconnect()}>Sign out</button>
       </div>
     );
   }
 
-  const handleWalletConnect = async () => {
-    setIsConnectingWallet(true);
-    
-    try {
-      await authClient.requestSignIn.near(
-        { recipient: "myapp.com" },
-        {
-          onSuccess: () => {
-            setIsConnectingWallet(false);
-            console.log("Wallet connected!");
-          },
-          onError: (error) => {
-            setIsConnectingWallet(false);
-            console.error("Wallet connection failed:", error.message);
-          },
-        }
-      );
-    } catch (error) {
-      setIsConnectingWallet(false);
-      console.error("Authentication error:", error);
-    }
-  };
-
   const handleSignIn = async () => {
     setIsSigningIn(true);
     
-    try {
-      await authClient.signIn.near(
-        { recipient: "myapp.com" },
-        {
-          onSuccess: () => {
-            setIsSigningIn(false);
-            console.log("Successfully signed in!");
-          },
-          onError: (error) => {
+    await authClient.signIn.near({
+      onSuccess: () => {
+        setIsSigningIn(false);
+        console.log("Successfully signed in!");
+      },
+      onError: (error) => {
+        setIsSigningIn(false);
+        console.error("Sign in failed:", error.message);
+      },
+    });
+  };
+
+  return (
+    <button onClick={handleSignIn} disabled={isSigningIn}>
+      {isSigningIn ? "Signing in..." : "Sign in with NEAR"}
+    </button>
+  );
+}
+```
+
+### How It Works
+
+The `signIn.near()` method automatically:
+
+1. **Checks wallet capabilities** - Detects if the wallet supports `signInAndSignMessage`
+2. **Single-step flow** (supported wallets): One popup for connection + signing
+3. **Two-step fallback** (unsupported wallets): Automatic fallback to connect then sign
+
+**Supported wallets for single-step:**
+- Meteor Wallet
+- Intear Wallet
+- NEAR CLI
+- HOT Wallet
+- MyNearWallet
+- And more...
+
+### Manual Two-Step Flow (Optional)
+
+If you need explicit control over the connection step:
+
+```ts
+// Step 1: Connect wallet (optional, for explicit control)
+await authClient.requestSignIn.near({
+  onSuccess: () => console.log("Wallet connected"),
+});
+
+// Step 2: Sign and authenticate
+await authClient.signIn.near({
+  onSuccess: () => console.log("Signed in!"),
+});
+```
             setIsSigningIn(false);
             console.error("Sign in failed:", error.message);
           },
@@ -172,15 +154,9 @@ export function LoginButton() {
 
   return (
     <div>
-      {!accountId ? (
-        <button onClick={handleWalletConnect} disabled={isConnectingWallet}>
-          {isConnectingWallet ? "Connecting..." : "Connect NEAR Wallet"}
-        </button>
-      ) : (
-        <button onClick={handleSignIn} disabled={isSigningIn}>
-          {isSigningIn ? "Signing in..." : `Sign in with NEAR (${accountId})`}
-        </button>
-      )}
+      <button onClick={handleSignIn} disabled={isSigningIn}>
+        {isSigningIn ? "Signing in..." : "Sign in with NEAR"}
+      </button>
     </div>
   );
 }
@@ -235,7 +211,7 @@ The SIWN plugin accepts the following configuration options:
 
 The SIWN client plugin accepts the following configuration options:
 
-* **domain**: Domain identifier... idk what it should do yet. Maybe shade agent.
+* **recipient**: The recipient identifier for NEP-413 messages (must match server config)
 * **networkId**: NEAR network to use ("mainnet" or "testnet"). Default is "mainnet"
 
 ```ts title="auth-client.ts"
@@ -245,7 +221,7 @@ import { siwnClient } from "better-near-auth/client";
 export const authClient = createAuthClient({
   plugins: [
     siwnClient({
-      domain: "myapp.com",
+      recipient: "myapp.com",
       networkId: "testnet", // Use testnet
     }),
   ],
@@ -280,14 +256,17 @@ The client plugin provides the following actions:
 - `getNearClient()` - Get the near-kit client instance
 - `getAccountId()` - Get the currently connected account ID
 - `disconnect()` - Disconnect wallet and clear cached data
+- `link(callbacks?)` - Link a NEAR account to the current session
+- `unlink(params)` - Unlink a NEAR account from the current session
+- `listAccounts()` - List all linked NEAR accounts
 
 #### `authClient.requestSignIn`
 
-- `near(params, callbacks?)` - Connect wallet and cache nonce (Step 1)
+- `near(callbacks?)` - Connect wallet and cache nonce (for two-step flow)
 
 #### `authClient.signIn`
 
-- `near(params, callbacks?)` - Sign message and authenticate (Step 2)
+- `near(callbacks?)` - Sign message and authenticate (single-step or two-step)
 
 ### Callback Interface
 
@@ -303,10 +282,10 @@ interface AuthCallbacks {
 Common error codes you may encounter:
 
 - `SIGNER_NOT_AVAILABLE` - NEAR wallet not available
-- `WALLET_NOT_CONNECTED` - Wallet not connected before signing
-- `NONCE_NOT_FOUND` - No valid cached nonce found
-- `ACCOUNT_MISMATCH` - Cached nonce doesn't match current account
-- `UNAUTHORIZED_INVALID_OR_EXPIRED_NONCE` - Server nonce expired or invalid
+- `WALLET_NOT_CONNECTED` - Wallet not connected before signing (two-step fallback)
+- `ACCOUNT_MISMATCH` - Cached nonce doesn't match current account (two-step fallback)
+- `UNAUTHORIZED_NONCE_REPLAY` - Nonce already used (replay attack detected)
+- `UNAUTHORIZED_INVALID_SIGNATURE` - Invalid signature verification
 
 ## Advanced Configuration
 
@@ -446,6 +425,67 @@ export const authClient = createAuthClient({
    - Testnet accounts must use "testnet", mainnet accounts use "mainnet"
 
 
+## Examples
+
+This repository includes example applications demonstrating how to use better-near-auth:
+
+### Browser to Server Example
+
+A full-stack example showing NEAR authentication in a browser app with a server backend.
+
+- **Location**: `examples/browser-2-server/`
+- **Live Demo**: [better-near-auth.near.page](https://better-near-auth.near.page)
+- **Tech Stack**: Hono, Drizzle ORM, React, TanStack Router
+
+**Running locally:**
+```bash
+# From repo root
+pnpm install
+cd examples/browser-2-server
+pnpm dev
+```
+
+**Deployment:**
+Each example can be deployed independently to Railway or other platforms. See the example's README for deployment instructions.
+
+## Development
+
+Interested in contributing? See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
+- Development setup
+- How to add changesets
+- Pull request guidelines
+- Release process
+
+**Quick start:**
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
+
+# Run type checking
+pnpm typecheck
+
+# Run tests
+pnpm test
+
+# Run example locally
+cd examples/browser-2-server && pnpm dev
+```
+
+**Build output:**
+- `dist/index.js` - Server plugin (ESM)
+- `dist/client.js` - Client plugin (ESM)
+- `dist/*.d.ts` - TypeScript declarations
+
+**Deployment workflow:**
+1. Make changes and create changeset
+2. Merge PR → Changesets publishes to npm
+3. Example auto-updates to use published version
+4. Railway auto-deploys
+5. Example reverts to `workspace:*` for next development cycle
+
 ## Links
 
 * [Better Auth Documentation](https://better-auth.com)
@@ -453,5 +493,6 @@ export const authClient = createAuthClient({
 * [NEP-413 Specification](https://github.com/near/NEPs/blob/master/neps/nep-0413.md)
 * [near-sign-verify](https://github.com/elliotBraem/near-sign-verify)
 * [near-kit](https://kit.near.tools/)
-* [Hot Connect](https://github.com/azbang/hot-connector)
-* [Example Implementation](https://better-near-auth.near.page)
+* [NEAR Connect](https://github.com/azbang/near-connect)
+* [Example Implementation](https://better-near-auth.near.page) - Live demo
+* [Contributing Guide](./CONTRIBUTING.md) - Development and contribution guidelines

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+import type { BetterAuthClientPlugin, BetterFetch, BetterFetchResponse } from "better-auth/client";
+import { atom } from "nanostores";
+import { Near } from "near-kit";
+import type { siwn } from "./index.js";
+import { type AccountId, type NonceRequestT, type NonceResponseT, type ProfileResponseT, type VerifyRequestT, type VerifyResponseT } from "./types.js";
+export interface AuthCallbacks {
+    onSuccess?: () => void;
+    onError?: (error: Error & {
+        status?: number;
+        code?: string;
+    }) => void;
+}
+export interface SIWNClientConfig {
+    recipient: string;
+    networkId?: "mainnet" | "testnet";
+}
+export interface CachedNonceData {
+    nonce: string;
+    accountId: string;
+    publicKey?: string | null;
+    networkId: string;
+    timestamp: number;
+}
+export interface SIWNClientActions {
+    near: {
+        nonce: (params: NonceRequestT) => Promise<BetterFetchResponse<NonceResponseT>>;
+        verify: (params: VerifyRequestT) => Promise<BetterFetchResponse<VerifyResponseT>>;
+        getProfile: (accountId?: AccountId) => Promise<BetterFetchResponse<ProfileResponseT>>;
+        getNearClient: () => Near;
+        getAccountId: () => string | null;
+        getState: () => {
+            accountId: string | null;
+            publicKey: string | null;
+            networkId: string;
+        } | null;
+        disconnect: () => Promise<void>;
+        link: (callbacks?: AuthCallbacks) => Promise<void>;
+        unlink: (params: {
+            accountId: string;
+            network?: "mainnet" | "testnet";
+        }) => Promise<BetterFetchResponse<{
+            success: boolean;
+            message: string;
+        }>>;
+        listAccounts: () => Promise<BetterFetchResponse<{
+            accounts: any[];
+        }>>;
+    };
+    requestSignIn: {
+        near: (callbacks?: AuthCallbacks) => Promise<void>;
+    };
+    signIn: {
+        near: (callbacks?: AuthCallbacks) => Promise<void>;
+    };
+}
+export interface SIWNClientPlugin extends BetterAuthClientPlugin {
+    id: "siwn";
+    $InferServerPlugin: ReturnType<typeof siwn>;
+    getAtoms: ($fetch: BetterFetch) => {
+        nearState: ReturnType<typeof atom<{
+            accountId: string | null;
+            publicKey: string | null;
+            networkId: string;
+        } | null>>;
+        cachedNonce: ReturnType<typeof atom<CachedNonceData | null>>;
+    };
+    getActions: ($fetch: BetterFetch) => SIWNClientActions;
+}
+export declare const siwnClient: (config: SIWNClientConfig) => SIWNClientPlugin;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}