better-near-auth 0.1.2 → 0.1.4

package/README.md

@@ -55,20 +55,41 @@ npm install better-near-auth
     import { siwnClient } from "better-near-auth/client";
 
     export const authClient = createAuthClient({
-        plugins: [siwnClient()],
+        plugins: [
+            siwnClient({
+                domain: "myapp.com", // this doesn't actually do anything yet... taking suggestions
+                networkId: "mainnet", // optional, default is "mainnet"
+            })
+        ],
     });
     ```
 
-
 ## Usage
 
-### One-Line Authentication
+### 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
 
-The simplest way to authenticate with NEAR:
+```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);
+    }
+  }
+);
 
-```ts title="sign-in-near.ts"
-const response = await authClient.signIn.near(
-  { recipient: "myapp.com", signer: window.near },
+// Step 2: Sign message and authenticate
+await authClient.signIn.near(
+  { recipient: "myapp.com" },
   {
     onSuccess: () => {
       console.log("Successfully signed in!");
@@ -78,8 +99,91 @@ const response = await authClient.signIn.near(
     }
   }
 );
+```
+
+### Complete React Component Example
+
+```tsx title="LoginButton.tsx"
+import { authClient } from "./auth-client";
+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 embedded fastintear client
+  const accountId = authClient.near.getAccountId();
+
+  if (session) {
+    return (
+      <div>
+        <p>Welcome, {session.user.name}!</p>
+        <button onClick={() => authClient.signOut()}>Sign out</button>
+      </div>
+    );
+  }
 
-console.log("Signed in as:", response.user.accountId);
+  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) => {
+            setIsSigningIn(false);
+            console.error("Sign in failed:", error.message);
+          },
+        }
+      );
+    } catch (error) {
+      setIsSigningIn(false);
+      console.error("Authentication error:", error);
+    }
+  };
+
+  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>
+      )}
+    </div>
+  );
+}
 ```
 
 ### Profile Access
@@ -96,6 +200,20 @@ const aliceProfile = await authClient.near.getProfile("alice.near");
 console.log("Alice's profile:", aliceProfile);
 ```
 
+### Wallet Management
+
+```ts title="wallet-management.ts"
+// Check if wallet is connected
+const accountId = authClient.near.getAccountId();
+console.log("Connected account:", accountId);
+
+// Get the embedded NEAR client
+const nearClient = authClient.near.getNearClient();
+
+// Disconnect wallet and clear cached data
+await authClient.near.disconnect();
+```
+
 ## Configuration Options
 
 ### Server Options
@@ -115,7 +233,10 @@ The SIWN plugin accepts the following configuration options:
 
 ### Client Options
 
-The SIWN client plugin doesn't require any configuration options:
+The SIWN client plugin accepts the following configuration options:
+
+* **domain**: Domain identifier... idk what it should do yet. Maybe shade agent.
+* **networkId**: NEAR network to use ("mainnet" or "testnet"). Default is "mainnet"
 
 ```ts title="auth-client.ts"
 import { createAuthClient } from "better-auth/client";
@@ -124,7 +245,8 @@ import { siwnClient } from "better-near-auth/client";
 export const authClient = createAuthClient({
   plugins: [
     siwnClient({
-      // Optional client configuration can go here
+      domain: "myapp.com",
+      networkId: "testnet", // Use testnet
     }),
   ],
 });
@@ -144,94 +266,51 @@ The SIWN plugin adds a `nearAccount` table to store user NEAR account associatio
 | isPrimary | boolean | Whether this is the user's primary account|
 | createdAt | date    | Creation timestamp                        |
 
-## Complete Implementation Example
+## API Reference
 
-Here's a complete example showing how to implement SIWN authentication:
+### Client Actions
 
-```ts title="auth.ts"
-import { betterAuth } from "better-auth";
-import { siwn } from "better-near-auth";
+The client plugin provides the following actions:
 
-export const auth = betterAuth({
-  database: {
-    provider: "sqlite",
-    url: "./db.sqlite"
-  },
-  plugins: [
-    siwn({
-      recipient: "myapp.com",
-      anonymous: false, // Require email for users
-      emailDomainName: "myapp.com",
-      
-      // Optional: Custom profile lookup
-      getProfile: async (accountId) => {
-        // Custom profile logic, falls back to NEAR Social
-      },
-    }),
-  ],
-});
-```
+#### `authClient.near`
 
