Authentication Developer Guide

This guide provides implementation code for working with authentication. For conceptual understanding, see:

• Authentication Flow - OAuth flows, JWT architecture, FusionAuth configuration

• Authorization - Role and permission model

• User Management - Identity lifecycle, account linking

Overview

1. User authenticates with FusionAuth → receives JWT
2. Application validates JWT via JWKS
3. Application resolves FusionAuth identity to internal user
4. Application stores tokens in httpOnly cookies
5. FusionAuth JWT passed directly to Neon for RLS
6. Neon uses auth_user() and is_authenticated() for access control

Setup

Environment Variables

# FusionAuth Configuration
FUSIONAUTH_URL=https://auth.refresh.tech
FUSIONAUTH_APP_ID=<application-id>
FUSIONAUTH_CLIENT_SECRET=<client-secret>
FUSIONAUTH_TENANT_ID=<fusionauth-tenant-id>

# Neon validates FusionAuth JWT directly via JWKS - no custom JWT keys needed
# PRIVATE_JWK_JSON and PUBLIC_JWK_JSON are no longer required

FusionAuth SDK Setup

// src/lib/server/fusionauth.ts
import { FusionAuthClient } from '@fusionauth/typescript-client';

export const fusionAuth = new FusionAuthClient(env.FUSIONAUTH_API_KEY, env.FUSIONAUTH_URL);

JWT Validation

Validating FusionAuth JWTs

// src/lib/server/auth/jwt.ts
import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL(`${FUSIONAUTH_URL}/.well-known/jwks.json`));

export interface DecodedJwt {
	sub: string; // FusionAuth user ID
	email: string;
	roles: string[]; // FusionAuth roles
	exp: number;
	iat: number;
}

export async function validateJwt(token: string): Promise<DecodedJwt> {
	const { payload } = await jwtVerify(token, jwks, {
		issuer: FUSIONAUTH_URL,
		audience: FUSIONAUTH_APP_ID,
		algorithms: ['RS256']
	});

	return {
		sub: payload.sub as string,
		email: payload.email as string,
		roles: (payload.roles as string[]) || [],
		exp: payload.exp as number,
		iat: payload.iat as number
	};
}

Extracting Token from Request

// src/lib/server/auth/middleware.ts
export function extractToken(request: Request): string | null {
	const authHeader = request.headers.get('Authorization');

	if (!authHeader?.startsWith('Bearer ')) {
		return null;
	}

	return authHeader.slice(7);
}

Identity Resolution

Resolving FusionAuth ID to Internal User

// src/lib/server/auth/identity.ts
import { db } from '$lib/server/db';
import { userIdentities, users } from '$lib/server/db/schema';
import { eq, and, isNull } from 'drizzle-orm';

export interface ResolvedIdentity {
	userId: string;
	identityId: string;
	email: string;
	type: 'personal' | 'work';
	tenantId: string | null;
}

export async function resolveIdentity(jwt: DecodedJwt): Promise<ResolvedIdentity> {
	// 1. Try to find by fusionauth_id (fastest path)
	let identity = await db.query.userIdentities.findFirst({
		where: eq(userIdentities.fusionAuthId, jwt.sub)
	});

	if (identity) {
		return {
			userId: identity.userId,
			identityId: identity.id,
			email: identity.email,
			type: identity.type as 'personal' | 'work',
			tenantId: identity.tenantId
		};
	}

	// 2. Try to find unclaimed identity by email (HRIS pre-created)
	// IMPORTANT: Email comparison must be case-insensitive
	const normalizedEmail = jwt.email.toLowerCase();
	identity = await db.query.userIdentities.findFirst({
		where: and(
			sql`LOWER(${userIdentities.email}) = ${normalizedEmail}`,
			isNull(userIdentities.fusionAuthId)
		)
	});

	if (identity) {
		// Link the identity to this FusionAuth user
		await db
			.update(userIdentities)
			.set({ fusionAuthId: jwt.sub, updatedDate: new Date() })
			.where(eq(userIdentities.id, identity.id));

		return {
			userId: identity.userId,
			identityId: identity.id,
			email: identity.email,
			type: identity.type as 'personal' | 'work',
			tenantId: identity.tenantId
		};
	}

	// 3. No existing identity - create personal account
	const newUser = await db
		.insert(users)
		.values({
			name: jwt.email.split('@')[0] // Default name from email
		})
		.returning();

	const newIdentity = await db
		.insert(userIdentities)
		.values({
			userId: newUser[0].id,
			fusionAuthId: jwt.sub,
			email: normalizedEmail, // Store normalized (lowercase)
			type: 'personal',
			tenantId: null,
			isPrimary: true
		})
		.returning();

	return {
		userId: newUser[0].id,
		identityId: newIdentity[0].id,
		email: jwt.email,
		type: 'personal',
		tenantId: null
	};
}

