create-stackr 0.2.0

package/templates/base/web/src/lib/auth/actions.ts.ejs

@@ -0,0 +1,334 @@
+'use server';
+
+import {
+  setSessionCookie,
+  getSessionToken,
+  clearSessionCookie,
+  getDeviceSessionToken,
+} from './cookies';
+import { AUTH_CONFIG, BETTER_AUTH_COOKIE_NAME } from './config';
+
+// Types
+export interface User {
+  id: string;
+  email: string;
+  name: string | null;
+  emailVerified: boolean;
+  image: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Session {
+  id: string;
+  userId: string;
+  token: string;
+  expiresAt: string;
+  createdAt: string;
+  updatedAt: string;
+  ipAddress?: string;
+  userAgent?: string;
+}
+
+export interface AuthSession {
+  user: User;
+  session: Session;
+}
+
+interface SignInResult {
+  success: boolean;
+  error?: string;
+  session?: AuthSession;
+}
+
+interface SignUpResult {
+  success: boolean;
+  error?: string;
+<% if (features.authentication.emailVerification) { %>
+  needsEmailVerification?: boolean;
+<% } %>
+}
+
+/**
+ * Build headers for Fastify requests
+ * Includes session token in Better Auth cookie format and Origin for CSRF protection.
+ * Exported for reuse by other modules (e.g., sessions.ts).
+ */
+export async function buildAuthHeaders(): Promise<HeadersInit> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    // Origin header required for Better Auth CSRF protection
+    // Server Actions run in Node.js and don't automatically include Origin
+    'Origin': AUTH_CONFIG.appUrl,
+  };
+
+  const sessionToken = await getSessionToken();
+  if (sessionToken) {
+    headers['Cookie'] = `${BETTER_AUTH_COOKIE_NAME}=${sessionToken}`;
+  }
+
+  const deviceToken = await getDeviceSessionToken();
+  if (deviceToken) {
+    headers['X-Device-Session-Token'] = deviceToken;
+  }
+
+  return headers;
+}
+
+/**
+ * Sign in with email and password
+ */
+export async function signIn(email: string, password: string): Promise<SignInResult> {
+  try {
+    const response = await fetch(`${AUTH_CONFIG.backendUrl}/api/auth/sign-in/email`, {
+      method: 'POST',
+      headers: await buildAuthHeaders(),
+      body: JSON.stringify({ email, password }),
+      cache: 'no-store',
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      return {
+        success: false,
+        error: error.message || 'Invalid email or password',
+      };
+    }
+
+    // Extract session token from Set-Cookie header
+    const sessionToken = extractSessionToken(response);
+
+    if (!sessionToken) {
+      return { success: false, error: 'No session token received' };
+    }
+
+    // Set session cookie
+    await setSessionCookie(sessionToken);
+
+    // Get session data
+    const session = await getSession();
+
+    return { success: true, session: session || undefined };
+  } catch (error) {
+    console.error('Sign in error:', error);
+    return { success: false, error: 'An error occurred during sign in' };
+  }
+}
+
+/**
+ * Sign up with email and password
+ */
+export async function signUp(
+  email: string,
+  password: string,
+  name?: string
+): Promise<SignUpResult> {
+  try {
+    const response = await fetch(`${AUTH_CONFIG.backendUrl}/api/auth/sign-up/email`, {
+      method: 'POST',
+      headers: await buildAuthHeaders(),
+      body: JSON.stringify({ email, password, name }),
+      cache: 'no-store',
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      return {
+        success: false,
+        error: error.message || 'Failed to create account',
+      };
+    }
+
+<% if (features.authentication.emailVerification) { %>
+    const data = await response.json();
+
+    // Check if email verification is required
+    if (data.emailVerificationRequired) {
+      return { success: true, needsEmailVerification: true };
+    }
+<% } %>
+
+    // Extract and set session token
+    const sessionToken = extractSessionToken(response);
+
+    if (sessionToken) {
+      await setSessionCookie(sessionToken);
+    }
+
+    return { success: true };
+  } catch (error) {
+    console.error('Sign up error:', error);
+    return { success: false, error: 'An error occurred during sign up' };
+  }
+}
+
+/**
+ * Sign out current session
+ */
+export async function signOut(): Promise<{ success: boolean }> {
+  try {
+    await fetch(`${AUTH_CONFIG.backendUrl}/api/auth/sign-out`, {
+      method: 'POST',
+      headers: await buildAuthHeaders(),
+      body: JSON.stringify({}),
+      cache: 'no-store',
+    });
+  } catch (error) {
+    console.error('Sign out error:', error);
+  }
+
+  // Always clear local cookie
+  await clearSessionCookie();
+
+  return { success: true };
+}
+
+/**
+ * Get current session (validates with backend)
+ *
+ * Note: For client-side caching, use the AuthProvider which
+ * maintains a cache to avoid hitting the backend on every render.
+ */
+export async function getSession(): Promise<AuthSession | null> {
+  const sessionToken = await getSessionToken();
+
+  if (!sessionToken) {
+    return null;
+  }
+
+  try {
+    const response = await fetch(`${AUTH_CONFIG.backendUrl}/api/auth/get-session`, {
+      method: 'GET',
+      headers: await buildAuthHeaders(),
+      cache: 'no-store',
+    });
+
+    if (!response.ok) {
+      // Session invalid, clear cookie
+      await clearSessionCookie();
+      return null;
+    }
+
+    const data = await response.json();
+    return data as AuthSession;
+  } catch (error) {
+    console.error('Get session error:', error);
+    return null;
+  }
+}
+
+/**
+ * Request password reset email
+ */
+export async function requestPasswordReset(
+  email: string
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const response = await fetch(`${AUTH_CONFIG.backendUrl}/api/auth/forget-password`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        email,
+        redirectTo: `${AUTH_CONFIG.appUrl}/reset-password`,
+      }),
+      cache: 'no-store',
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      return { success: false, error: error.message || 'Failed to send reset email' };
+    }
+
+    return { success: true };
+  } catch (error) {
+    console.error('Password reset request error:', error);
+    return { success: false, error: 'An error occurred' };
+  }
+}
+
+/**
+ * Reset password with token
+ */
+export async function resetPassword(
+  token: string,
+  newPassword: string
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const response = await fetch(`${AUTH_CONFIG.backendUrl}/api/auth/reset-password`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token, newPassword }),
+      cache: 'no-store',
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      return { success: false, error: error.message || 'Failed to reset password' };
+    }
+
+    return { success: true };
+  } catch (error) {
+    console.error('Password reset error:', error);
+    return { success: false, error: 'An error occurred' };
+  }
+}
+
+<% if (features.authentication.emailVerification) { %>
+/**
+ * Verify email with token
+ */
+export async function verifyEmail(token: string): Promise<{ success: boolean; error?: string }> {
+  try {
+    const response = await fetch(`${AUTH_CONFIG.backendUrl}/api/auth/verify-email`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token }),
+      cache: 'no-store',
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      return { success: false, error: error.message || 'Failed to verify email' };
+    }
+
+    return { success: true };
+  } catch (error) {
+    console.error('Email verification error:', error);
+    return { success: false, error: 'An error occurred' };
+  }
+}
+<% } %>
+
+/**
+ * Extract session token from Set-Cookie header
+ *
+ * IMPORTANT: In Node.js 20+, use headers.getSetCookie() to get an array of cookies.
+ * The headers.get("set-cookie") method joins cookies with commas, which breaks
+ * parsing because cookie attributes like Expires contain commas (e.g., "Thu, 01 Jan 2025").
+ */
+function extractSessionToken(response: Response): string | null {
+  // Use getSetCookie() for proper cookie array handling (Node.js 20+)
+  // This returns an array of individual Set-Cookie header values
+  const setCookies = response.headers.getSetCookie?.() ?? [];
+
+  // Fallback for older Node.js versions or environments without getSetCookie
+  if (setCookies.length === 0) {
+    const setCookieHeader = response.headers.get('set-cookie');
+    if (!setCookieHeader) return null;
+
+    // Manual parsing fallback - split on ", " followed by a cookie name pattern
+    // This handles most cases but getSetCookie() is preferred
+    const cookiePattern = new RegExp(`${BETTER_AUTH_COOKIE_NAME}=([^;]+)`);
+    const match = setCookieHeader.match(cookiePattern);
+    return match ? match[1] : null;
+  }
+
+  for (const cookie of setCookies) {
+    const match = cookie.match(new RegExp(`${BETTER_AUTH_COOKIE_NAME}=([^;]+)`));
+    if (match) {
+      return match[1];
+    }
+  }
+
+  return null;
+}

