Auth Patterns

Auth Patterns

Quick Pattern

// Login form
export const login = form(schema, async ({ email, password }) => {
	const event = getRequestEvent();
	await auth.api.signInEmail({
		body: { email, password },
		headers: event.request.headers,
	});
	redirect(303, '/dashboard'); // Outside try/catch
});

// Protected query
export const get_data = guarded_query(() => {
	return { message: 'Protected data' };
});

Core Principles

• Use getRequestEvent() for headers (cookie access)
• Redirect MUST be outside try/catch (throws error)
• Use guarded_query/form/command for protected endpoints
• Email verification required before login
• Commands cannot redirect - use client-side goto()

Reference Files

• auth-setup.md - Complete better-auth

configuration

• auth-usage.md - All auth patterns and

examples

• email-verification.md - Email

verification flow

Auth Patterns

Better-auth integration for authentication. Use when implementing login, registration, protected routes, or email verification.

Structure

• SKILL.md - Main skill instructions
• references/ - Detailed documentation loaded as needed
• scripts/ - Executable code for deterministic operations
• assets/ - Templates, images, or other resources

Usage

This skill is automatically discovered by Claude when relevant to the task.

Authentication Setup with Better Auth

Setting up Better Auth with Remote Functions - no hooks.server.ts needed.

Installation

pnpm add better-auth better-sqlite3 resend
pnpm rebuild better-sqlite3

Configure Better Auth

Create auth instance with database, cookies, and email verification:

// lib/server/auth.ts
import { getRequestEvent } from '$app/server';
import { env } from '$env/dynamic/private';
import { betterAuth } from 'better-auth';
import { sveltekitCookies } from 'better-auth/svelte-kit';
import Database from 'better-sqlite3';
import { resend } from './resend';

// Create database instance for Better Auth
const auth_db = new Database('local.db');

// Enable WAL mode for better concurrency
auth_db.pragma('journal_mode = WAL');
auth_db.pragma('busy_timeout = 5000');
auth_db.pragma('synchronous = NORMAL');

export const auth = betterAuth({
	database: auth_db,
	emailAndPassword: {
		enabled: true,
		requireEmailVerification: true,
		autoSignInAfterVerification: true,
		sendVerificationEmail: async ({ user, url }) => {
			await resend.emails.send({
				from: 'Your App <notifications@yourdomain.com>',
				to: user.email,
				subject: 'Verify your email address',
				html: `
					<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
						<h2>Welcome!</h2>
						<p>Hi ${user.name},</p>
						<p>Please verify your email address to get started.</p>
						<p>
							<a href="${url}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 4px; display: inline-block;">
								Verify Email Address
							</a>
						</p>
						<p>Or copy this link: ${url}</p>
					</div>
				`,
			});
		},
	},
	emailVerification: {
		sendOnSignUp: true,
		autoSignInAfterVerification: true,
	},
	socialProviders: {
		github: {
			clientId: env.GITHUB_CLIENT_ID as string,
			clientSecret: env.GITHUB_CLIENT_SECRET as string,
		},
	},
	secret: env.AUTH_SECRET || 'dev-secret-change-in-production',
	baseURL: env.AUTH_BASE_URL || 'http://localhost:5173',
	plugins: [sveltekitCookies(getRequestEvent)],
});

Create Resend helper:

// lib/server/resend.ts
import { env } from '$env/dynamic/private';
import { Resend } from 'resend';

export const resend = new Resend(env.RESEND_API_KEY);

Generate Database Schema

Better Auth manages its own tables:

# Generate schema
npx @better-auth/cli@latest generate

# Apply migrations
npx @better-auth/cli@latest migrate

Better Auth creates: user, session, account, verification tables.

Enable Remote Functions

Add to svelte.config.js:

kit: {
  adapter: adapter(),
  experimental: {
    remoteFunctions: true
  }
}

Environment Variables

Development

AUTH_SECRET=your-random-secret-here
AUTH_BASE_URL=http://localhost:5173
RESEND_API_KEY=your-resend-api-key

# GitHub OAuth (Dev)
GITHUB_CLIENT_ID=your_dev_github_client_id
GITHUB_CLIENT_SECRET=your_dev_github_client_secret

Production

AUTH_SECRET=your-production-secret
AUTH_BASE_URL=https://yourdomain.com
ORIGIN=https://yourdomain.com  # Critical for CSRF protection
RESEND_API_KEY=your-production-resend-api-key