-```ts title="auth-client.ts"
-import { createAuthClient } from "better-auth/client";
-import { siwnClient } from "better-near-auth/client";
+- `nonce(params)` - Request a nonce from the server
+- `verify(params)` - Verify an auth token with the server
+- `getProfile(accountId?)` - Get user profile from NEAR Social
+- `getNearClient()` - Get the embedded fastintear client
+- `getAccountId()` - Get the currently connected account ID
+- `disconnect()` - Disconnect wallet and clear cached data
 
-export const authClient = createAuthClient({
-  baseURL: "http://localhost:3000",
-  plugins: [siwnClient()],
-});
-```
+#### `authClient.requestSignIn`
 
-```tsx title="LoginButton.tsx"
-import { authClient } from "./auth-client";
-import { useState } from "react";
+- `near(params, callbacks?)` - Connect wallet and cache nonce (Step 1)
 
-export function LoginButton() {
-  const { data: session } = authClient.useSession();
-  const [isSigningIn, setIsSigningIn] = useState(false);
+#### `authClient.signIn`
 
-  if (session) {
-    return (
-      <div>
-        <p>Welcome, {session.user.name}!</p>
-        <button onClick={() => authClient.signOut()}>Sign out</button>
-      </div>
-    );
-  }
+- `near(params, callbacks?)` - Sign message and authenticate (Step 2)
 
-  const handleSignIn = async () => {
-    setIsSigningIn(true);
-    
-    try {
-      await authClient.signIn.near(
-        { recipient: "myapp.com", signer: window.near },
-        {
-          onSuccess: () => {
-            console.log("Successfully signed in!");
-          },
-          onError: (error) => {
-            console.error("Sign in failed:", error.message);
-          }
-        }
-      );
-    } catch (error) {
-      console.error("Authentication error:", error);
-    } finally {
-      setIsSigningIn(false);
-    }
-  };
+### Callback Interface
 
-  return (
-    <button onClick={handleSignIn} disabled={isSigningIn}>
-      {isSigningIn ? "Signing in..." : "Sign in with NEAR"}
-    </button>
-  );
+```typescript
+interface AuthCallbacks {
+  onSuccess?: () => void;
+  onError?: (error: Error & { status?: number; code?: string }) => void;
 }
 ```
 
+### Error Codes
+
+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
+
 ## Advanced Configuration
 
-For advanced use cases, you can customize the validation functions passed to `verify` in `near-sign-verify`:
+For advanced use cases, you can customize the validation functions:
 
 ```ts title="advanced-auth.ts"
 import { betterAuth } from "better-auth";