package/templates/base/web/src/lib/auth/config.ts.ejs

@@ -0,0 +1,65 @@
+/**
+ * Auth configuration and constants
+ *
+ * Centralized configuration for authentication.
+ * Cookie names are constants to avoid magic strings scattered across the codebase.
+ */
+
+export const AUTH_CONFIG = {
+  // Public URL of the web app (for OAuth callbacks)
+  appUrl: process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000",
+
+  // Backend URL for server-to-server calls
+  // In development, you can use the Next.js proxy or direct URL
+  backendUrl: process.env.BACKEND_URL || "http://localhost:8080",
+
+  // Session cookie max age in seconds (should match Fastify config)
+  sessionMaxAge: 60 * 60 * 24 * 7, // 7 days
+
+  // Device session cookie max age
+  deviceSessionMaxAge: 60 * 60 * 24 * 30, // 30 days
+
+  // Device session heartbeat interval (client-side)
+  deviceHeartbeatInterval: 5 * 60 * 1000, // 5 minutes
+
+  // Enabled OAuth providers (from template config)
+<% if (features.authentication.providers.google) { %>
+  googleEnabled: true,
+<% } else { %>
+  googleEnabled: false,
+<% } %>
+<% if (features.authentication.providers.apple) { %>
+  appleEnabled: true,
+<% } else { %>
+  appleEnabled: false,
+<% } %>
+<% if (features.authentication.providers.github) { %>
+  githubEnabled: true,
+<% } else { %>
+  githubEnabled: false,
+<% } %>
+} as const;
+
+/**
+ * Cookie names used throughout the auth system
+ * Centralized to ensure consistency and make updates easier
+ */
+export const COOKIE_NAMES = {
+  // Session token from Better Auth (stored after sign in)
+  SESSION: "session_token",
+
+  // Device session token (for anonymous sessions)
+  DEVICE_SESSION: "device_session_token",
+
+  // OAuth PKCE verifier (temporary, during OAuth flow)
+  OAUTH_PKCE_VERIFIER: "oauth_pkce_verifier",
+
+  // OAuth state for CSRF protection (temporary, during OAuth flow)
+  OAUTH_STATE: "oauth_state",
+} as const;
+
+/**
+ * Better Auth cookie name (used when reading cookies set by Fastify)
+ * This must match the cookie name that Better Auth uses
+ */
+export const BETTER_AUTH_COOKIE_NAME = "better-auth.session_token";