Getting Work User ID for Tenant

// src/lib/server/auth/tenant.ts
import { tenantUsers } from '$lib/server/db/schema';

export async function getWorkUserIdForTenant(
	userId: string,
	tenantId: string
): Promise<string | null> {
	// Get all linked user IDs
	const allUserIds = await getAllLinkedUserIds(userId);

	// Find active tenant membership
	const tenantUser = await db.query.tenantUsers.findFirst({
		where: and(
			inArray(tenantUsers.userId, allUserIds),
			eq(tenantUsers.tenantId, tenantId),
			eq(tenantUsers.status, 'active')
		)
	});

	return tenantUser?.userId ?? null;
}

export async function getAllLinkedUserIds(userId: string): Promise<string[]> {
	// Get the primary user
	const user = await db.query.users.findFirst({
		where: eq(users.id, userId)
	});

	const primaryId = user?.primaryUserId ?? userId;

	// Get all users linked to this primary
	const linkedUsers = await db.query.users.findMany({
		where: eq(users.primaryUserId, primaryId)
	});

	return [primaryId, ...linkedUsers.map((u) => u.id)];
}

Permission Checking

Permissions follow the principle of least privilege with granular resource:action patterns. User roles are resolved via auth_assignment → auth_role → auth_role_permission → auth_permission, then each API endpoint checks for its specific required permission.

How Permissions Are Resolved

Permissions are resolved ONCE per request in hooks.server.ts and stored in locals:

// hooks.server.ts - fusionAuthHandle
const { permissions, bypassRls } = await getUserPermissionsFromAuth(userId);
event.locals.permissions = permissions; // ResolvedPermission[]
event.locals.bypassRls = bypassRls; // boolean

Key implementation details:

1. User is identified via FusionAuth JWT sub claim → user_auth_identities

2. getUserPermissionsFromAuth() queries auth_permission_cache for the user

3. If cache is stale, it's repopulated from auth tables via triggers

4. If ANY role has bypass_rls=true, bypassRls is true

5. Permissions are NOT stored in cookies (to avoid 4KB limit)

Permission Format

// Permissions are granular: resource:action
// Standard CRUD: get, list, create, update, delete
// Custom actions: sync, export, respond, invite, etc.

// Use the UserPermission enum from auth-types.ts
import { UserPermission } from '$lib/types/auth-types';

UserPermission.SURVEYS_CREATE; // 'surveys:create'
UserPermission.USERS_DELETE; // 'users:delete'
// ... etc

Resolving Permissions

Permissions are resolved from the auth tables based on the user's role assignments:

// src/lib/server/auth/permission-guard.ts
import { authPermissionCache } from '$lib/server/db/schema';

export interface ResolvedPermission {
	permission: string; // e.g., 'compliance.control:list'
	bypassRls: boolean; // true if came from role with bypass_rls
}

export async function getUserPermissionsFromAuth(
	userId: string
): Promise<{ permissions: ResolvedPermission[]; bypassRls: boolean }> {
	// Query the permission cache for this user
	const cached = await db
		.select()
		.from(authPermissionCache)
		.where(
			and(
				eq(authPermissionCache.principalType, 'user'),
				eq(authPermissionCache.principalId, userId)
			)
		);

	const permissions: ResolvedPermission[] = cached.map((c) => ({
		permission: c.permissionName,
		bypassRls: c.bypassRls
	}));

	// bypassRls is true if ANY permission has it set
	const bypassRls = permissions.some((p) => p.bypassRls);

	return { permissions, bypassRls };
}

The auth_permission_cache table is populated by database triggers whenever auth tables change. This provides fast permission lookups without complex joins at request time.

Checking Specific Permission

// Check for a single granular permission
export async function checkPermission(
	jwt: DecodedJwt,
	tenantId: string | null,
	requiredPermission: string // e.g., 'survey:create'
): Promise<boolean> {
	const resolved = await resolvePermissions(jwt, tenantId);
	return resolved.permissions.has(requiredPermission);
}