@@ -295,15 +374,78 @@ export const auth = betterAuth({
       },
       
       // Validate function call keys against allowed contracts
-      validateLimitedAccessKey: async ({ accountId, publicKey, contractId }) => {
+      validateLimitedAccessKey: async ({ accountId, publicKey, recipient }) => {
         const allowedContracts = ["myapp.near", "social.near"];
-        return contractId ? allowedContracts.includes(contractId) : true;
+        return recipient ? allowedContracts.includes(recipient) : true;
       },
     }),
   ],
 });
 ```
 
+## Network Support
+
+The plugin automatically detects the network from the account ID:
+
+- Accounts ending with `.testnet` use the testnet network
+- All other accounts use the mainnet network
+
+You can configure the client to use a specific network:
+
+```ts title="testnet-config.ts"
+export const authClient = createAuthClient({
+  plugins: [
+    siwnClient({
+      domain: "myapp.com",
+      networkId: "testnet", // Use testnet
+    }),
+  ],
+});
+```
+
+## Security Features
+
+### NEP-413 Compliance
+- Follows NEAR Enhancement Proposal 413 for secure message signing
+- Implements proper nonce handling to prevent replay attacks
+- Validates message format and recipient information
+
+### Nonce Management
+- Unique nonce storage per account/network/publicKey combination
+- 15-minute server-side expiration for nonces
+- 5-minute client-side cache expiration
+- Automatic cleanup after successful authentication
+
+### Access Key Support
+- Supports both full access keys and function call access keys
+- Configurable validation for limited access keys
+- Contract-specific access control when using function call keys
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Wallet not connected"**
+   - You must call `requestSignIn.near()` before `signIn.near()`
+   - Check that the embedded fastintear client is properly initialized
+
+2. **"No valid nonce found"**
+   - Ensure `requestSignIn.near()` completed successfully before calling `signIn.near()`
+   - Client nonces expire after 5 minutes
+
+3. **"Invalid or expired nonce"**
+   - Server nonces expire after 15 minutes
+   - Ensure client and server clocks are synchronized
+
+4. **"Account ID mismatch"**
+   - Verify the signed message contains the correct account ID
+   - Check for wallet switching between the two authentication steps
+
+5. **"Network ID mismatch"**
+   - Ensure the networkId sent to the server matches the account's network
+   - Testnet accounts must use "testnet", mainnet accounts use "mainnet"
+
+
 ## Links
 
 * [Better Auth Documentation](https://better-auth.com)
@@ -311,3 +453,4 @@ export const auth = betterAuth({
 * [NEP-413 Specification](https://github.com/near/NEPs/blob/master/neps/nep-0413.md)
 * [near-sign-verify](https://github.com/elliotBraem/near-sign-verify)
 * [fastintear](https://github.com/elliotBraem/fastintear)
+* [Example Implementation](https://better-near-auth.near.page)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-near-auth",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Sign in with NEAR (SIWN) plugin for Better Auth",
   "main": "index.ts",
   "module": "index.ts",
@@ -45,7 +45,8 @@
   "dependencies": {
     "@better-auth/utils": "^0.2.6",
     "@fastnear/utils": "^0.9.7",
-    "fastintear": "^0.2.3",
+    "fastintear": "^0.2.4",
+    "nanostores": "^1.0.1",
     "near-sign-verify": "^0.4.3",
     "zod": "^4.0.17"
   },

package/src/client.ts

@@ -1,14 +1,10 @@
 import { base64ToBytes } from "@fastnear/utils";
-import type { BetterAuthClientPlugin, BetterFetchOption, BetterFetchResponse } from "better-auth/client";
-import { sign, type WalletInterface } from "near-sign-verify";
+import type { BetterAuthClientPlugin, BetterFetch, BetterFetchOption, BetterFetchResponse } from "better-auth/client";
+import { createNearClient } from "fastintear";
+import { atom } from "nanostores";
+import { sign } from "near-sign-verify";
 import type { siwn } from ".";
 import { type AccountId, type NonceRequestT, type NonceResponseT, type ProfileResponseT, type VerifyRequestT, type VerifyResponseT } from "./types";
-import type { User } from "better-auth";
-
-export interface Signer {
-	accountId(): string | null;
-	signMessage: WalletInterface["signMessage"];
-}
 
 export interface AuthCallbacks {
 	onSuccess?: () => void;
@@ -16,7 +12,17 @@ export interface AuthCallbacks {
 }
 
 export interface SIWNClientConfig {
-	domain: string;
+	domain: string; // TODO: this could potentially be shade agent proxy or something, doesn't really have any purpose rn
+	networkId?: "mainnet" | "testnet";
+	// TODO: should include browser vs keypair
+}
+
+export interface CachedNonceData {
+	nonce: string;
+	accountId: string;
+	publicKey: string;
+	networkId: string;
+	timestamp: number;
 }
 
 export interface SIWNClientActions {
@@ -24,19 +30,44 @@ export interface SIWNClientActions {
 		nonce: (params: NonceRequestT) => Promise<BetterFetchResponse<NonceResponseT>>;
 		verify: (params: VerifyRequestT) => Promise<BetterFetchResponse<VerifyResponseT>>;
 		getProfile: (accountId?: AccountId) => Promise<BetterFetchResponse<ProfileResponseT>>;
+		getNearClient: () => ReturnType<typeof createNearClient>;
+		getAccountId: () => string | null;
+		disconnect: () => Promise<void>;
+	};
+	requestSignIn: {
+		near: (params: { recipient: string }, callbacks?: AuthCallbacks) => Promise<void>;
 	};
 	signIn: {
-		near: (params: { recipient: string, signer: Signer }, callbacks?: AuthCallbacks) => Promise<void>;
+		near: (params: { recipient: string }, callbacks?: AuthCallbacks) => Promise<void>;
 	};
 }
 
 export interface SIWNClientPlugin extends BetterAuthClientPlugin {
 	id: "siwn";
 	$InferServerPlugin: ReturnType<typeof siwn>;
-	getActions: ($fetch: any) => SIWNClientActions;
+	getActions: ($fetch: BetterFetch) => SIWNClientActions;
 }
 
 export const siwnClient = (config: SIWNClientConfig): SIWNClientPlugin => {
+	// Create embedded NEAR client
+	const nearClient = createNearClient({
+		networkId: config.networkId || "mainnet"
+	});
+
+	// Create atoms for caching nonce only
+	const cachedNonce = atom<CachedNonceData | null>(null);
+
+	const clearNonce = () => {
+		cachedNonce.set(null);
+	};
+
+	const isNonceValid = (nonceData: CachedNonceData | null): boolean => {
+		if (!nonceData) return false;
+		const now = Date.now();
+		const fiveMinutes = 5 * 60 * 1000;
+		return (now - nonceData.timestamp) < fiveMinutes;
+	};
+
 	return {
 		id: "siwn",
 		$InferServerPlugin: {} as ReturnType<typeof siwn>,
@@ -63,45 +94,134 @@ export const siwnClient = (config: SIWNClientConfig): SIWNClientPlugin => {
 							body: { accountId },
 							...fetchOptions
 						});
-
+					},
+					getNearClient: () => nearClient,
+					getAccountId: () => nearClient.accountId(),
+					disconnect: async () => {
+						await nearClient.signOut();
+						clearNonce();
 					},
 				},
+				requestSignIn: {
+					near: async (
+						params: { recipient: string },
+						callbacks?: AuthCallbacks
+					): Promise<void> => {
+						try {
+							const { recipient } = params;
+
+							if (!nearClient) {
+								const error = new Error("NEAR client not available") as Error & { code?: string };
+								error.code = "SIGNER_NOT_AVAILABLE";
+								throw error;
+							}
+
+							clearNonce();
+
+							await nearClient.requestSignIn({ contractId: recipient }, {
+								onSuccess: async ({ accountId, publicKey, networkId }: { accountId: string, publicKey: string, networkId: string }) => {
+									try {
+										const nonceRequest: NonceRequestT = {
+											accountId,
+											publicKey,
+											networkId: networkId as "mainnet" | "testnet"
+										};
+
+										const nonceResponse: BetterFetchResponse<NonceResponseT> = await $fetch("/near/nonce", {
+											method: "POST",
+											body: nonceRequest
+										});
+
+										if (nonceResponse.error) {
+											throw new Error(nonceResponse.error.message || "Failed to get nonce");
+										}
+
+										const nonce = nonceResponse?.data?.nonce;
+										if (!nonce) {
+											throw new Error("No nonce received from server");
+										}
+
+										// Cache nonce with all wallet data
+										const cachedData: CachedNonceData = {
+											nonce,
+											accountId,
+											publicKey,
+											networkId,
+											timestamp: Date.now()
+										};
+										cachedNonce.set(cachedData);
+
+										callbacks?.onSuccess?.();
+									} catch (error) {
+										const err = error instanceof Error ? error : new Error(String(error));
+										clearNonce();
+										callbacks?.onError?.(err);
+									}
+								},
+								onError: (error: any) => {
+									const err = error instanceof Error ? error : new Error(String(error));
+									clearNonce();
+									callbacks?.onError?.(err);
+								}
+							});
+						} catch (error) {
+							const err = error instanceof Error ? error : new Error(String(error));
+							clearNonce();
+							callbacks?.onError?.(err);
+						}
+					}
+				},
 				signIn: {
 					near: async (
-						params: { recipient: string, signer: Signer },
+						params: { recipient: string },
 						callbacks?: AuthCallbacks
 					): Promise<void> => {
 						try {
-							const { signer, recipient } = params;
+							const { recipient } = params;
 
-							if (!signer) {
-								throw new Error("NEAR signer not available");
+							if (!nearClient) {
+								const error = new Error("NEAR client not available") as Error & { code?: string };
+								error.code = "SIGNER_NOT_AVAILABLE";
+								throw error;
 							}
 
-							const accountId = signer.accountId();
+							const accountId = nearClient.accountId();
 							if (!accountId) {
-								throw new Error("Wallet not connected. Please connect your wallet first.");
+								const error = new Error("Wallet not connected. Please connect your wallet first.") as Error & { code?: string };
+								error.code = "WALLET_NOT_CONNECTED";
+								throw error;
 							}
 
-							const nonceResponse: BetterFetchResponse<NonceResponseT> = await $fetch("/near/nonce", {
-								method: "POST",
-								body: { accountId }
-							});
+							// Retrieve nonce from cache
+							const nonceData = cachedNonce.get();
+
+							if (!isNonceValid(nonceData)) {
+								const error = new Error("No valid nonce found. Please call requestSignIn first.") as Error & { code?: string };
+								error.code = "NONCE_NOT_FOUND";
+								throw error;
+							}
 
-							if (nonceResponse.error) {
-								throw new Error(nonceResponse.error.message || "Failed to get nonce");
+							// Validate that the cached nonce matches the current account
+							if (nonceData!.accountId !== accountId) {
+								const error = new Error("Account ID mismatch. Please call requestSignIn again.") as Error & { code?: string };
+								error.code = "ACCOUNT_MISMATCH";
+								throw error;
 							}
 
-							const nonce = nonceResponse?.data?.nonce;
+							const { nonce } = nonceData!;
+
+							// Create the sign-in message
 							const message = `Sign in to ${recipient}\n\nAccount ID: ${accountId}\nNonce: ${nonce}`;
-							const nonceBytes = base64ToBytes(nonce!);
+							const nonceBytes = base64ToBytes(nonce);
 
+							// Sign the message
 							const authToken = await sign(message, {
-								signer,
+								signer: nearClient,
 								recipient,
 								nonce: nonceBytes,
 							});
 
+							// Verify the signature with the server
 							const verifyResponse: BetterFetchResponse<VerifyResponseT> = await $fetch("/near/verify", {
 								method: "POST",
 								body: {
@@ -118,9 +238,13 @@ export const siwnClient = (config: SIWNClientConfig): SIWNClientPlugin => {
 								throw new Error("Authentication verification failed");
 							}
 
+							// Clear the nonce after successful authentication
+							clearNonce();
 							callbacks?.onSuccess?.();
 						} catch (error) {
 							const err = error instanceof Error ? error : new Error(String(error));
+							// Clear nonce on error to prevent reuse
+							clearNonce();
 							callbacks?.onError?.(err);
 						}
 					}

package/src/index.ts

@@ -2,7 +2,7 @@ import { bytesToBase64 } from "@fastnear/utils";
 import { APIError, createAuthEndpoint, sessionMiddleware } from "better-auth/api";
 import { setSessionCookie } from "better-auth/cookies";
 import type { BetterAuthPlugin, User } from "better-auth/types";
-import { generateNonce, verify, type VerificationResult, type VerifyOptions } from "near-sign-verify";
+import { generateNonce, parseAuthToken, verify, type VerificationResult, type VerifyOptions } from "near-sign-verify";
 import { defaultGetProfile, getImageUrl, getNetworkFromAccountId } from "./profile";
 import { schema } from "./schema";
 import type {
@@ -73,15 +73,23 @@ export const siwn = (options: SIWNPluginOptions) =>
 					body: NonceRequest,
 				},
 				async (ctx) => {
-					const { accountId } = ctx.body;
+					const { accountId, publicKey, networkId } = ctx.body;
 					const network = getNetworkFromAccountId(accountId);
+					
+					if (networkId !== network) {
+						throw new APIError("BAD_REQUEST", {
+							message: "Network ID mismatch with account ID",
+							status: 400,
+						});
+					}
+
 					const nonce = options.getNonce ? await options.getNonce() : generateNonce();
 
 					// Store nonce as base64 string for database compatibility
 					const nonceString = bytesToBase64(nonce);
 
 					await ctx.context.internalAdapter.createVerificationValue({
-						identifier: `siwn:${accountId}:${network}`,
+						identifier: `siwn:${accountId}:${network}:${publicKey}`,
 						value: nonceString!,
 						expiresAt: new Date(Date.now() + 15 * 60 * 1000),
 					});
@@ -158,9 +166,11 @@ export const siwn = (options: SIWNPluginOptions) =>
 					}
 
 					try {
+						const { publicKey } = parseAuthToken(authToken);
+
 						const verification =
 							await ctx.context.internalAdapter.findVerificationValue(
-								`siwn:${accountId}:${network}`,
+								`siwn:${accountId}:${network}:${publicKey}`,
 							);
 
 						if (!verification || new Date() > verification.expiresAt) {

package/src/types.ts

@@ -34,7 +34,11 @@ export type SocialImage = z.infer<typeof socialImageSchema>;
 export type Profile = z.infer<typeof profileSchema>;
 
 
-export const NonceRequest = z.object({ accountId: accountIdSchema });
+export const NonceRequest = z.object({
+	accountId: accountIdSchema,
+	publicKey: z.string(),
+	networkId: z.union([z.literal("mainnet"), z.literal("testnet")])
+});
 export const VerifyRequest = z.object({
 	authToken: z.string().min(1),
 	accountId: accountIdSchema,