package/templates/base/web/src/lib/auth/cookies.ts.ejs

@@ -0,0 +1,74 @@
+import { cookies } from 'next/headers';
+import { AUTH_CONFIG, COOKIE_NAMES } from './config';
+
+/**
+ * Set the session cookie after successful authentication
+ */
+export async function setSessionCookie(sessionToken: string): Promise<void> {
+  const cookieStore = await cookies();
+
+  cookieStore.set(COOKIE_NAMES.SESSION, sessionToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    maxAge: AUTH_CONFIG.sessionMaxAge,
+  });
+}
+
+/**
+ * Get the session token from cookies
+ */
+export async function getSessionToken(): Promise<string | undefined> {
+  const cookieStore = await cookies();
+  return cookieStore.get(COOKIE_NAMES.SESSION)?.value;
+}
+
+/**
+ * Clear the session cookie (for sign out)
+ */
+export async function clearSessionCookie(): Promise<void> {
+  const cookieStore = await cookies();
+  cookieStore.delete(COOKIE_NAMES.SESSION);
+}
+
+/**
+ * Clear all auth-related cookies
+ */
+export async function clearAuthCookies(): Promise<void> {
+  const cookieStore = await cookies();
+  cookieStore.delete(COOKIE_NAMES.SESSION);
+  cookieStore.delete(COOKIE_NAMES.OAUTH_PKCE_VERIFIER);
+  cookieStore.delete(COOKIE_NAMES.OAUTH_STATE);
+}
+
+/**
+ * Set device session cookie
+ */
+export async function setDeviceSessionCookie(token: string): Promise<void> {
+  const cookieStore = await cookies();
+
+  cookieStore.set(COOKIE_NAMES.DEVICE_SESSION, token, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    maxAge: AUTH_CONFIG.deviceSessionMaxAge,
+  });
+}
+
+/**
+ * Get device session token from cookies
+ */
+export async function getDeviceSessionToken(): Promise<string | undefined> {
+  const cookieStore = await cookies();
+  return cookieStore.get(COOKIE_NAMES.DEVICE_SESSION)?.value;
+}
+
+/**
+ * Clear device session cookie
+ */
+export async function clearDeviceSessionCookie(): Promise<void> {
+  const cookieStore = await cookies();
+  cookieStore.delete(COOKIE_NAMES.DEVICE_SESSION);
+}

package/templates/base/web/src/lib/auth/index.ts.ejs

