better-near-auth 0.1.0

package/README.md

@@ -0,0 +1,311 @@
+<!-- markdownlint-disable MD014 -->
+<!-- markdownlint-disable MD033 -->
+<!-- markdownlint-disable MD041 -->
+<!-- markdownlint-disable MD029 -->
+
+<div align="center">
+
+<h1 style="font-size: 2.5rem; font-weight: bold;">better-near-auth</h1>
+
+  <p>
+    <strong>Sign in with NEAR (SIWN) plugin for better-auth</strong>
+  </p>
+
+</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) and [fastintear](https://github.com/elliotBraem/fastintear), and provides a complete drop-in solution with secure defaults and automatic profile integration.
+
+## Installation
+
+1. Install the package
+
+```bash
+npm install better-near-auth
+```
+
+2. Add the SIWN plugin to your auth configuration:
+
+    ```ts title="auth.ts"
+    import { betterAuth } from "better-auth";
+    import { siwn } from "better-near-auth";
+
+    export const auth = betterAuth({
+        plugins: [
+            siwn({
+                recipient: "myapp.com",
+                anonymous: true, // optional, default is true
+            }),
+        ],
+    });
+    ```
+
+3. Migrate the database. Run the migration or generate the schema to add the necessary fields and tables to the database.
+
+  ```bash
+  npx @better-auth/cli generate
+  ```
+
+4. Add the Client Plugin
+
+    ```ts title="auth-client.ts"
+    import { createAuthClient } from "better-auth/client";
+    import { siwnClient } from "better-near-auth/client";
+
+    export const authClient = createAuthClient({
+        plugins: [siwnClient()],
+    });
+    ```
+
+
+## Usage
+
+### One-Line Authentication
+
+The simplest way to authenticate with NEAR:
+
+```ts title="sign-in-near.ts"
+const response = 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);
+    }
+  }
+);
+
+console.log("Signed in as:", response.user.accountId);
+```
+
+### Profile Access
+
+Access user profiles from NEAR Social automatically:
+
+```ts title="profile-usage.ts"
+// Get current user's profile (requires authentication)
+const { data: myProfile } = await authClient.near.getProfile();
+console.log("My profile:", myProfile);
+
+// Get specific user's profile (no auth required)
+const { data: aliceProfile } = await authClient.near.getProfile("alice.near");
+console.log("Alice's profile:", aliceProfile);
+```
+
+## Configuration Options
+
+### Server Options
+
+The SIWN plugin accepts the following configuration options:
+
+* **recipient**: The recipient identifier for NEP-413 messages (required)
+* **anonymous**: Whether to allow anonymous sign-ins without requiring an email. Default is `true`
+* **emailDomainName**: The email domain name for creating user accounts when not using anonymous mode. Defaults to the recipient value
+* **requireFullAccessKey**: Whether to require full access keys. Default is `true`
+* **getNonce**: Function to generate a unique nonce for each sign-in attempt. Optional, uses secure defaults
+* **validateNonce**: Function to validate nonces. Optional, uses time-based validation by default
+* **validateRecipient**: Function to validate recipients. Optional, uses exact match by default
+* **validateMessage**: Function to validate messages. Optional, no validation by default
+* **getProfile**: Function to fetch user profiles. Optional, uses NEAR Social by default
+* **validateFunctionCallKey**: Function to validate function call access keys when `requireFullAccessKey` is false
+
+### Client Options
+
+The SIWN client plugin doesn't require any configuration options:
+
+```ts title="auth-client.ts"
+import { createAuthClient } from "better-auth/client";
+import { siwnClient } from "better-near-auth/client";
+
+export const authClient = createAuthClient({
+  plugins: [
+    siwnClient({
+      // Optional client configuration can go here
+    }),
+  ],
+});
+```
+
+## Schema
+
+The SIWN plugin adds a `nearAccount` table to store user NEAR account associations:
+
+| Field     | Type    | Description                               |
+| --------- | ------- | ----------------------------------------- |
+| id        | string  | Primary key                               |
+| userId    | string  | Reference to user.id                      |
+| accountId | string  | NEAR account ID                           |
+| network   | string  | Network (mainnet or testnet)              |
+| publicKey | string  | Associated public key                     |
+| isPrimary | boolean | Whether this is the user's primary account|
+| createdAt | date    | Creation timestamp                        |
+
+## Complete Implementation Example
+
+Here's a complete example showing how to implement SIWN authentication:
+
+```ts title="auth.ts"
+import { betterAuth } from "better-auth";
+import { siwn } from "better-near-auth";
+
+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
+        return null; // Use default NEAR Social lookup
+      },
+    }),
+  ],
+});
+```
+
+```ts title="auth-client.ts"
+import { createAuthClient } from "better-auth/client";
+import { siwnClient } from "better-near-auth/client";
+
+export const authClient = createAuthClient({
+  baseURL: "http://localhost:3000",
+  plugins: [siwnClient()],
+});
+```
+
+```tsx title="LoginButton.tsx"
+import { authClient } from "./auth-client";
+import { useState } from "react";
+
+export function LoginButton() {
+  const { data: session } = authClient.useSession();
+  const [isSigningIn, setIsSigningIn] = useState(false);
+
+  if (session) {
+    return (
+      <div>
+        <p>Welcome, {session.user.name}!</p>
+        <button onClick={() => authClient.signOut()}>Sign out</button>
+      </div>
+    );
+  }
+
+  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);
+    }
+  };
+
+  return (
+    <button onClick={handleSignIn} disabled={isSigningIn}>
+      {isSigningIn ? "Signing in..." : "Sign in with NEAR"}
+    </button>
+  );
+}
+```
+
+## Advanced Configuration
+
+For advanced use cases, you can customize the validation functions passed to `verify` in `near-sign-verify`:
+
+```ts title="advanced-auth.ts"
+import { betterAuth } from "better-auth";
+import { siwn } from "better-near-auth";
+import { generateNonce } from "near-sign-verify";
+
+const usedNonces = new Set<string>();
+
+export const auth = betterAuth({
+  plugins: [
+    siwn({
+      recipient: "myapp.com",
+      anonymous: false, // Require email for users
+      emailDomainName: "myapp.com",
+      requireFullAccessKey: false, // Allow function call keys
+      
+      // Custom nonce generation
+      getNonce: async () => {
+        return generateNonce();
+      },
+      
+      // Custom nonce validation (prevents replay attacks)
+      validateNonce: (nonce: Uint8Array) => {
+        const nonceHex = Array.from(nonce).map(b => b.toString(16).padStart(2, '0')).join('');
+        if (usedNonces.has(nonceHex)) {
+          return false; // Prevent replay attacks
+        }
+        usedNonces.add(nonceHex);
+        return true;
+      },
+      
+      // Custom recipient validation (allow multiple domains)
+      validateRecipient: (recipient: string) => {
+        const allowedRecipients = ["myapp.com", "staging.myapp.com", "localhost:3000"];
+        return allowedRecipients.includes(recipient);
+      },
+      
+      // Custom message validation
+      validateMessage: (message: string) => {
+        // Add custom message format validation
+        return message.includes("Sign in to") && message.length > 10;
+      },
+      
+      // Custom profile lookup
+      getProfile: async (accountId) => {
+        // Custom profile logic, falls back to NEAR Social
+        try {
+          const response = await fetch(`https://api.myapp.com/profiles/${accountId}`);
+          if (response.ok) {
+            const customProfile = await response.json();
+            return {
+              name: customProfile.displayName,
+              description: customProfile.bio,
+              image: { url: customProfile.avatar },
+            };
+          }
+        } catch (error) {
+          console.error("Custom profile fetch failed:", error);
+        }
+        return null; // Use default NEAR Social lookup
+      },
+      
+      // Validate function call keys against allowed contracts
+      validateFunctionCallKey: async ({ accountId, publicKey, contractId }) => {
+        const allowedContracts = ["myapp.near", "social.near"];
+        return contractId ? allowedContracts.includes(contractId) : true;
+      },
+    }),
+  ],
+});
+```
+
+## Links
+
+* [Better Auth Documentation](https://better-auth.com)
+* [NEAR Protocol](https://near.org)
+* [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)

package/index.ts

@@ -0,0 +1,22 @@
+export { siwn } from "./src/index";
+export { siwnClient } from "./src/client";
+export type {
+	AccountId,
+	NearAccount,
+	SocialImage,
+	Profile,
+	NonceRequestT,
+	NonceResponseT,
+	VerifyRequestT,
+	VerifyResponseT,
+	ProfileRequestT,
+	ProfileResponseT,
+} from "./src/types";
+export { accountIdSchema } from "./src/types";
+export type { SIWNPluginOptions } from "./src/index";
+export type {
+	AuthCallbacks,
+	SIWNClientConfig,
+	SIWNClientActions,
+	SIWNClientPlugin,
+} from "./src/client";

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "better-near-auth",
+  "version": "0.1.0",
+  "description": "Sign in with NEAR (SIWN) plugin for Better Auth",
+  "main": "index.ts",
+  "module": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.ts",
+      "types": "./index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "lint": "tsc --noEmit",
+    "dev": "bun run index.ts"
+  },
+  "keywords": [
+    "better-auth",
+    "near",
+    "siwn",
+    "sign-in-with-near",
+    "authentication",
+    "blockchain",
+    "web3",
+    "plugin"
+  ],
+  "author": "efiz.near",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elliotBraem/better-near-auth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/elliotBraem/better-near-auth/issues"
+  },
+  "homepage": "https://github.com/elliotBraem/better-near-auth#readme",
+  "peerDependencies": {
+    "better-auth": "^1.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@better-auth/utils": "^0.2.6",
+    "@fastnear/utils": "^0.9.7",
+    "fastintear": "link:fastintear",
+    "near-sign-verify": "^0.4.3",
+    "zod": "^4.0.17"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^24.3.0",
+    "better-auth": "^1.3.6",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "src/",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,128 @@
+import { base64ToBytes } from "@fastnear/utils";
+import type { BetterAuthClientPlugin, BetterFetchOption, BetterFetchResponse } from "better-auth/client";
+import { sign, type WalletInterface } from "near-sign-verify";
+import type { siwn } from ".";
+import { type AccountId, type NonceRequestT, type NonceResponseT, type ProfileResponseT, type VerifyRequestT, type VerifyResponseT } from "./types";
+
+export interface Signer {
+	accountId(): string | null;
+	signMessage: WalletInterface["signMessage"];
+}
+
+export interface AuthCallbacks {
+	onSuccess?: () => void;
+	onError?: (error: Error & { status?: number; code?: string }) => void;
+}
+
+export interface SIWNClientConfig {
+	domain: string;
+}
+
+export interface SIWNClientActions {
+	near: {
+		nonce: (params: NonceRequestT) => Promise<BetterFetchResponse<NonceResponseT>>;
+		verify: (params: VerifyRequestT) => Promise<BetterFetchResponse<VerifyResponseT>>;
+		getProfile: (accountId?: AccountId) => Promise<BetterFetchResponse<ProfileResponseT>>;
+	};
+	signIn: {
+		near: (params: { recipient: string, signer: Signer }, callbacks?: AuthCallbacks) => Promise<VerifyResponseT>;
+	};
+}
+
+export interface SIWNClientPlugin extends BetterAuthClientPlugin {
+	id: "siwn";
+	$InferServerPlugin: ReturnType<typeof siwn>;
+	getActions: ($fetch: any) => SIWNClientActions;
+}
+
+export const siwnClient = (config: SIWNClientConfig): SIWNClientPlugin => {
+	return {
+		id: "siwn",
+		$InferServerPlugin: {} as ReturnType<typeof siwn>,
+		getActions: ($fetch): SIWNClientActions => {
+			return {
+				near: {
+					nonce: async (params: NonceRequestT, fetchOptions?: BetterFetchOption): Promise<BetterFetchResponse<NonceResponseT>> => {
+						return await $fetch("/near/nonce", {
+							method: "POST",
+							body: params,
+							...fetchOptions
+						});
+					},
+					verify: async (params: VerifyRequestT, fetchOptions?: BetterFetchOption): Promise<BetterFetchResponse<VerifyResponseT>> => {
+						return await $fetch("/near/verify", {
+							method: "POST",
+							body: params,
+							...fetchOptions
+						});
+					},
+					getProfile: async (accountId?: AccountId, fetchOptions?: BetterFetchOption): Promise<BetterFetchResponse<ProfileResponseT>> => {
+						return await $fetch("/near/profile", {
+							method: "POST",
+							body: { accountId },
+							...fetchOptions
+						});
+
+					},
+				},
+				signIn: {
+					near: async (params: { recipient: string, signer: Signer }, callbacks?: AuthCallbacks): Promise<VerifyResponseT> => {
+						try {
+							const { signer, recipient } = params;
+
+							if (!signer) {
+								throw new Error("NEAR signer not available");
+							}
+
+							// Must be already connected
+							const accountId = signer.accountId();
+							if (!accountId) {
+								throw new Error("Wallet not connected. Please connect your wallet first.");
+							}
+
+							// Get nonce for signature
+							const nonceResponse: BetterFetchResponse<NonceResponseT> = await $fetch("/near/nonce", {
+								method: "POST",
+								body: { accountId }
+							});
+
+							const nonce = nonceResponse?.data?.nonce;
+							const message = `Sign in to ${recipient}\n\nAccount ID: ${accountId}\nNonce: ${nonce}`;
+
+							// Convert base64 nonce to Uint8Array for signing
+							const nonceBytes = base64ToBytes(nonce!);
+
+							// Sign message
+							const authToken = await sign(message, {
+								signer,
+								recipient,
+								nonce: nonceBytes,
+							});
+
+							// Verify signature with backend
+							const verifyResponse: BetterFetchResponse<VerifyResponseT> = await $fetch("/near/verify", {
+								method: "POST",
+								body: {
+									authToken,
+									accountId,
+								}
+							});
+
+							if (!verifyResponse?.data?.success) {
+								throw new Error("Authentication verification failed");
+							}
+
+							callbacks?.onSuccess?.();
+							return verifyResponse.data;
+
+						} catch (error) {
+							const err = error instanceof Error ? error : new Error(String(error));
+							callbacks?.onError?.(err);
+							throw err;
+						}
+					}
+				}
+			};
+		}
+	} satisfies BetterAuthClientPlugin;
+};

package/src/index.ts

@@ -0,0 +1,351 @@
+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 { defaultGetProfile, getImageUrl, getNetworkFromAccountId } from "./profile";
+import { schema } from "./schema";
+import type {
+	AccountId,
+	NearAccount,
+	Profile
+} from "./types";
+import {
+	NonceRequest,
+	NonceResponse,
+	ProfileRequest,
+	ProfileResponse,
+	VerifyRequest,
+	VerifyResponse
+} from "./types";
+
+function getOrigin(baseURL: string): string {
+	try {
+		return new URL(baseURL).origin;
+	} catch {
+		return baseURL;
+	}
+}
+
+export type SIWNPluginOptions =
+	| {
+		recipient: string;
+		anonymous?: true;
+		emailDomainName?: string;
+		requireFullAccessKey?: boolean;
+		getNonce?: () => Promise<Uint8Array>;
+		validateNonce?: (nonce: Uint8Array) => boolean;
+		validateRecipient?: (recipient: string) => boolean;
+		validateMessage?: (message: string) => boolean;
+		getProfile?: (accountId: AccountId) => Promise<Profile | null>;
+		validateFunctionCallKey?: (args: {
+			accountId: AccountId;
+			publicKey: string;
+			contractId?: string;
+		}) => Promise<boolean>;
+	}
+	| {
+		recipient: string;
+		anonymous: false;
+		emailDomainName?: string;
+		requireFullAccessKey?: boolean;
+		getNonce?: () => Promise<Uint8Array>;
+		validateNonce?: (nonce: Uint8Array) => boolean;
+		validateRecipient?: (recipient: string) => boolean;
+		validateMessage?: (message: string) => boolean;
+		getProfile?: (accountId: AccountId) => Promise<Profile | null>;
+		validateFunctionCallKey?: (args: {
+			accountId: AccountId;
+			publicKey: string;
+			contractId?: string;
+		}) => Promise<boolean>;
+	};
+
+export const siwn = (options: SIWNPluginOptions) =>
+	({
+		id: "siwn",
+		schema,
+		endpoints: {
+			getSiwnNonce: createAuthEndpoint(
+				"/near/nonce",
+				{
+					method: "POST",
+					body: NonceRequest,
+				},
+				async (ctx) => {
+					const { accountId } = ctx.body;
+					const network = getNetworkFromAccountId(accountId);
+					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}`,
+						value: nonceString!,
+						expiresAt: new Date(Date.now() + 15 * 60 * 1000),
+					});
+
+					return ctx.json(NonceResponse.parse({ nonce: nonceString }));
+				},
+			),
+			getSiwnProfile: createAuthEndpoint(
+				"/near/profile",
+				{
+					method: "POST",
+					body: ProfileRequest,
+					use: [sessionMiddleware],
+				},
+				async (ctx) => {
+					const { accountId } = ctx.body;
+					let targetAccountId = accountId;
+
+					if (!targetAccountId) {
+						const session = ctx.context.session;
+						if (!session) {
+							throw new APIError("UNAUTHORIZED", {
+								message: "Session required when no accountId provided",
+								status: 401,
+							});
+						}
+
+						const nearAccount: NearAccount | null = await ctx.context.adapter.findOne({
+							model: "nearAccount",
+							where: [
+								{ field: "userId", operator: "eq", value: session.user.id },
+								{ field: "isPrimary", operator: "eq", value: true },
+							],
+						});
+
+						if (!nearAccount) {
+							throw new APIError("NOT_FOUND", {
+								message: "No NEAR account found for user",
+								status: 404,
+							});
+						}
+
+						targetAccountId = nearAccount.accountId;
+					}
+
+					const profile = await (options.getProfile || defaultGetProfile)(targetAccountId);
+					return ctx.json(ProfileResponse.parse(profile));
+				},
+			),
+			verifySiwnMessage: createAuthEndpoint(
+				"/near/verify",
+				{
+					method: "POST",
+					body: VerifyRequest.refine((data) => options.anonymous !== false || !!data.email, {
+						message: "Email is required when the anonymous plugin option is disabled.",
+						path: ["email"],
+					}),
+					requireRequest: true,
+				},
+				async (ctx) => {
+					const {
+						authToken,
+						accountId,
+						email,
+					} = ctx.body;
+					const network = getNetworkFromAccountId(accountId);
+					const isAnon = options.anonymous ?? true;
+
+					if (!isAnon && !email) {
+						throw new APIError("BAD_REQUEST", {
+							message: "Email is required when anonymous is disabled.",
+							status: 400,
+						});
+					}
+
+					try {
+						const verification =
+							await ctx.context.internalAdapter.findVerificationValue(
+								`siwn:${accountId}:${network}`,
+							);
+
+						if (!verification || new Date() > verification.expiresAt) {
+							throw new APIError("UNAUTHORIZED", {
+								message: "Unauthorized: Invalid or expired nonce",
+								status: 401,
+								code: "UNAUTHORIZED_INVALID_OR_EXPIRED_NONCE",
+							});
+						}
+
+						// Build verify options using plugin configuration
+						const requireFullAccessKey = options.requireFullAccessKey ?? true;
+						const verifyOptions: VerifyOptions = {
+							requireFullAccessKey: requireFullAccessKey,
+							...(options.validateNonce
+								? { validateNonce: options.validateNonce }
+								: { nonceMaxAge: 15 * 60 * 1000 }),
+							...(options.validateRecipient
+								? { validateRecipient: options.validateRecipient }
+								: { expectedRecipient: options.recipient }),
+							...(options.validateMessage ? { validateMessage: options.validateMessage } : {}),
+						} as VerifyOptions;
+
+						// Verify the signature using near-sign-verify
+						const result: VerificationResult = await verify(authToken, verifyOptions);
+
+						if (result.accountId !== accountId) {
+							throw new APIError("UNAUTHORIZED", {
+								message: "Unauthorized: Account ID mismatch",
+								status: 401,
+							});
+						}
+
+						if (!options.requireFullAccessKey && options.validateFunctionCallKey) {
+							const isValidFunctionKey = await options.validateFunctionCallKey({
+								accountId: result.accountId,
+								publicKey: result.publicKey,
+							}); // we can validate against an access control contract
+
+							if (!isValidFunctionKey) {
+								throw new APIError("UNAUTHORIZED", {
+									message: "Unauthorized: Invalid function call access key",
+									status: 401,
+								});
+							}
+						}
+
+						await ctx.context.internalAdapter.deleteVerificationValue(
+							verification.id,
+						);
+
+						let user: User | null = null;
+
+						const existingNearAccount: NearAccount | null =
+							await ctx.context.adapter.findOne({
+								model: "nearAccount",
+								where: [
+									{ field: "accountId", operator: "eq", value: accountId },
+									{ field: "network", operator: "eq", value: network },
+								],
+							});
+
+						if (existingNearAccount) {
+							user = await ctx.context.adapter.findOne({
+								model: "user",
+								where: [
+									{
+										field: "id",
+										operator: "eq",
+										value: existingNearAccount.userId,
+									},
+								],
+							});
+						} else {
+							const anyNearAccount: NearAccount | null =
+								await ctx.context.adapter.findOne({
+									model: "nearAccount",
+									where: [
+										{ field: "accountId", operator: "eq", value: accountId },
+									],
+								});
+
+							if (anyNearAccount) {
+								user = await ctx.context.adapter.findOne({
+									model: "user",
+									where: [
+										{
+											field: "id",
+											operator: "eq",
+											value: anyNearAccount.userId,
+										},
+									],
+								});
+							}
+						}
+
+						if (!user) {
+							const domain =
+								options.emailDomainName ?? getOrigin(ctx.context.baseURL);
+							const userEmail =
+								!isAnon && email ? email : `${accountId}@${domain}`;
+
+							const profile = await (options.getProfile || defaultGetProfile)(accountId);
+
+							user = await ctx.context.internalAdapter.createUser({
+								name: profile?.name ?? accountId,
+								email: userEmail,
+								image: profile?.image ? getImageUrl(profile.image) : "",
+							});
+
+							await ctx.context.adapter.create({
+								model: "nearAccount",
+								data: {
+									userId: user.id,
+									accountId,
+									network,
+									publicKey: result.publicKey,
+									isPrimary: true,
+									createdAt: new Date(),
+								},
+							});
+
+							await ctx.context.internalAdapter.createAccount({
+								userId: user.id,
+								providerId: "siwn",
+								accountId: `${accountId}:${network}`,
+								createdAt: new Date(),
+								updatedAt: new Date(),
+							});
+						} else {
+							if (!existingNearAccount) {
+								await ctx.context.adapter.create({
+									model: "nearAccount",
+									data: {
+										userId: user.id,
+										accountId,
+										network,
+										publicKey: result.publicKey,
+										isPrimary: false,
+										createdAt: new Date(),
+									},
+								});
+
+								await ctx.context.internalAdapter.createAccount({
+									userId: user.id,
+									providerId: "siwn",
+									accountId: `${accountId}:${network}`,
+									createdAt: new Date(),
+									updatedAt: new Date(),
+								});
+							}
+						}
+
+						const session = await ctx.context.internalAdapter.createSession(
+							user.id,
+							ctx,
+						);
+
+						if (!session) {
+							throw new APIError("INTERNAL_SERVER_ERROR", {
+								message: "Internal Server Error",
+								status: 500,
+							});
+						}
+
+						await setSessionCookie(ctx, { session, user });
+
+						return ctx.json(VerifyResponse.parse({
+							token: session.token,
+							success: true,
+							user: {
+								id: user.id,
+								accountId,
+								network,
+							},
+						}));
+					} catch (error: unknown) {
+						if (error instanceof APIError) throw error;
+						throw new APIError("UNAUTHORIZED", {
+							message: "Something went wrong. Please try again later.",
+							error: error instanceof Error ? error.message : "Unknown error",
+							status: 401,
+						});
+					}
+				},
+			),
+		},
+	}) satisfies BetterAuthPlugin;