# GitHub OAuth (Prod)
GITHUB_CLIENT_ID=your_prod_github_client_id
GITHUB_CLIENT_SECRET=your_prod_github_client_secret

Critical:

• The ORIGIN environment variable MUST be set in production to avoid

CSRF 403 errors

• Get your Resend API key from https://resend.com
• Configure your domain in Resend for sending emails
• You need separate GitHub OAuth apps for dev and production

(different callback URLs)

GitHub OAuth Configuration

Create GitHub OAuth Apps

You need two separate GitHub OAuth applications - one for development and one for production.

Development App:

1. Go to GitHub Settings → Developer settings → OAuth Apps → New OAuth App 2. Fill in the details:

• Application name: Your App (Dev)
• Homepage URL: http://localhost:5173
• Authorization callback URL:

http://localhost:5173/api/auth/callback/github 3. Click "Register application" 4. Copy the Client ID and generate a new Client Secret 5. Add to your .env file:

   GITHUB_CLIENT_ID=your_dev_client_id
   GITHUB_CLIENT_SECRET=your_dev_client_secret

Production App:

1. Create another OAuth App 2. Fill in the details:

• Application name: Your App
• Homepage URL: https://yourdomain.com
• Authorization callback URL:

https://yourdomain.com/api/auth/callback/github 3. Use different credentials in production environment

What Data GitHub Provides

When users authenticate with GitHub, you'll receive:

• id - GitHub user ID
• login - GitHub username (used for @username profiles)
• name - Display name
• email - Primary email address
• avatar_url - Profile photo URL
• bio - Profile bio
• location - User's location
• blog - Website URL
• company - Company name
• twitter_username - X/Twitter handle

This data can be used to auto-populate user profiles and sync GitHub information.

Profile Creation on GitHub OAuth

When a user signs in with GitHub for the first time:

1. Better Auth creates a user record with GitHub data 2. Your app should create a user_profiles record:

• Set username = GitHub login
• Set github_username = GitHub login
• Sync bio, location, website from GitHub
• Generate default QR code

3. Optionally create user_social_links entries for GitHub, Twitter, etc.

See database-pattern.md for examples of profile creation queries.

Authentication Helper Functions

Create reusable auth helpers:

// lib/server/auth-helpers.ts
import { query, form, command, getRequestEvent } from '$app/server';
import { redirect } from '@sveltejs/kit';
import { auth } from './auth';

/**
 * Get current user ID or redirect to login
 */
export async function get_current_user_id(): Promise<string> {
	const event = getRequestEvent();

	const session = await auth.api.getSession({
		headers: event.request.headers,
	});

	if (!session?.user) {
		redirect(302, '/login');
	}

	return session.user.id;
}

/**
 * Wrap a query function with authentication
 */
export const guarded_query = <T>(fn: () => T | Promise<T>) => {
	return query(async () => {
		const event = getRequestEvent();

		const session = await auth.api.getSession({
			headers: event.request.headers,
		});

		if (!session) {
			redirect(302, '/login');
		}

		return fn();
	});
};

/**
 * Wrap a form function with authentication
 */
export const guarded_form = <Schema, Result>(
	schema: Schema,
	handler: (data: any) => Result | Promise<Result>,
) => {
	return form(schema, async (data) => {
		const event = getRequestEvent();

		const session = await auth.api.getSession({
			headers: event.request.headers,
		});

		if (!session) {
			redirect(302, '/login');
		}

		return handler(data);
	});
};

/**
 * Wrap a command function with authentication
 */
export const guarded_command = <Schema, Result>(
	schema: Schema,
	handler: (data: any) => Result | Promise<Result>,
) => {
	return command(schema, async (data) => {
		const event = getRequestEvent();

		const session = await auth.api.getSession({
			headers: event.request.headers,
		});

		if (!session) {
			redirect(302, '/login');
		}

		return handler(data);
	});
};

Key Concepts

1. Direct database instance - Pass Better Auth a direct Database instance 2. sveltekitCookies plugin - Handles cookie management automatically 3. getRequestEvent - Access request context in remote functions 4. No hooks needed - Authentication is handled in remote functions 5. Use Better Auth CLI - Let Better Auth manage its schema

Security Considerations

• Always set AUTH_SECRET to a strong random value in production
• Set ORIGIN environment variable in production
• Use HTTPS in production (AUTH_BASE_URL)
• Enable secure cookies in production (automatic with HTTPS)
• Keep better-auth package updated for security patches