@@ -0,0 +1,40 @@
+/**
+ * Auth module exports
+ *
+ * This barrel file provides a clean public API for the auth module.
+ * Import from '@/lib/auth' instead of individual files.
+ */
+
+// Configuration
+export { AUTH_CONFIG, COOKIE_NAMES, BETTER_AUTH_COOKIE_NAME } from "./config";
+
+// Server actions for authentication
+export {
+  signIn,
+  signUp,
+  signOut,
+  getSession,
+  requestPasswordReset,
+  resetPassword,
+  buildAuthHeaders,
+<% if (features.authentication.emailVerification) { %>
+  verifyEmail,
+<% } %>
+  type User,
+  type Session,
+  type AuthSession,
+} from "./actions";
+
+// OAuth actions
+export { initiateOAuth, getOAuthUrl } from "./oauth";
+
+// Cookie utilities (server-side only)
+export {
+  setSessionCookie,
+  getSessionToken,
+  clearSessionCookie,
+  clearAuthCookies,
+} from "./cookies";
+
+// PKCE utilities (server-side only)
+export { generatePKCE, verifyPKCE } from "./pkce";

package/templates/base/web/src/lib/auth/oauth.ts.ejs

@@ -0,0 +1,72 @@
+'use server';
+
+import { cookies } from 'next/headers';
+import crypto from 'crypto';
+import { generatePKCE } from './pkce';
+import { AUTH_CONFIG, COOKIE_NAMES } from './config';
+
+type OAuthProvider = 'google' | 'apple' | 'github';
+
+interface InitiateOAuthResult {
+  url: string;
+}
+
+/**
+ * Initiate OAuth flow with PKCE
+ *
+ * Generates PKCE parameters, stores verifier in secure cookie,
+ * and returns the OAuth initiation URL.
+ *
+ * The browser will redirect to this URL, which starts the OAuth flow.
+ */
+export async function initiateOAuth(provider: OAuthProvider): Promise<InitiateOAuthResult> {
+  const { verifier, challenge } = generatePKCE();
+  const state = crypto.randomUUID();
+
+  const cookieStore = await cookies();
+
+  // Store verifier in httpOnly cookie
+  // This cookie travels with the browser and is read during the callback
+  cookieStore.set(COOKIE_NAMES.OAUTH_PKCE_VERIFIER, verifier, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 600, // 10 minutes
+  });
+
+  // Store state for CSRF verification
+  cookieStore.set(COOKIE_NAMES.OAUTH_STATE, state, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 600,
+  });
+
+  // Build OAuth initiation URL
+  const callbackUrl = `${AUTH_CONFIG.appUrl}/auth/callback`;
+
+  const params = new URLSearchParams({
+    provider,
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    state,
+    callback_url: callbackUrl,
+  });
+
+  const url = `${AUTH_CONFIG.backendUrl}/api/auth/web/oauth/init?${params}`;
+
+  return { url };
+}
+
+/**
+ * Get OAuth URL for direct navigation
+ *
+ * This is a convenience wrapper that can be used by OAuth buttons
+ * to get the URL for client-side redirect.
+ */
+export async function getOAuthUrl(provider: OAuthProvider): Promise<string> {
+  const result = await initiateOAuth(provider);
+  return result.url;
+}

package/templates/base/web/src/lib/auth/pkce.ts.ejs

@@ -0,0 +1,48 @@
+import crypto from 'crypto';
+
+/**
+ * Generate PKCE (Proof Key for Code Exchange) parameters
+ *
+ * PKCE prevents authorization code interception attacks by requiring
+ * the client to prove it initiated the OAuth request.
+ *
+ * The verifier is stored in a httpOnly cookie and sent during token exchange.
+ * The challenge is sent during OAuth initiation and stored server-side.
+ * When exchanging the token, the server verifies SHA256(verifier) === challenge.
+ *
+ * @returns Object containing verifier and challenge
+ */
+export function generatePKCE(): { verifier: string; challenge: string } {
+  // Generate 32 bytes of random data for verifier (256 bits of entropy)
+  // This exceeds the PKCE spec minimum of 43 characters
+  const verifierBuffer = crypto.randomBytes(32);
+  const verifier = verifierBuffer.toString('base64url');
+
+  // SHA256 hash the verifier for the challenge
+  const challengeBuffer = crypto.createHash('sha256').update(verifier).digest();
+  const challenge = challengeBuffer.toString('base64url');
+
+  return { verifier, challenge };
+}
+
+/**
+ * Verify a PKCE verifier against a challenge
+ *
+ * This is primarily used for testing. In production, the verification
+ * happens on the Fastify server during token exchange.
+ *
+ * @param verifier - The original random string
+ * @param challenge - The SHA256 hash to verify against
+ * @returns true if the verifier produces the challenge
+ */
+export function verifyPKCE(verifier: string, challenge: string): boolean {
+  const computedChallenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+
+  // Use timing-safe comparison to prevent timing attacks
+  try {
+    return crypto.timingSafeEqual(Buffer.from(computedChallenge), Buffer.from(challenge));
+  } catch {
+    // Buffers have different lengths
+    return false;
+  }
+}