package/src/near.test.ts

@@ -0,0 +1,331 @@
+// import { describe, expect } from "vitest";
+// import { getTestInstance } from "better-auth/test-utils/test-instance";
+// import { siwn } from "./index";
+// import { siwnClient } from "./client";
+
+// describe("siwn", async (it) => {
+// 	const accountId = "test.near";
+// 	const testnetAccountId = "test.testnet";
+// 	const domain = "example.com";
+
+// 	it("should generate a valid nonce for a valid NEAR account ID", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+// 		const { data } = await client.near.nonce({ accountId });
+// 		expect(typeof data?.nonce).toBe("string");
+// 		expect(data?.nonce).toMatch(/^[a-zA-Z0-9]{17}$/);
+// 	});
+
+// 	it("should detect mainnet network for regular account IDs", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+// 		const { data } = await client.near.nonce({ accountId: "user.near" });
+// 		expect(typeof data?.nonce).toBe("string");
+// 	});
+
+// 	it("should detect testnet network for .testnet account IDs", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+// 		const { data } = await client.near.nonce({ accountId: testnetAccountId });
+// 		expect(typeof data?.nonce).toBe("string");
+// 	});
+
+// 	it("should reject verification if nonce is missing", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+// 		const { error } = await client.near.verify({
+// 			authToken: "valid_token",
+// 			accountId,
+// 		});
+
+// 		expect(error).toBeDefined();
+// 		expect(error?.status).toBe(401);
+// 		expect(error?.code).toBe("UNAUTHORIZED_INVALID_OR_EXPIRED_NONCE");
+// 		expect(error?.message).toMatch(/nonce/i);
+// 	});
+
+// 	it("should reject invalid account ID format", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+// 		const { error } = await client.near.nonce({ accountId: "invalid-account" });
+// 		expect(error).toBeDefined();
+// 		expect(error?.status).toBe(400);
+// 		expect(error?.message).toBe("Invalid body parameters");
+// 	});
+
+// 	it("should allow function call keys when requireFullAccessKey is false", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						requireFullAccessKey: false,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 						async validateFunctionCallKey({ accountId, publicKey }) {
+// 							return accountId === "test.near" && publicKey !== "";
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+
+// 		await client.near.nonce({ accountId });
+// 		const { data, error } = await client.near.verify({
+// 			authToken: "valid_token",
+// 			accountId,
+// 		});
+// 		expect(error).toBeNull();
+// 		expect(data?.success).toBe(true);
+// 	});
+
+// 	it("should get profile for current user when no accountId provided", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 						async getProfile(accountId) {
+// 							return {
+// 								name: `Profile for ${accountId}`,
+// 								description: "Test profile",
+// 							};
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+
+// 		await client.near.nonce({ accountId });
+// 		await client.near.verify({
+// 			authToken: "valid_token",
+// 			accountId,
+// 		});
+
+// 		const { data } = await client.near.getProfile();
+// 		expect(data?.profile?.name).toBe(`Profile for ${accountId}`);
+// 	});
+
+// 	it("should get profile for specific accountId when provided", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 						async getProfile(accountId) {
+// 							return {
+// 								name: `Profile for ${accountId}`,
+// 								description: "Test profile",
+// 							};
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: {
+// 					plugins: [siwnClient()],
+// 				},
+// 			},
+// 		);
+
+// 		const targetAccount = "alice.near";
+// 		const { data } = await client.near.getProfile(targetAccount);
+// 		expect(data?.profile?.name).toBe(`Profile for ${targetAccount}`);
+// 	});
+
+// 	it("should validate various NEAR account ID formats", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: { plugins: [siwnClient()] },
+// 			},
+// 		);
+
+// 		const validAccountIds = [
+// 			"user.near",
+// 			"test.testnet",
+// 			"alice.tg",
+// 			"bob.kaito",
+// 			"sub.account.near",
+// 			"a1b2c3.near",
+// 			"user-name.near",
+// 			"user_name.near",
+// 			"deep.sub.account.near",
+// 			"app.myproject.near",
+// 		];
+
+// 		for (const accountId of validAccountIds) {
+// 			const { data, error } = await client.near.nonce({ accountId });
+// 			expect(error).toBeNull();
+// 			expect(typeof data?.nonce).toBe("string");
+// 		}
+// 	});
+
+// 	it("should reject invalid NEAR account ID formats", async () => {
+// 		const { client } = await getTestInstance(
+// 			{
+// 				plugins: [
+// 					siwn({
+// 						domain,
+// 						async getNonce() {
+// 							return "A1b2C3d4E5f6G7h8J";
+// 						},
+// 						async verifyMessage({ authToken, expectedRecipient, accountId }) {
+// 							return authToken === "valid_token" && expectedRecipient === domain;
+// 						},
+// 					}),
+// 				],
+// 			},
+// 			{
+// 				clientOptions: { plugins: [siwnClient()] },
+// 			},
+// 		);
+
+// 		const invalidAccountIds = [
+// 			"",
+// 			"a",
+// 			"A",
+// 			"user.NEAR",
+// 			"user..near",
+// 			".user.near",
+// 			"user.near.",
+// 			"user@near",
+// 			"user near",
+// 			"x".repeat(65),
+// 		];
+
+// 		for (const accountId of invalidAccountIds) {
+// 			const { error } = await client.near.nonce({ accountId });
+// 			expect(error).toBeDefined();
+// 			expect(error?.status).toBe(400);
+// 		}
+// 	});
+// });

package/src/profile.ts

@@ -0,0 +1,63 @@
+import type { AccountId, Profile, SocialImage } from "./types";
+
+const FALLBACK_URL =
+	"https://ipfs.near.social/ipfs/bafkreidn5fb2oygegqaldx7ycdmhu4owcrmoxd7ekbzfmeakkobz2ja7qy";
+
+function getNetworkFromAccountId(accountId: string): "mainnet" | "testnet" {
+	return accountId.endsWith('.testnet') ? 'testnet' : 'mainnet';
+}
+
+function getImageUrl(
+	image: SocialImage | undefined,
+	fallback?: string,
+): string {
+	if (image?.url) return image.url;
+	if (image?.ipfs_cid) return `https://ipfs.near.social/ipfs/${image.ipfs_cid}`;
+	return fallback || FALLBACK_URL;
+}
+
+interface SocialApiResponse {
+	[accountId: string]: {
+		profile?: Profile;
+	};
+}
+
+async function defaultGetProfile(accountId: AccountId): Promise<Profile | null> {
+	const network = getNetworkFromAccountId(accountId);
+	const apiBase = {
+		mainnet: "https://api.near.social",
+		testnet: "https://test.api.near.social",
+	}[network];
+
+	const keys = [`${accountId}/profile/**`];
+
+	try {
+		const response = await fetch(`${apiBase}/get`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ keys })
+		});
+
+		if (!response.ok) {
+			throw new Error(`HTTP error! status: ${response.status}`);
+		}
+
+		const data = await response.json() as SocialApiResponse;
+		const profile: Profile | undefined = data?.[accountId]?.profile;
+
+		if (profile) {
+			return {
+				name: profile.name,
+				description: profile.description,
+				image: profile.image,
+				backgroundImage: profile.backgroundImage,
+				linktree: profile.linktree
+			};
+		}
+		return null;
+	} catch (error) {
+		return null;
+	}
+}
+
+export { defaultGetProfile, getImageUrl, getNetworkFromAccountId };