// Check for any of multiple permissions
export async function checkAnyPermission(
	jwt: DecodedJwt,
	tenantId: string | null,
	requiredPermissions: string[] // e.g., ['survey:update', 'survey:delete']
): Promise<boolean> {
	const resolved = await resolvePermissions(jwt, tenantId);
	return requiredPermissions.some((p) => resolved.permissions.has(p));
}

Middleware Implementation

Auth Middleware

// src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import type { Handle } from '@sveltejs/kit';
import { redirect } from '@sveltejs/kit';

const fusionAuthHandle: Handle = async ({ event, resolve }) => {
	const accessToken = event.cookies.get('auth_access_token');
	const userSessionCookie = event.cookies.get('auth_user');

	if (accessToken && userSessionCookie) {
		// Parse user session from cookie
		try {
			event.locals.accessToken = accessToken;
			event.locals.user = JSON.parse(atob(userSessionCookie));
		} catch {
			// Invalid session cookie - clear and require re-auth
			event.cookies.delete('auth_user', { path: '/' });
			event.locals.user = undefined;
		}

		// Check token expiry and refresh if needed
		const isValid = await refreshTokensIfNeeded(event.cookies);
		if (!isValid) {
			event.locals.user = undefined;
			event.locals.accessToken = undefined;
		}
	}

	// Get active tenant from cookie
	event.locals.activeTenantId = event.cookies.get('active_tenant_id') ?? undefined;

	return resolve(event);
};

const permissionMiddleware: Handle = async ({ event, resolve }) => {
	if (!event.locals.accessToken) {
		return resolve(event);
	}

	// Validate JWT and extract roles
	try {
		const jwt = await validateJwt(event.locals.accessToken);

		// Resolve permissions for the request
		const permissions = await resolvePermissions(jwt, event.locals.activeTenantId ?? null);
		event.locals.permissions = permissions;
	} catch {
		// Token validation failed
		event.locals.permissions = undefined;
	}

	return resolve(event);
};

export const handle = sequence(fusionAuthHandle, permissionMiddleware);

Type Definitions

// src/app.d.ts
import type { UserSession, UserPermission } from '$lib/types/auth-types';

declare global {
	namespace App {
		interface Locals {
			accessToken?: string; // FusionAuth access token from cookie
			user?: UserSession; // Minimal user info from auth_user cookie
			activeTenantId?: string; // From active_tenant_id cookie
			roles?: string[]; // FusionAuth roles from JWT
			permissions?: UserPermission[]; // Resolved from roles (1-min cache)
			bypassRls?: boolean; // True if any permission has bypass_rls=true
		}
	}
}

UserSession Type

// src/lib/types/auth-types.ts
// Minimal session stored in auth_user cookie (stays under 4KB limit)
// Permissions are NOT in the cookie - resolved from JWT roles in hooks.server.ts
export interface UserSession {
	userId: string; // Internal user ID (resolved from FusionAuth)
	email: string;
	name?: string;
	identityType: 'personal' | 'work';
	tenantId: string | null; // Tenant from identity resolution
}

Usage in Routes

Protected API Route

Each endpoint checks for exactly one granular permission. This follows least privilege—document:list does NOT imply document:get, and document:update does NOT imply document:delete.

// src/routes/api/documents/+server.ts
import { json, error } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const GET: RequestHandler = async ({ locals, cookies }) => {
	// Require authentication (from cookie-based session)
	if (!locals.user) {
		throw error(401, 'Authentication required');
	}

	// Require tenant context
	if (!locals.activeTenantId) {
		throw error(400, 'Tenant context required');
	}

	// Check granular permission - 'document:list' is separate from 'document:get'
	if (!locals.permissions?.permissions.has('document:list')) {
		throw error(403, 'Permission denied: document:list required');
	}

	// Get FusionAuth access token from cookie for Neon RLS
	const accessToken = cookies.get('auth_access_token');
	const db = createAuthenticatedDbClient(accessToken);

	// Query with RLS - Neon validates JWT via JWKS
	// auth_user() resolves fusionauth_id → internal user_id
	// is_authenticated() checks permissions from JWT roles
	const documents = await db.query.documents.findMany();

	return json(documents);
};

