mcpField
B
better-auth

better-auth

github.com/dobroslavradosavljevicSecurity338 installsUpdated 1d ago
Repository

About better-auth

A guidance skill for developers building self-hosted TypeScript authentication with Better Auth. It covers setup, plugins, database adapters, framework integration, security, and version upgrades.

Key features

  1. 01Server and client setup guidance
  2. 02Plugin and database adapter guidance
  3. 03Framework mounts and session checks
  4. 04Upgrade and security checks

Use cases

  1. 01Configure Better Auth sign-in and sessions
  2. 02Add plugins and generate database schemas
  3. 03Upgrade auth dependencies and review risks

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dobroslavradosavljevic/skills --skill better-auth

After installing, type/better-authin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
adapters-schema.md
frameworks-client.md
plugins-ecosystem.md
security-patterns.md
source-map.md
usage-guide.md

Details

From the project README

Better Auth

Use this skill for self-hosted TypeScript authentication with Better Auth ([email protected]): server instance, client SDK, plugins, adapters, framework mounts, and security.

Snapshot: 2026-10-01. latest is 1.7.7 (stable). Do not treat 1.7 as rc/beta. Require ≥ 1.7.7: earlier versions (back to 1.4.0-beta.18) have a critical Magic Link account takeover (GHSA-965c-763c-88jm) and an OAuth Proxy takeover (GHSA-r4xp-prcw-77qf); no 1.6.x fix exists. Refresh from source-map.md if versions differ.

Workflow

  1. Inspect the local surface:
    • Core: better-auth (snapshot 1.7.7). CLI: bunx auth@latest (package [email protected]) — not stale @better-auth/[email protected]. CLI needs Node.js ≥ 22.12.
    • Env: BETTER_AUTH_SECRET (≥32), BETTER_AUTH_URL / baseURL, trustedOrigins.
    • Database: Kysely/pool vs Drizzle/Prisma/Mongo adapter; secondary storage (Redis). Schema validation is on by default.
    • Plugins: server + matching client plugins; schema generated after changes.
    • Mount: /api/auth/* (default basePath) via auth.handler / framework helper.
  2. For day-to-day setup, follow usage-guide.md first. From 1.6, start with bunx auth@latest upgrade and the 1.7 upgrade guide — generated SQL is not the full upgrade.
  3. Refresh docs when versions drift. Start from source-map.md.
  4. Route deeper detail:
  5. Align every installed @better-auth/* at 1.7.x with core (except separate lines: utils, infra, agent-auth, dash). Prefer scoped adapters when optimizing (better-auth/minimal).
  6. Verify with session smoke (auth.api.getSession), sign-in/out, plugin schema migrate, and production secret/origins checks.

Core Judgment

  • Cookie DB sessions by default — not JWT. Use jwt / bearer / API keys only when cookies aren’t enough.
  • Singleton auth in lib/auth.ts (named export helps CLI discovery). Separate auth-client.ts.
  • Server: auth.api.* with real request headers. Client: createAuthClient + framework entry (better-auth/react, …).
  • Most features are plugins: register server + client, then bunx auth@latest generate (ORM) or migrate (Kysely).
  • Passkey / API key / SSO / SCIM / OAuth-provider / MCP / CIMD / Stripe / Expo are scoped packages. MCP is @better-auth/mcp, not better-auth/plugins.
  • oidcProvider is removed. Use @better-auth/oauth-provider. Do not also register oauthProvider() next to mcp() — mcp() is the provider.
  • Generic OAuth uses signIn.social / linkSocial and /api/auth/callback/:id. There is no genericOAuthClient().
  • Never treat middleware cookie presence as auth — validate session. Don’t disable CSRF/origin checks to “fix” CORS.
  • Upgrading to 1.7.7 is a coordinated cutover: upgrade every server sharing verification storage and every OAuth Proxy participant together; pending Magic Links and OAuth/SAML state from before the upgrade stop working.
  • Rate limit is off/weak in dev; memory storage fails on multi-instance — use Redis/DB in prod.
  • Prefer bun / bunx in command examples.

Verification

Prefer repository-owned commands. Cover the relevant subset:

  • bun pm ls better-auth and matching @better-auth/* versions (all 1.7.x together, ≥ 1.7.7).
  • bunx auth@latest info / secret as needed; schema generate/migrate after plugin changes; read-only bunx auth@latest check schema to validate the adapter schema.
  • Smoke: mount handler, getSession, email or social sign-in, sign-out.
  • Plugins: client methods resolve; org/2FA/passkey/OAuth-provider/MCP flows if enabled.
  • Prod: baseURL, secret length, trustedOrigins, HTTPS cookies, rate-limit storage, schema validation not failing.
  • Security: roles/additionalFields with input: false; no testUtils in prod config.
  • After 1.6→1.7: Microsoft oid rows, OAuth clients, SCIM reprovision, Expo await getCookie(), and 1.7.0–1.7.2 issuer cleanup if that schema was applied.

Report which checks ran, which did not, and version assumptions that remain.

Comments

Markdown supported