package/src/schema.ts

@@ -0,0 +1,36 @@
+import type { AuthPluginSchema } from "better-auth/types";
+
+export const schema = {
+	nearAccount: {
+		fields: {
+			userId: {
+				type: "string",
+				references: {
+					model: "user",
+					field: "id",
+				},
+				required: true,
+			},
+			accountId: {
+				type: "string",
+				required: true,
+			},
+			network: {
+				type: "string",
+				required: true,
+			},
+			publicKey: {
+				type: "string",
+				required: true,
+			},
+			isPrimary: {
+				type: "boolean",
+				defaultValue: false,
+			},
+			createdAt: {
+				type: "date",
+				required: true,
+			},
+		},
+	},
+} satisfies AuthPluginSchema;

package/src/types.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+
+export const accountIdSchema = z.string()
+	.min(2)
+	.max(64)
+	.regex(/^(([a-z\d]+[-_])*[a-z\d]+\.)*([a-z\d]+[-_])*[a-z\d]+$/, "Invalid NEAR account ID format");
+
+export type AccountId = z.infer<typeof accountIdSchema>;
+
+export interface NearAccount {
+	id: string;
+	userId: string;
+	accountId: string;
+	network: "mainnet" | "testnet";
+	publicKey: string;
+	isPrimary: boolean;
+	createdAt: Date;
+}
+
+export const socialImageSchema = z.object({
+	url: z.string().optional(),
+	ipfs_cid: z.string().optional(),
+});
+
+export const profileSchema = z.object({
+	name: z.string().optional(),
+	description: z.string().optional(),
+	image: socialImageSchema.optional(),
+	backgroundImage: socialImageSchema.optional(),
+	linktree: z.record(z.string(), z.string()).optional(),
+});
+
+export type SocialImage = z.infer<typeof socialImageSchema>;
+export type Profile = z.infer<typeof profileSchema>;
+
+
+export const NonceRequest = z.object({ accountId: accountIdSchema });
+export const VerifyRequest = z.object({
+	authToken: z.string().min(1),
+	accountId: accountIdSchema,
+	email: z.email().optional(),
+});
+export const ProfileRequest = z.object({
+	accountId: accountIdSchema.optional(),
+});
+
+export const NonceResponse = z.object({ nonce: z.string() }); // Base64 string
+export const VerifyResponse = z.object({
+	token: z.string(),
+	success: z.literal(true),
+	user: z.object({
+		id: z.string(),
+		accountId: accountIdSchema,
+		network: z.union([z.literal("mainnet"), z.literal("testnet")]),
+	}),
+});
+export const ProfileResponse = profileSchema.nullable();
+
+export type NonceRequestT = z.infer<typeof NonceRequest>;
+export type NonceResponseT = z.infer<typeof NonceResponse>;
+export type VerifyRequestT = z.infer<typeof VerifyRequest>;
+export type VerifyResponseT = z.infer<typeof VerifyResponse>;
+export type ProfileRequestT = z.infer<typeof ProfileRequest>;
+export type ProfileResponseT = z.infer<typeof ProfileResponse>;