export const POST: RequestHandler = async ({ request, locals, cookies }) => {
	if (!locals.user) {
		throw error(401, 'Authentication required');
	}

	if (!locals.activeTenantId) {
		throw error(400, 'Tenant context required');
	}

	// Each action has its own permission - 'document:create' is separate from 'document:update'
	if (!locals.permissions?.permissions.has('document:create')) {
		throw error(403, 'Permission denied: document:create required');
	}

	const accessToken = cookies.get('auth_access_token');
	const db = createAuthenticatedDbClient(accessToken);

	const body = await request.json();
	// Validate and create document...
};

Page Load Function

// src/routes/(authenticated)/dashboard/+page.server.ts
import { redirect, error } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ locals }) => {
	// Require authentication (from cookie-based session)
	if (!locals.user) {
		throw redirect(302, '/auth/login');
	}

	// Require tenant context
	if (!locals.activeTenantId) {
		throw redirect(302, '/select-tenant');
	}

	return {
		user: locals.user, // From auth_user cookie
		permissions: Array.from(locals.permissions?.permissions ?? []),
		tenantId: locals.activeTenantId,
		isRefreshInternal: locals.permissions?.isRefreshInternal ?? false
	};
};

Personal Route (No Tenant Required)

// src/routes/(authenticated)/personal/resources/+page.server.ts
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ locals, cookies }) => {
	if (!locals.user) {
		throw redirect(302, '/auth/login');
	}

	// Get FusionAuth access token for Neon RLS
	const accessToken = cookies.get('auth_access_token');
	const db = createAuthenticatedDbClient(accessToken);

	// Query personal resources (no tenant context)
	// RLS uses auth_user() to resolve FusionAuth ID → internal user_id
	const resources = await db.query.personalResources.findMany();

	return { resources };
};

Database Client with FusionAuth JWT

The FusionAuth access token is passed directly to Neon. No custom JWT generation is needed.

// src/lib/server/db/index.ts
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';

/**
 * Creates an authenticated database client using FusionAuth JWT.
 * Neon validates the JWT via FusionAuth JWKS endpoint.
 *
 * RLS policies use:
 * - auth_user(auth.user_id()) to resolve fusionauth_id → internal user_id
 * - has_permission(auth.session(), ARRAY[...], tenant_id) to check permissions
 */
export function createAuthenticatedDbClient(accessToken: string | undefined) {
	if (!accessToken) {
		throw new Error('Access token required for authenticated database operations');
	}

	const sql = neon(DATABASE_URL, {
		authToken: accessToken // FusionAuth JWT passed directly
	});

	return drizzle(sql, { schema });
}

/**
 * Creates an unauthenticated database client for public operations.
 * RLS policies will restrict access appropriately.
 */
export function createPublicDbClient() {
	const sql = neon(DATABASE_URL);
	return drizzle(sql, { schema });
}

Why no custom Neon JWT?

Previously, the app generated a custom JWT with user_id and tenant_id claims. Now:

1. FusionAuth JWT is passed directly to Neon

2. Neon validates via FusionAuth JWKS (/.well-known/jwks.json)

3. RLS uses auth_user() to resolve FusionAuth sub → internal user_id

4. RLS uses has_permission() to check permissions via auth_permission_cache

This is more future-proof as database schemas move to api-core.

OAuth Callback Implementation

// src/routes/auth/callback/+server.ts
import type { RequestHandler } from './$types';
import { redirect } from '@sveltejs/kit';

export const GET: RequestHandler = async ({ url, cookies }) => {
	const code = url.searchParams.get('code');
	const state = url.searchParams.get('state');

	// Verify state matches expected state (CSRF protection)
	if (!isValidState(state, cookies)) {
		throw error(400, 'Invalid state parameter');
	}

	// Exchange code for tokens
	const tokenResponse = await fetch(`${FUSIONAUTH_URL}/oauth2/token`, {
		method: 'POST',
		headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
		body: new URLSearchParams({
			grant_type: 'authorization_code',
			code: code!,
			client_id: FUSIONAUTH_APP_ID,
			client_secret: FUSIONAUTH_CLIENT_SECRET,
			redirect_uri: `${PUBLIC_URL}/auth/callback`
		})
	});

	const tokens = await tokenResponse.json();

	// Resolve identity and link if needed
	const jwt = await validateJwt(tokens.access_token);
	const identity = await resolveIdentity(jwt);

	// Store tokens in httpOnly cookies
	cookies.set('auth_access_token', tokens.access_token, {
		path: '/',
		httpOnly: true,
		secure: true,
		sameSite: 'lax',
		maxAge: tokens.expires_in // 60 minutes
	});

	cookies.set('auth_refresh_token', tokens.refresh_token, {
		path: '/',
		httpOnly: true,
		secure: true,
		sameSite: 'lax',
		maxAge: 60 * 60 * 24 * 30 // 30 days
	});

	// Store MINIMAL user info for UI (NOT httpOnly - accessible to client)
	// Permissions are NOT stored in cookie - resolved from JWT roles in hooks.server.ts
	const userSession: UserSession = {
		userId: identity.userId,
		email: identity.email,
		name: jwt.name,
		identityType: identity.type,
		tenantId: identity.tenantId
	};

	cookies.set('auth_user', btoa(JSON.stringify(userSession)), {
		path: '/',
		httpOnly: false,
		secure: true,
		sameSite: 'lax',
		maxAge: tokens.expires_in
	});

	// Redirect to app
	throw redirect(302, '/app');
};

