Authentication - Minimal

Minimal uses Better Auth for authentication, providing email/password login, OAuth providers, and email verification out of the box.

Authentication Overview

Minimal’s authentication system includes:

Email/Password: Built-in email and password authentication
OAuth: Google sign-in (optional)
Email Verification: Email verification on signup
Password Reset: Secure password reset flow
Session Management: 7-day sessions with automatic renewal
Account Linking: Link multiple OAuth providers to one account
Chrome Extension: CORS support for browser extension

Better Auth Configuration

Authentication is configured in lib/auth.ts using Better Auth with Prisma adapter.

Core Setup

import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import { nextCookies } from "better-auth/next-js";
import { db } from "./db";

export const auth = betterAuth({
  baseURL: process.env.NEXT_PUBLIC_APP_URL,
  secret: process.env.BETTER_AUTH_SECRET,
  database: prismaAdapter(db, { provider: "sqlite" }),
  plugins: [nextCookies()],
});

Required Environment Variables

BETTER_AUTH_SECRET="your-secret-key"
NEXT_PUBLIC_APP_URL="https://your-domain.com"

Email and Password Authentication

Email/password authentication is enabled by default:

emailAndPassword: {
  enabled: true,
  sendResetPassword: async ({ user, url }) => {
    await sendEmail({
      to: user.email,
      ...resetPasswordEmail(user.name, url),
    });
  },
}

Features

Secure password hashing
Password reset via email
Email verification
Account creation with automatic group setup

User registers

User provides name, email, and password

Account created

User account is created with emailVerified: false

Verification email sent

Email with verification link is sent to user

Default group created

A default “Bookmarks” group is created for the user

User verifies email

User clicks verification link and is automatically signed in

Password Requirements

Better Auth enforces secure password requirements by default. Customize these in your auth configuration if needed.

Email Verification

Email verification is configured to:

Send verification email on signup
Auto sign-in after verification
Use custom email templates

emailVerification: {
  sendOnSignUp: true,
  autoSignInAfterVerification: true,
  sendVerificationEmail: async ({ user, url }) => {
    await sendEmail({
      to: user.email,
      ...verificationEmail(user.name, url),
    });
  },
}

Email Service Setup

Minimal uses Autosend for transactional emails:

Get Autosend API Key

Sign up at autosend.com
Create an API key from the dashboard

Configure Environment

.env

AUTOSEND_API_KEY="as_live_abc123..."

Test Email Sending

Without AUTOSEND_API_KEY, email verification and password reset will not work. Users can still sign up, but won’t receive emails.

Email Templates

Minimal includes three email templates:

Welcome Email: Sent on first signup
Verification Email: Email verification link
Reset Password Email: Password reset link

Templates are located in lib/emails/ and use a consistent design from lib/email.ts.

OAuth Configuration

Google OAuth Setup

Create Google OAuth App

Go to Google Cloud Console
Create a new project or select existing
Navigate to “APIs & Services” > “Credentials”
Click “Create Credentials” > “OAuth client ID”
Select “Web application”

Configure OAuth Consent Screen

Navigate to “OAuth consent screen”
Select “External” (or “Internal” for workspace)
Fill in required fields:
- App name: “Minimal”
- User support email
- Developer contact email
Add scopes:
- userinfo.email
- userinfo.profile

Set Authorized Redirect URIs

Add your callback URL:

https://your-domain.com/api/auth/callback/google

For development:

http://localhost:3000/api/auth/callback/google

Get Credentials

Copy:

Client ID
Client Secret

Configure Environment Variables

.env

GOOGLE_CLIENT_ID="123456789-abc.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="GOCSPX-abc123def456ghi789"

OAuth Configuration in Code

Google OAuth is conditionally enabled:

const { GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET } = process.env;
const googleOAuthEnabled = Boolean(GOOGLE_CLIENT_ID && GOOGLE_CLIENT_SECRET);

...(googleOAuthEnabled && {
  socialProviders: {
    google: {
      clientId: GOOGLE_CLIENT_ID!,
      clientSecret: GOOGLE_CLIENT_SECRET!,
    },
  },
})

If credentials are not provided, Google sign-in is automatically disabled.

Account Linking

Minimal supports linking multiple OAuth providers to one account:

account: {
  accountLinking: {
    enabled: true,
    trustedProviders: ["google"],
  },
}

This allows users to:

Sign in with email/password, then link Google
Sign in with Google, then add password
Link multiple OAuth providers (if additional providers are added)

Session Management

Sessions are configured with:

session: {
  expiresIn: 60 * 60 * 24 * 7,  // 7 days
  updateAge: 60 * 60 * 24,       // Refresh daily
}

Session Duration: 7 days
Update Frequency: Session extended every 24 hours of activity
Storage: Database-backed sessions (session table)
Security: Tracks IP address and user agent

Session Data

Each session stores:

Session token (unique, indexed)
User ID
Expiration timestamp
IP address (optional)
User agent (optional)
Created/updated timestamps

Chrome Extension Support

Minimal supports authentication from a Chrome extension:

trustedOrigins: CHROME_EXTENSION_ID
  ? [`chrome-extension://${CHROME_EXTENSION_ID}`]
  : []

