ton-better-auth

library0.2.3jsnpmunverified

Better Auth plugin for TON Connect — sign in with TON wallets using ton_proof. Version 0.2.3. Provides server-side verification of TON Connect ton_proof payloads (nonce challenge, signature verification, wallet state-init parsing for v1–v5, on-chain get_public_key fallback) and a client plugin with typed helpers. Release cadence: active development. Key differentiators: integrates directly with Better Auth's session and user management, supports wildcard domain policies, per-network domain rules, anti-abuse cooldowns, and events. Requires @better-auth/core >=1.3.0, better-auth >=1.3.0, and optional react >=18 for client. Ships TypeScript types. Node >=20.

security

npm install ton-better-auth

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TON-BETTER-AUTH

ton-better-auth

securityjavascriptv0.2.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tonConnect

✓ import { tonConnect } from 'ton-better-auth'

✗ const tonConnect = require('ton-better-auth')

ESM-only (package type: module). Server plugin factory.

tonConnectClient

✓ import { tonConnectClient } from 'ton-better-auth/client'

✗ import { tonConnectClient } from 'ton-better-auth'

Client plugin is exported from /client subpath. CommonJS require will fail.

TONConnectOptions

✓ import type { TONConnectOptions } from 'ton-better-auth'

✗ import { TONConnectOptions } from 'ton-better-auth'

Options type is exported as type only. TypeScript users should use 'import type'.

Server plugin configuration with domain policies, anti-abuse settings, and client plugin initialization.

// Server setup (src/auth.ts) import { betterAuth } from 'better-auth'; import { tonConnect } from 'ton-better-auth'; export const auth = betterAuth({ database: /* your adapter */, plugins: [ tonConnect({ allowedDomains: { default: ['example.com', '*.example.com'], mainnet: ['app.example.com'], testnet: ['localhost:5173'] }, validAuthTimeSec: 15 * 60, challengeTtlSec: 10 * 60, emailDomain: 'ton.local', antiAbuse: { verify: { maxPerIp: 20, maxPerAddress: 8, windowSec: 60 }, failedVerifyCooldown: { enabled: true, threshold: 5, windowSec: 600, cooldownSec: 600, keying: 'ip+address' } } }) ] }); // Client setup (src/auth-client.ts) import { createAuthClient } from 'better-auth/client'; import { tonConnectClient } from 'ton-better-auth/client'; export const authClient = createAuthClient({ plugins: [tonConnectClient()] });

Debug

Known issues

breakingPackage requires Node >=20. Older versions will fail at runtime.

fix

Upgrade Node to version 20 or later.

affects: <20

breakingESM-only package. CommonJS require() throws ERR_REQUIRE_ESM.

fix

Use dynamic import() or convert project to ESM (type: module in package.json).

affects: >=0.1.0

deprecatedallowedDomainsByNetwork is an alternative to per-network keys in allowedDomains; both can coexist but may cause confusion.

fix

Use the per-network object in allowedDomains (e.g., allowedDomains: { '-3': [...] }) and avoid allowedDomainsByNetwork.

affects: >=0.2.0

gotchaThe plugin creates a 'tonWallet' database table automatically. Custom schemas must include it for migrations to work.

fix

Run 'npx @better-auth/cli@latest generate' to generate migration files, then apply them.

affects: >=0.1.0

gotchaNonces are one-shot and replay-protected. If a challenge request is interrupted, the nonce is consumed and a new challenge must be requested.

fix

Retry the challenge endpoint on failure; do not reuse a previous nonce.

affects: >=0.1.0

gotchaThe client plugin tonConnectClient() must be imported from 'ton-better-auth/client', not from the main package.

fix

Use correct import path: import { tonConnectClient } from 'ton-better-auth/client'.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'ton-better-auth/client'

Using an import path that is not exposed in the package exports map, typically due to import from wrong path or old Node version.

fix

Ensure import path is 'ton-better-auth/client' and Node >=20. For older Node, you may need to enable exports resolution.

ERR_REQUIRE_ESM

Using require() on an ESM-only package.

fix

Use import instead of require, or use dynamic import() in CommonJS.

TypeError: tonConnect is not a function

Default import used instead of named import, or the import is from wrong path.

fix

Use named import: import { tonConnect } from 'ton-better-auth'

Missing table: tonWallet

Database schema does not include the required 'tonWallet' table for storing wallet links.

fix

Run 'npx @better-auth/cli@latest migrate' to create the table, or generate migration files.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

@better-auth/corerequiredPeer dependency: core types and utilities for Better Auth plugin

better-authrequiredPeer dependency: runtime Better Auth server and client

reactoptionalOptional peer for the React client plugin

Agent activity

30 hits · last 30 days

node

Resources

githubhttps://github.com/mhbdev/ton-better-auth ↗

packageton-better-auth ↗

homepagehttps://github.com/mhbdev/ton-better-auth#readme ↗