Common Issues

CSRF 403 Errors

Problem: Forms fail with 403 in production

Solution: Set ORIGIN environment variable to match your domain

Cookie Not Set

Problem: Login succeeds but user not authenticated

Solution: Ensure sveltekitCookies(getRequestEvent) plugin is configured

Database Locked

Problem: Database locked errors during concurrent requests

Solution: Better Auth uses its own database instance - this is normal. SQLite locks are temporary.

Authentication Usage Patterns

Practical patterns for implementing authentication in your app.

See auth-setup.md for installation and configuration.

Registration and Login

Registration and Login Forms

The sveltekitCookies plugin handles cookies automatically - no manual cookie transfer needed.

// routes/(auth)/auth.remote.ts
import { form, command, query, getRequestEvent } from '$app/server';
import { redirect } from '@sveltejs/kit';
import * as v from 'valibot';
import { auth } from '$lib/server/auth';

export const register = form(
	v.object({
		name: v.pipe(v.string(), v.minLength(1, 'Name is required')),
		email: v.pipe(v.string(), v.email('Invalid email address')),
		password: v.pipe(
			v.string(),
			v.minLength(8, 'Password must be at least 8 characters'),
		),
	}),
	async ({ name, email, password }) => {
		const event = getRequestEvent();

		try {
			await auth.api.signUpEmail({
				body: { name, email, password },
				headers: event.request.headers,
			});
		} catch (error: any) {
			console.error('Registration error:', error);
			return {
				error: error.message || 'Registration failed',
			};
		}

		// Redirect MUST be outside try/catch because it throws an error
		redirect(303, '/register/success');
	},
);

export const login = form(
	v.object({
		email: v.pipe(v.string(), v.email('Invalid email address')),
		password: v.pipe(
			v.string(),
			v.minLength(1, 'Password is required'),
		),
	}),
	async ({ email, password }) => {
		const event = getRequestEvent();

		try {
			// sveltekitCookies plugin handles cookies automatically
			await auth.api.signInEmail({
				body: { email, password },
				headers: event.request.headers,
			});
		} catch (error: any) {
			// Check if error is due to unverified email
			if (
				error.message?.includes('verify') ||
				error.message?.includes('verification')
			) {
				return {
					error:
						'Please verify your email address before logging in.',
					unverified: true,
					email,
				};
			}
			return {
				error: error.message || 'Invalid email or password',
			};
		}

		redirect(303, '/dashboard');
	},
);

Logout

export const logout = command(async () => {
	const event = getRequestEvent();

	await auth.api.signOut({
		headers: event.request.headers,
	});

	// Commands cannot redirect - return success and use goto() on client
	return { success: true };
});

Get Current User

export const get_current_user = query(async () => {
	const event = getRequestEvent();

	const session = await auth.api.getSession({
		headers: event.request.headers,
	});

	return session?.user ?? null;
});

Protected Routes

Use helper functions to protect queries:

// dashboard/dashboard.remote.ts
import { guarded_query } from '$lib/server/auth-helpers';

export const get_dashboard_data = guarded_query(() => {
	// Only authenticated users can access this
	return {
		message: 'Welcome to your protected dashboard!',
		timestamp: Date.now(),
	};
});

Protected Forms

import { guarded_form } from '$lib/server/auth-helpers';
import * as v from 'valibot';

export const create_item = guarded_form(
	v.object({
		title: v.string(),
		description: v.string(),
	}),
	async ({ title, description }) => {
		// User is authenticated here
		const user_id = await get_current_user_id();

		// Create item for user
		db.prepare(
			`
      INSERT INTO items (id, user_id, title, description)
      VALUES (?, ?, ?, ?)
    `,
		).run(crypto.randomUUID(), user_id, title, description);
	},
);

Protected Commands

import { guarded_command } from '$lib/server/auth-helpers';
import * as v from 'valibot';

export const update_settings = guarded_command(
	v.object({
		theme: v.string(),
		notifications: v.boolean(),
	}),
	async ({ theme, notifications }) => {
		const user_id = await get_current_user_id();

		db.prepare(
			`
      UPDATE user_settings
      SET theme = ?, notifications = ?
      WHERE user_id = ?
    `,
		).run(theme, notifications ? 1 : 0, user_id);
	},
);

Component Usage

Login Page

<!-- routes/(auth)/login/+page.svelte -->
<script lang="ts">
	import { login } from '../auth.remote';
</script>