Configuration

Get Extension ID

After building your Chrome extension, note the extension ID from chrome://extensions

Configure Environment

.env

CHROME_EXTENSION_ID="abcdefghijklmnopqrstuvwxyz123456"
NEXT_PUBLIC_CHROME_EXTENSION_ID="abcdefghijklmnopqrstuvwxyz123456"

Rebuild Application

bun run build

This adds the extension origin to CORS allowed origins for API requests.

Authentication Hooks

Minimal uses Better Auth hooks to perform actions after authentication:

hooks: {
  after: createAuthMiddleware(async (ctx) => {
    const session = ctx.context.newSession;
    if (!session) return;

    // Create default group for new users
    await ensureDefaultGroup(session.user.id);

    // Track signup/login events
    const isNewUser = 
      Date.now() - new Date(session.user.createdAt).getTime() < 60_000;
    
    if (isNewUser) {
      // Send welcome email
      await sendEmail({
        to: session.user.email,
        ...welcomeEmail(session.user.name),
      });
    }
  }),
}

Default Group Creation

Every user gets a default “Bookmarks” group:

async function ensureDefaultGroup(userId: string): Promise<void> {
  const existingGroups = await db.group.count({ where: { userId } });
  if (existingGroups > 0) return;

  await db.group.create({
    data: { name: "Bookmarks", color: "#74B06F", userId },
  });
}

Security Best Practices

Follow these security practices for production deployments:

Secret Management

Strong Secret: Generate with openssl rand -base64 32
Never Commit: Add .env to .gitignore
Rotate Regularly: Update BETTER_AUTH_SECRET periodically
Environment Separation: Use different secrets for dev/prod

HTTPS Requirements

Better Auth requires HTTPS in production for secure cookie transmission.

Use HTTPS for NEXT_PUBLIC_APP_URL
Configure SSL/TLS certificates (Let’s Encrypt recommended)
Set secure cookie flags automatically in production

OAuth Security

Verify Redirect URIs: Only add your actual domain
Restrict Scopes: Only request necessary OAuth scopes
Secure Secrets: Keep GOOGLE_CLIENT_SECRET private
Review Permissions: Regularly review OAuth app permissions

Troubleshooting

”BETTER_AUTH_SECRET is required”

Set the secret in .env:

BETTER_AUTH_SECRET="$(openssl rand -base64 32)"

OAuth Redirect Mismatch

Check NEXT_PUBLIC_APP_URL matches OAuth redirect URI exactly
Ensure protocol (http/https) is correct
Verify no trailing slashes in URLs
Add both development and production URIs to OAuth app

Email Not Sending

Verify AUTOSEND_API_KEY is set and valid
Check Autosend dashboard for delivery logs
Review application logs for email errors
Test with a known working email address

Session Expired Immediately

Check server and client clocks are synchronized
Verify database is correctly storing sessions
Check NEXT_PUBLIC_APP_URL matches your actual domain
Review browser cookie settings (allow cookies)

Chrome Extension CORS Issues

Verify CHROME_EXTENSION_ID matches actual extension ID
Ensure extension is loaded (check chrome://extensions)
Rebuild application after adding extension ID
Check browser console for specific CORS errors

User Management

Admin Access

Set admin email for admin privileges:

.env

ADMIN_EMAIL="admin@example.com"

User Roles

Currently, Minimal uses a simple admin check. To extend:

Add role field to user model
Update auth hooks to check roles
Implement role-based access control in API routes

Next Steps

Configuration - Complete environment variables guide
Database Setup - Database configuration
Installation - Full installation guide

​Authentication Overview

​Better Auth Configuration

​Core Setup

​Required Environment Variables

​Email and Password Authentication

​Features

​User Signup Flow

​Password Requirements

​Email Verification

​Email Service Setup

​Email Templates

​OAuth Configuration

​Google OAuth Setup

​OAuth Configuration in Code

​Account Linking

​Session Management

​Session Data

​Chrome Extension Support

​Configuration

​Authentication Hooks

​Default Group Creation

​Security Best Practices

​Secret Management

​HTTPS Requirements

​OAuth Security

​Troubleshooting

​”BETTER_AUTH_SECRET is required”

​OAuth Redirect Mismatch

​Email Not Sending

​Session Expired Immediately

​Chrome Extension CORS Issues

​User Management

​Admin Access

​User Roles

​Next Steps

Authentication Overview

Better Auth Configuration

Core Setup

Required Environment Variables

Email and Password Authentication

Features

User Signup Flow

Password Requirements

Email Verification

Email Service Setup

Email Templates

OAuth Configuration

Google OAuth Setup

OAuth Configuration in Code

Account Linking

Session Management

Session Data

Chrome Extension Support

Configuration

Authentication Hooks

Default Group Creation

Security Best Practices

Secret Management

HTTPS Requirements

OAuth Security

Troubleshooting

”BETTER_AUTH_SECRET is required”

OAuth Redirect Mismatch

Email Not Sending

Session Expired Immediately

Chrome Extension CORS Issues

User Management

Admin Access

User Roles

Next Steps