Token Refresh

Token refresh is handled automatically by middleware. When the access token is near expiry, the middleware refreshes it using the refresh token cookie.

// src/lib/server/auth/refresh.ts
import type { Cookies } from '@sveltejs/kit';

export async function refreshTokensIfNeeded(cookies: Cookies): Promise<boolean> {
	const accessToken = cookies.get('auth_access_token');
	const refreshToken = cookies.get('auth_refresh_token');

	if (!refreshToken) {
		return false; // No refresh token - user must re-authenticate
	}

	// Check if access token is near expiry (within 5 minutes)
	if (accessToken) {
		try {
			const decoded = decodeJwtPayload(accessToken);
			const expiresAt = decoded.exp * 1000;
			const fiveMinutes = 5 * 60 * 1000;

			if (Date.now() < expiresAt - fiveMinutes) {
				return true; // Token still valid
			}
		} catch {
			// Token invalid - refresh needed
		}
	}

	// Refresh the tokens
	const response = await fetch(`${FUSIONAUTH_URL}/oauth2/token`, {
		method: 'POST',
		headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
		body: new URLSearchParams({
			grant_type: 'refresh_token',
			refresh_token: refreshToken,
			client_id: FUSIONAUTH_APP_ID,
			client_secret: FUSIONAUTH_CLIENT_SECRET
		})
	});

	if (!response.ok) {
		// Clear cookies and require re-authentication
		cookies.delete('auth_access_token', { path: '/' });
		cookies.delete('auth_refresh_token', { path: '/' });
		cookies.delete('auth_user', { path: '/' });
		return false;
	}

	const tokens = await response.json();

	// Update cookies with new tokens
	cookies.set('auth_access_token', tokens.access_token, {
		path: '/',
		httpOnly: true,
		secure: true,
		sameSite: 'lax',
		maxAge: tokens.expires_in
	});

	if (tokens.refresh_token) {
		cookies.set('auth_refresh_token', tokens.refresh_token, {
			path: '/',
			httpOnly: true,
			secure: true,
			sameSite: 'lax',
			maxAge: 60 * 60 * 24 * 30
		});
	}

	return true;
}

Troubleshooting

JWT Validation Failing

Problem: jwtVerify throws error

Solutions:

1. Check FusionAuth URL is correct

2. Verify JWKS endpoint is accessible

3. Check token hasn't expired

4. Verify audience matches app ID

Identity Not Linking

Problem: New user created instead of linking to HRIS identity

Solutions:

1. Verify email comparison uses case-insensitive matching (LOWER())

2. Verify HRIS sync created user_identities record

3. Check fusionauth_id is NULL on pre-created identity

4. Confirm emails are stored normalized (lowercase)

Permission Denied

Problem: 403 errors on API calls

Solutions:

1. Verify tenant_users record exists with status = 'active'

2. Check role has required permission via auth_role_permission table

3. Verify URL path contains correct :tenantId parameter

4. Check user is using correct identity for that tenant

Neon RLS Issues

Problem: RLS blocking queries

Solutions:

1. Verify FusionAuth access token is being passed to Neon via authToken

2. Check Neon is configured with FusionAuth JWKS URL

3. Verify auth_user() function is returning correct internal user_id

4. Check has_permission() is receiving correct permissions array

5. Verify user_auth_identities record exists for the FusionAuth user

6. Check auth_permission_cache is populated for the user

7. Verify auth_assignment exists linking user to appropriate roles

Related Documentation

• Architecture: Authentication Flow

• Architecture: User Management

• Architecture: Authorization

• Architecture: Multi-Tenancy

---

Last updated: December 2025