<form {...login}>
	<fieldset class="fieldset">
		<legend class="fieldset-legend">Email</legend>
		<label class="input w-full">
			<input type="email" name="email" class="grow" required />
		</label>
	</fieldset>

	<fieldset class="fieldset">
		<legend class="fieldset-legend">Password</legend>
		<label class="input w-full">
			<input type="password" name="password" class="grow" required />
		</label>
	</fieldset>

	{#if login.error}
		<div class="alert alert-error">
			<span>{login.error}</span>
		</div>
	{/if}

	<button class="btn btn-block btn-primary" type="submit"
		>Login</button
	>
</form>

Protected Dashboard

<!-- routes/(app)/dashboard/+page.svelte -->
<script lang="ts">
	import { get_current_user, logout } from '../../(auth)/auth.remote';
	import { get_dashboard_data } from './dashboard.remote';
	import { goto } from '$app/navigation';

	async function handle_logout() {
		await logout();
		goto('/login');
	}
</script>

<svelte:boundary>
	<div>
		<button class="btn" onclick={handle_logout}>Logout</button>

		{#await get_current_user() then user}
			{#if user}
				<p>Welcome, {user.name}!</p>
			{/if}
		{/await}

		{#await get_dashboard_data() then data}
			<p>{data.message}</p>
		{/await}
	</div>

	{#snippet pending()}
		<div class="loading">Loading...</div>
	{/snippet}

	{#snippet failed(error, reset)}
		<div class="error">
			<p>Error: {error.message}</p>
			<button onclick={reset}>Retry</button>
		</div>
	{/snippet}
</svelte:boundary>

Show User Info

<script lang="ts">
	import { get_current_user } from './auth.remote';
</script>

{#await get_current_user() then user}
	{#if user}
		<div class="dropdown">
			<label tabindex="0" class="btn btn-ghost">
				{user.name}
			</label>
			<ul class="dropdown-content menu">
				<li><a href="/profile">Profile</a></li>
				<li><button onclick={handle_logout}>Logout</button></li>
			</ul>
		</div>
	{:else}
		<a href="/login" class="btn">Login</a>
	{/if}
{/await}

Layout-Based Protection

Protect entire route groups with layout guards:

// routes/(app)/layout.remote.ts
import { guarded_query } from '$lib/server/auth-helpers';

export const verify_auth = guarded_query(() => {
	// Just check authentication - redirect if not logged in
	return { authenticated: true };
});

<!-- routes/(app)/+layout.svelte -->
<script lang="ts">
	import { verify_auth } from './layout.remote';
</script>

<svelte:boundary>
	{#await verify_auth()}
		<div class="loading">Loading...</div>
	{:then}
		<slot />
	{/await}

	{#snippet failed()}
		<!-- User will be redirected to login -->
	{/snippet}
</svelte:boundary>

Email Verification

Resend Verification Email

// auth.remote.ts
export const resend_verification_email = command(
	v.pipe(v.string(), v.email('Invalid email address')),
	async (email: string) => {
		const event = getRequestEvent();

		try {
			await auth.api.sendVerificationEmail({
				body: { email, callbackURL: '/dashboard' },
				headers: event.request.headers,
			});

			return {
				success: true,
				message: 'Verification email sent! Please check your inbox.',
			};
		} catch (error: any) {
			return {
				error: error.message || 'Failed to send verification email',
			};
		}
	},
);

Handle Unverified Users in Login

Show a resend button when users try to login without verifying:

<!-- routes/(auth)/login/+page.svelte -->
<script lang="ts">
	import { login, resend_verification_email } from '../auth.remote';
</script>

<form {...login}>
	<!-- email and password fields -->

	{#if login.error}
		<div class="alert alert-error">
			<span>{login.error}</span>
		</div>

		{#if login.unverified}
			<button
				class="btn btn-sm"
				onclick={(e) => {
					e.preventDefault();
					resend_verification_email(login.email);
				}}
			>
				Resend Verification Email
			</button>
		{/if}
	{/if}

	<button class="btn btn-primary" type="submit">Login</button>
</form>

Registration Success Page

Redirect to a success page after registration:

<!-- routes/(auth)/register/success/+page.svelte -->
<div class="card">
	<h1>Check Your Email</h1>
	<p>We've sent a verification link to your email address.</p>
	<p>Please click the link to verify your account and get started.</p>
	<a href="/login" class="btn btn-primary">Go to Login</a>
</div>

Key Points

1. Remote Functions - SvelteKit's recommended approach for server-side logic 2. Automatic Cookies - sveltekitCookies plugin handles session cookies automatically 3. Redirect outside try/catch - SvelteKit's redirect() throws an error 4. Commands cannot redirect - Use goto() client-side for logout 5. Use guarded helpers - Simplifies protected route implementation 6. Layout guards - Protect entire route groups efficiently 7. Email verification - Users must verify email before accessing the app

Email Verification

Users must verify their email address before accessing the application.

Configuration

In src/lib/server/auth.ts:

export const auth = betterAuth({
	emailVerification: {
		sendOnSignUp: true,
		autoSignInAfterVerification: true,
		sendVerificationEmail: async ({ user, url }) => {
			await resend.emails.send({
				from: 'Your App <updates@yourdomain.com>',
				to: user.email,
				subject: 'Verify your email address',
				html: `
          <div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
            <h2>Welcome to Your App!</h2>
            <p>Hi ${user.name},</p>
            <p>Thanks for signing up. Please verify your email address to get started.</p>
            <p>
              <a href="${url}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 4px; display: inline-block;">
                Verify Email Address
              </a>
            </p>
            <p>Or copy and paste this link into your browser:</p>
            <p style="color: #666; font-size: 14px;">${url}</p>
            <p>This link will expire in 24 hours.</p>
          </div>
        `,
			});
		},
	},
});

Resending Verification Email

// auth.remote.ts
export const resend_verification_email = command(
	v.pipe(v.string(), v.email('Invalid email address')),
	async (email: string) => {
		const event = getRequestEvent();

		try {
			await auth.api.sendVerificationEmail({
				body: { email, callbackURL: '/dashboard' },
				headers: event.request.headers,
			});

			return {
				success: true,
				message: 'Verification email sent! Please check your inbox.',
			};
		} catch (error: any) {
			return {
				error: error.message || 'Failed to send verification email',
			};
		}
	},
);

Handling Unverified Users

Show a resend button when users try to login without verifying:

<!-- routes/(auth)/login/+page.svelte -->
<script lang="ts">
	import { login, resend_verification_email } from '../auth.remote';
</script>

<form {...login}>
	<fieldset class="fieldset">
		<legend class="fieldset-legend">Email</legend>
		<label class="input w-full">
			<input type="email" name="email" class="grow" required />
		</label>
	</fieldset>

	<fieldset class="fieldset">
		<legend class="fieldset-legend">Password</legend>
		<label class="input w-full">
			<input type="password" name="password" class="grow" required />
		</label>
	</fieldset>

	{#if login.error}
		<div class="alert alert-error">
			<span>{login.error}</span>
		</div>

		{#if login.unverified}
			<button
				class="btn btn-sm"
				onclick={(e) => {
					e.preventDefault();
					resend_verification_email(login.email);
				}}
			>
				Resend Verification Email
			</button>
		{/if}
	{/if}

	<button class="btn btn-block btn-primary" type="submit"
		>Login</button
	>
</form>

Login Error Handling

Check for verification errors:

export const login = form(
	v.object({
		email: v.pipe(v.string(), v.email()),
		password: v.pipe(v.string(), v.minLength(1)),
	}),
	async ({ email, password }) => {
		const event = getRequestEvent();

		try {
			await auth.api.signInEmail({
				body: { email, password },
				headers: event.request.headers,
			});
		} catch (error: any) {
			// Check if error is due to unverified email
			if (
				error.message?.includes('verify') ||
				error.message?.includes('verification')
			) {
				return {
					error:
						'Please verify your email address before logging in.',
					unverified: true,
					email,
				};
			}
			return {
				error: error.message || 'Invalid email or password',
			};
		}

		redirect(303, '/dashboard');
	},
);

Registration Success Page

Redirect to a success page after registration:

<!-- routes/(auth)/register/success/+page.svelte -->
<div class="card">
	<h1>Check Your Email</h1>
	<p>We've sent a verification link to your email address.</p>
	<p>Please click the link to verify your account and get started.</p>
	<a href="/login" class="btn btn-primary">Go to Login</a>
</div>

Best Practices

1. Always require verification - Set requireEmailVerification: true 2. Auto sign-in after verification - Set autoSignInAfterVerification: true 3. Provide resend option - Allow users to resend verification emails 4. Clear error messages - Tell users they need to verify 5. Email templates - Use branded, professional HTML templates 6. Expiry time - Set appropriate link expiration (24 hours recommended)