Initial commit

src/app/api/auth/admin/login/route.ts

@@ -0,0 +1,114 @@
+/**
+ * Component: Local Admin Login Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { prisma } from '@/lib/db';
+import bcrypt from 'bcrypt';
+import { generateAccessToken, generateRefreshToken } from '@/lib/utils/jwt';
+import { getEncryptionService } from '@/lib/services/encryption.service';
+
+/**
+ * POST /api/auth/admin/login
+ * Authenticates local admin users with username and password
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const { username, password } = await request.json();
+
+    if (!username || !password) {
+      return NextResponse.json(
+        {
+          error: 'ValidationError',
+          message: 'Username and password are required',
+        },
+        { status: 400 }
+      );
+    }
+
+    // Find user by local admin identifier
+    const user = await prisma.user.findUnique({
+      where: { plexId: `local-${username}` },
+    });
+
+    if (!user) {
+      return NextResponse.json(
+        {
+          error: 'AuthenticationError',
+          message: 'Invalid username or password',
+        },
+        { status: 401 }
+      );
+    }
+
+    // Verify password
+    // authToken contains an encrypted bcrypt hash, so we need to decrypt it first
+    let passwordValid = false;
+    try {
+      const encryptionService = getEncryptionService();
+      const decryptedHash = encryptionService.decrypt(user.authToken || '');
+      passwordValid = await bcrypt.compare(password, decryptedHash);
+    } catch (error) {
+      console.error('[AdminLogin] Password verification failed:', error);
+      return NextResponse.json(
+        {
+          error: 'AuthenticationError',
+          message: 'Invalid username or password',
+        },
+        { status: 401 }
+      );
+    }
+
+    if (!passwordValid) {
+      return NextResponse.json(
+        {
+          error: 'AuthenticationError',
+          message: 'Invalid username or password',
+        },
+        { status: 401 }
+      );
+    }
+
+    // Update last login time
+    await prisma.user.update({
+      where: { id: user.id },
+      data: { lastLoginAt: new Date() },
+    });
+
+    // Generate JWT tokens
+    const accessToken = generateAccessToken({
+      sub: user.id,
+      plexId: user.plexId,
+      username: user.plexUsername,
+      role: user.role,
+    });
+
+    const refreshToken = generateRefreshToken(user.id);
+
+    // Return tokens and user info
+    return NextResponse.json({
+      success: true,
+      accessToken,
+      refreshToken,
+      user: {
+        id: user.id,
+        plexId: user.plexId,
+        username: user.plexUsername,
+        email: user.plexEmail,
+        role: user.role,
+        avatarUrl: user.avatarUrl,
+      },
+    });
+  } catch (error) {
+    console.error('Failed to authenticate admin user:', error);
+    return NextResponse.json(
+      {
+        error: 'AuthenticationError',
+        message: 'Failed to authenticate',
+        details: error instanceof Error ? error.message : 'Unknown error',
+      },
+      { status: 500 }
+    );
+  }
+}

src/app/api/auth/is-local-admin/route.ts

@@ -0,0 +1,30 @@
+/**
+ * Component: Check Local Admin Status Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest, isLocalAdmin } from '@/lib/middleware/auth';
+
+/**
+ * GET /api/auth/is-local-admin
+ * Check if current authenticated user is a local admin (setup admin)
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    if (!req.user) {
+      return NextResponse.json(
+        {
+          isLocalAdmin: false,
+        },
+        { status: 200 }
+      );
+    }
+
+    const localAdmin = await isLocalAdmin(req.user.id);
+
+    return NextResponse.json({
+      isLocalAdmin: localAdmin,
+    });
+  });
+}

src/app/api/auth/local/login/route.ts

@@ -0,0 +1,59 @@
+/**
+ * Local Login Endpoint
+ * Documentation: documentation/features/audiobookshelf-integration.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { LocalAuthProvider } from '@/lib/services/auth/LocalAuthProvider';
+
+export async function POST(request: NextRequest) {
+  try {
+    const { username, password } = await request.json();
+
+    if (!username || !password) {
+      return NextResponse.json(
+        { error: 'Username and password are required' },
+        { status: 400 }
+      );
+    }
+
+    console.log('[LocalLogin] Attempting login for username:', username);
+
+    const provider = new LocalAuthProvider();
+    const result = await provider.handleCallback({ username, password });
+
+    if (!result.success) {
+      if (result.requiresApproval) {
+        console.log('[LocalLogin] Account pending approval:', username);
+        return NextResponse.json({
+          success: false,
+          pendingApproval: true,
+          message: 'Account pending admin approval.',
+        });
+      }
+      console.error('[LocalLogin] Login failed:', result.error);
+      return NextResponse.json(
+        { error: result.error },
+        { status: 401 }
+      );
+    }
+
+    console.log('[LocalLogin] Login successful for:', username);
+    console.log('[LocalLogin] User data:', result.user);
+    console.log('[LocalLogin] Token generated successfully');
+
+    // Return tokens for login
+    return NextResponse.json({
+      success: true,
+      user: result.user,
+      accessToken: result.tokens!.accessToken,
+      refreshToken: result.tokens!.refreshToken,
+    });
+  } catch (error) {
+    console.error('[LocalLogin] Error:', error);
+    return NextResponse.json(
+      { error: 'Login failed' },
+      { status: 500 }
+    );
+  }
+}

src/app/api/auth/logout/route.ts

@@ -0,0 +1,23 @@
+/**
+ * Component: Logout Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextResponse } from 'next/server';
+
+/**
+ * POST /api/auth/logout
+ * Logout user (client-side token clearing, stateless JWT)
+ */
+export async function POST() {
+  // Since we're using stateless JWT, logout is primarily client-side
+  // The client should clear tokens from storage
+
+  // TODO: In the future, implement token blacklist for enhanced security
+  // This would require storing revoked tokens in Redis with expiration
+
+  return NextResponse.json({
+    success: true,
+    message: 'Logged out successfully',
+  });
+}

src/app/api/auth/me/route.ts

@@ -0,0 +1,69 @@
+/**
+ * Component: Current User Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+
+/**
+ * GET /api/auth/me
+ * Get current authenticated user information
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    if (!req.user) {
+      return NextResponse.json(
+        {
+          error: 'Unauthorized',
+          message: 'User not authenticated',
+        },
+        { status: 401 }
+      );
+    }
+
+    // Fetch full user details from database
+    const user = await prisma.user.findUnique({
+      where: { id: req.user.id },
+      select: {
+        id: true,
+        plexId: true,
+        plexUsername: true,
+        plexEmail: true,
+        role: true,
+        isSetupAdmin: true,
+        avatarUrl: true,
+        createdAt: true,
+        lastLoginAt: true,
+      },
+    });
+
+    if (!user) {
+      return NextResponse.json(
+        {
+          error: 'NotFound',
+          message: 'User not found',
+        },
+        { status: 404 }
+      );
+    }
+
+    // Determine if user is local admin (setup admin with local authentication)
+    const isLocalAdmin = user.isSetupAdmin && user.plexId.startsWith('local-');
+
+    return NextResponse.json({
+      user: {
+        id: user.id,
+        plexId: user.plexId,
+        username: user.plexUsername,
+        email: user.plexEmail,
+        role: user.role,
+        isLocalAdmin: isLocalAdmin,
+        avatarUrl: user.avatarUrl,
+        createdAt: user.createdAt,
+        lastLoginAt: user.lastLoginAt,
+      },
+    });
+  });
+}

src/app/api/auth/oidc/callback/route.ts

@@ -0,0 +1,140 @@
+/**
+ * OIDC Callback Handler Endpoint
+ * Documentation: documentation/features/audiobookshelf-integration.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getAuthProvider } from '@/lib/services/auth';
+import { getBaseUrl } from '@/lib/utils/url';
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const code = searchParams.get('code');
+  const state = searchParams.get('state');
+  const error = searchParams.get('error');
+  const errorDescription = searchParams.get('error_description');
+
+  const baseUrl = getBaseUrl();
+
+  // Handle OAuth errors from provider
+  if (error) {
+    const errorMsg = errorDescription || error;
+    return NextResponse.redirect(`${baseUrl}/login?error=${encodeURIComponent(errorMsg)}`);
+  }
+
+  if (!code || !state) {
+    return NextResponse.redirect(`${baseUrl}/login?error=${encodeURIComponent('Missing authorization code or state')}`);
+  }
+
+  try {
+    // Get OIDC auth provider
+    const authProvider = await getAuthProvider('oidc');
+
+    // Handle callback
+    const result = await authProvider.handleCallback({ code, state });
+
+    if (!result.success) {
+      // Check if approval is required
+      if (result.requiresApproval) {
+        return NextResponse.redirect(`${baseUrl}/login?pending=approval`);
+      }
+
+      // Authentication failed
+      return NextResponse.redirect(`${baseUrl}/login?error=${encodeURIComponent(result.error || 'Authentication failed')}`);
+    }
+
+    // Authentication successful - prepare user data
+    if (!result.tokens || !result.user) {
+      return NextResponse.redirect(`${baseUrl}/login?error=${encodeURIComponent('Authentication data missing')}`);
+    }
+
+    // Prepare auth data to pass via URL hash (works across all browsers)
+    const authData = {
+      accessToken: result.tokens.accessToken,
+      refreshToken: result.tokens.refreshToken,
+      user: {
+        id: result.user.id,
+        plexId: result.user.id, // Use id as plexId for consistency
+        username: result.user.username,
+        email: result.user.email,
+        role: result.user.isAdmin ? 'admin' : 'user',
+        avatarUrl: result.user.avatarUrl,
+      },
+    };
+    const authDataEncoded = encodeURIComponent(JSON.stringify(authData));
+
+    // Prepare user data for cookie
+    const userDataJson = JSON.stringify(authData.user);
+
+    // Determine redirect URL based on first login status
+    let redirectUrl: string;
+    if (result.isFirstLogin) {
+      // First login - redirect to initializing page to show job progress
+      redirectUrl = `${baseUrl}/setup/initializing#authData=${authDataEncoded}`;
+      console.log('[OIDC Callback] First login detected - redirecting to initializing page');
+    } else {
+      // Normal login - redirect to login page with auth success
+      redirectUrl = `${baseUrl}/login?auth=success#authData=${authDataEncoded}`;
+    }
+
+    // Return HTML page with cookies set and JavaScript redirect with hash
+    // This ensures tokens are accessible to frontend via both cookies and URL hash
+    const html = `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <title>Login Successful</title>
+        </head>
+        <body>
+          <p>Login successful. Redirecting...</p>
+          <script>
+            // Use JavaScript redirect with hash parameter for compatibility
+            // Hash params aren't sent to server, so tokens stay client-side
+            setTimeout(() => {
+              window.location.href = '${redirectUrl}';
+            }, 100);
+          </script>
+        </body>
+      </html>
+    `;
+
+    const response = new NextResponse(html, {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/html',
+      },
+    });
+
+    // Set tokens in cookies (httpOnly: false so JavaScript can read them)
+    response.cookies.set('accessToken', result.tokens.accessToken, {
+      httpOnly: false, // Need to be accessible to JavaScript
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      maxAge: 60 * 60, // 1 hour
+      path: '/',
+    });
+
+    response.cookies.set('refreshToken', result.tokens.refreshToken, {
+      httpOnly: true, // Keep refresh token secure
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      maxAge: 60 * 60 * 24 * 7, // 7 days
+      path: '/',
+    });
+
+    response.cookies.set('userData', encodeURIComponent(userDataJson), {
+      httpOnly: false,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      maxAge: 60 * 60, // 1 hour
+      path: '/',
+    });
+
+    return response;
+  } catch (error) {
+    console.error('[OIDC Callback] Authentication failed:', error);
+
+    const errorMsg = error instanceof Error ? error.message : 'Authentication failed';
+    return NextResponse.redirect(`${baseUrl}/login?error=${encodeURIComponent(errorMsg)}`);
+  }
+}

src/app/api/auth/oidc/login/route.ts

@@ -0,0 +1,35 @@
+/**
+ * OIDC Login Initiation Endpoint
+ * Documentation: documentation/features/audiobookshelf-integration.md
+ */
+
+import { NextResponse } from 'next/server';
+import { getAuthProvider } from '@/lib/services/auth';
+import { getBaseUrl } from '@/lib/utils/url';
+
+export async function GET() {
+  try {
+    // Get OIDC auth provider
+    const authProvider = await getAuthProvider('oidc');
+
+    // Initiate login flow
+    const { redirectUrl } = await authProvider.initiateLogin();
+
+    if (!redirectUrl) {
+      return NextResponse.json(
+        { error: 'Failed to generate authorization URL' },
+        { status: 500 }
+      );
+    }
+
+    // Redirect to OIDC provider
+    return NextResponse.redirect(redirectUrl);
+  } catch (error) {
+    console.error('[OIDC Login] Failed to initiate login:', error);
+
+    // Redirect to login page with error
+    const baseUrl = getBaseUrl();
+    const errorMessage = error instanceof Error ? error.message : 'Failed to initiate login';
+    return NextResponse.redirect(`${baseUrl}/login?error=${encodeURIComponent(errorMessage)}`);
+  }
+}

src/app/api/auth/plex/callback/route.ts

@@ -0,0 +1,364 @@
+/**
+ * Component: Plex OAuth Callback Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getPlexService } from '@/lib/integrations/plex.service';
+import { getEncryptionService } from '@/lib/services/encryption.service';
+import { getConfigService } from '@/lib/services/config.service';
+import { generateAccessToken, generateRefreshToken } from '@/lib/utils/jwt';
+import { prisma } from '@/lib/db';
+
+/**
+ * GET /api/auth/plex/callback?pinId=12345
+ * Polls Plex PIN status and completes OAuth flow
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const searchParams = request.nextUrl.searchParams;
+    const pinId = searchParams.get('pinId');
+
+    if (!pinId) {
+      return NextResponse.json(
+        {
+          error: 'ValidationError',
+          message: 'Missing pinId parameter',
+        },
+        { status: 400 }
+      );
+    }
+
+    const plexService = getPlexService();
+    const encryptionService = getEncryptionService();
+
+    // Check PIN status
+    const authToken = await plexService.checkPin(parseInt(pinId, 10));
+
+    if (!authToken) {
+      // Still waiting for user to authorize
+      return NextResponse.json(
+        {
+          success: false,
+          authorized: false,
+          message: 'Waiting for user authorization',
+        },
+        { status: 202 } // 202 Accepted - still processing
+      );
+    }
+
+    // Get user info from Plex
+    const plexUser = await plexService.getUserInfo(authToken);
+
+    // Validate user info
+    if (!plexUser || !plexUser.id) {
+      console.error('[Plex OAuth] Invalid user info received:', plexUser);
+      return NextResponse.json(
+        {
+          error: 'OAuthError',
+          message: 'Failed to get user information from Plex',
+          details: 'User ID is missing from Plex response',
+        },
+        { status: 500 }
+      );
+    }
+
+    if (!plexUser.username) {
+      console.error('[Plex OAuth] Username missing from Plex user:', plexUser);
+      return NextResponse.json(
+        {
+          error: 'OAuthError',
+          message: 'Failed to get user information from Plex',
+          details: 'Username is missing from Plex response',
+        },
+        { status: 500 }
+      );
+    }
+
+    // Convert id to string safely
+    const plexIdString = typeof plexUser.id === 'string' ? plexUser.id : plexUser.id.toString();
+
+    // Get configured Plex server settings
+    const configService = getConfigService();
+    const plexConfig = await configService.getPlexConfig();
+
+    // Verify server is configured
+    if (!plexConfig.serverUrl || !plexConfig.authToken) {
+      console.error('[Plex OAuth] Server not configured');
+      return NextResponse.json(
+        {
+          error: 'ConfigurationError',
+          message: 'Plex server is not configured. Please contact your administrator.',
+        },
+        { status: 503 }
+      );
+    }
+
+    // Get server machine identifier from stored configuration
+    // Note: machineIdentifier is stored during setup/settings configuration
+    const serverMachineId = plexConfig.machineIdentifier;
+
+    if (!serverMachineId) {
+      console.error('[Plex OAuth] machineIdentifier not found in configuration');
+      return NextResponse.json(
+        {
+          error: 'ConfigurationError',
+          message: 'Server configuration incomplete. Please contact your administrator to re-configure Plex settings.',
+        },
+        { status: 503 }
+      );
+    }
+
+    console.log('[Plex OAuth] Using stored machineIdentifier:', serverMachineId);
+
+    // SECURITY: Verify user has access to the configured Plex server
+    // This checks if the server appears in the user's list of accessible servers from plex.tv
+    // This properly validates shared access permissions
+    const hasAccess = await plexService.verifyServerAccess(
+      plexConfig.serverUrl,
+      serverMachineId,
+      authToken
+    );
+
+    if (!hasAccess) {
+      console.warn('[Plex OAuth] User attempted to authenticate without server access:', {
+        plexId: plexIdString,
+        username: plexUser.username,
+        serverMachineId,
+      });
+      return NextResponse.json(
+        {
+          error: 'AccessDenied',
+          message: 'You do not have access to this Plex server. Please contact the administrator to share their library with you.',
+        },
+        { status: 403 }
+      );
+    }
+
+    console.log('[Plex OAuth] User verified with server access:', plexUser.username);
+
+    // Check for Plex Home profiles
+    const homeUsers = await plexService.getHomeUsers(authToken);
+    console.log('[Plex OAuth] Found home users:', homeUsers.length);
+
+    // If multiple home users exist, redirect to profile selection
+    // (Only show selection if there's more than just the main account)
+    if (homeUsers.length > 1) {
+      console.log('[Plex OAuth] Account has multiple home profiles, redirecting to profile selection');
+
+      // Detect if this is a browser request (mobile redirect) vs AJAX (desktop popup polling)
+      const accept = request.headers.get('accept') || '';
+      const isBrowserRequest = accept.includes('text/html');
+
+      if (isBrowserRequest) {
+        // For browser requests (mobile), construct redirect URL with session data
+        const host = request.headers.get('host') || 'localhost:3030';
+        const protocol = request.headers.get('x-forwarded-proto') ||
+                        (process.env.NODE_ENV === 'production' ? 'https' : 'http');
+        const selectProfileUrl = `${protocol}://${host}/auth/select-profile?pinId=${pinId}`;
+
+        console.log('[Plex OAuth] Redirecting to profile selection:', selectProfileUrl);
+
+        // Return HTML page with JavaScript to store token in sessionStorage and redirect
+        const html = `
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <title>Select Profile</title>
+            </head>
+            <body>
+              <p>Loading profiles...</p>
+              <script>
+                // Store main account token in session storage for profile selection page
+                sessionStorage.setItem('plex_main_token', '${authToken}');
+                // Redirect to profile selection
+                window.location.href = '${selectProfileUrl}';
+              </script>
+            </body>
+          </html>
+        `;
+
+        return new NextResponse(html, {
+          status: 200,
+          headers: {
+            'Content-Type': 'text/html',
+          },
+        });
+      } else {
+        // For AJAX requests (desktop popup), return JSON with redirect instruction
+        return NextResponse.json({
+          success: true,
+          authorized: true,
+          requiresProfileSelection: true,
+          redirectUrl: `/auth/select-profile?pinId=${pinId}`,
+          mainAccountToken: authToken, // Client will store this temporarily
+          homeUsers: homeUsers.length,
+        });
+      }
+    }
+
+    console.log('[Plex OAuth] Single profile or no additional profiles, continuing with main account authentication');
+
+    // No home users - continue with normal authentication flow using main account
+    // Check if this is the first user (should be promoted to admin)
+    const userCount = await prisma.user.count();
+    const isFirstUser = userCount === 0;
+    const role = isFirstUser ? 'admin' : 'user';
+
+    // Create or update user in database
+    const user = await prisma.user.upsert({
+      where: { plexId: plexIdString },
+      create: {
+        plexId: plexIdString,
+        plexUsername: plexUser.username,
+        plexEmail: plexUser.email || null,
+        role,
+        avatarUrl: plexUser.thumb || null,
+        authToken: encryptionService.encrypt(authToken),
+        lastLoginAt: new Date(),
+      },
+      update: {
+        plexUsername: plexUser.username,
+        plexEmail: plexUser.email || null,
+        avatarUrl: plexUser.thumb || null,
+        authToken: encryptionService.encrypt(authToken),
+        lastLoginAt: new Date(),
+      },
+    });
+
+    // Generate JWT tokens
+    const accessToken = generateAccessToken({
+      sub: user.id,
+      plexId: user.plexId,
+      username: user.plexUsername,
+      role: user.role,
+    });
+
+    const refreshToken = generateRefreshToken(user.id);
+
+    // Detect if this is a browser request (mobile redirect) vs AJAX (desktop popup polling)
+    const accept = request.headers.get('accept') || '';
+    const isBrowserRequest = accept.includes('text/html');
+
+    // For browser requests (mobile), set cookies and redirect to login page
+    if (isBrowserRequest) {
+      // Construct the redirect URL from headers (not request.url which may be 0.0.0.0)
+      const host = request.headers.get('host') || 'localhost:3030';
+      const protocol = request.headers.get('x-forwarded-proto') ||
+                      (process.env.NODE_ENV === 'production' ? 'https' : 'http');
+      const redirectUrl = `${protocol}://${host}/login?auth=success`;
+
+      console.log('[Plex OAuth] Setting cookies for mobile auth...');
+      console.log('[Plex OAuth] Redirect URL:', redirectUrl);
+
+      // Prepare user data
+      const userDataJson = JSON.stringify({
+        id: user.id,
+        plexId: user.plexId,
+        username: user.plexUsername,
+        email: user.plexEmail,
+        role: user.role,
+        avatarUrl: user.avatarUrl,
+      });
+      console.log('[Plex OAuth] Setting userData cookie:', userDataJson);
+
+      // Prepare auth data to pass via URL hash (fallback for mobile browsers that block cookies)
+      const authData = {
+        accessToken,
+        refreshToken,
+        user: {
+          id: user.id,
+          plexId: user.plexId,
+          username: user.plexUsername,
+          email: user.plexEmail,
+          role: user.role,
+          avatarUrl: user.avatarUrl,
+        },
+      };
+      const authDataEncoded = encodeURIComponent(JSON.stringify(authData));
+
+      // Return HTML page with cookies set and JavaScript redirect with hash
+      // This ensures cookies are properly set before redirecting
+      // The hash also provides a fallback for mobile browsers that block cookies on redirects
+      const html = `
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <title>Login Successful</title>
+          </head>
+          <body>
+            <p>Login successful. Redirecting...</p>
+            <script>
+              // Use JavaScript redirect with hash parameter for mobile compatibility
+              // Hash params aren't sent to server, so tokens stay client-side
+              setTimeout(() => {
+                window.location.href = '${redirectUrl}#authData=${authDataEncoded}';
+              }, 100);
+            </script>
+          </body>
+        </html>
+      `;
+
+      const response = new NextResponse(html, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/html',
+        },
+      });
+
+      // Set tokens in cookies
+      response.cookies.set('accessToken', accessToken, {
+        httpOnly: false, // Need to be accessible to JavaScript
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax',
+        maxAge: 60 * 60, // 1 hour
+        path: '/',
+      });
+
+      response.cookies.set('refreshToken', refreshToken, {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax',
+        maxAge: 60 * 60 * 24 * 7, // 7 days
+        path: '/',
+      });
+
+      response.cookies.set('userData', encodeURIComponent(userDataJson), {
+        httpOnly: false,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax',
+        maxAge: 60 * 60, // 1 hour
+        path: '/',
+      });
+
+      console.log('[Plex OAuth] Cookies set successfully, returning HTML redirect to:', redirectUrl);
+      return response;
+    }
+
+    // Return tokens and user info (for AJAX requests from desktop popup)
+    return NextResponse.json({
+      success: true,
+      authorized: true,
+      accessToken,
+      refreshToken,
+      user: {
+        id: user.id,
+        plexId: user.plexId,
+        username: user.plexUsername,
+        email: user.plexEmail,
+        role: user.role,
+        avatarUrl: user.avatarUrl,
+      },
+    });
+  } catch (error) {
+    console.error('Failed to complete Plex OAuth:', error);
+    return NextResponse.json(
+      {
+        error: 'OAuthError',
+        message: 'Failed to complete authentication',
+        details: error instanceof Error ? error.message : 'Unknown error',
+      },
+      { status: 500 }
+    );
+  }
+}

src/app/api/auth/plex/home-users/route.ts

@@ -0,0 +1,44 @@
+/**
+ * Component: Plex Home Users API
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getPlexService } from '@/lib/integrations/plex.service';
+
+/**
+ * GET /api/auth/plex/home-users
+ * Get list of Plex Home profiles for authenticated user
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const authToken = request.headers.get('X-Plex-Token');
+
+    if (!authToken) {
+      return NextResponse.json(
+        {
+          error: 'Unauthorized',
+          message: 'Missing authentication token',
+        },
+        { status: 401 }
+      );
+    }
+
+    const plexService = getPlexService();
+    const users = await plexService.getHomeUsers(authToken);
+
+    return NextResponse.json({
+      success: true,
+      users,
+    });
+  } catch (error) {
+    console.error('Failed to get home users:', error);
+    return NextResponse.json(
+      {
+        error: 'ServerError',
+        message: 'Failed to fetch home users',
+      },
+      { status: 500 }
+    );
+  }
+}

src/app/api/auth/plex/login/route.ts

@@ -0,0 +1,45 @@
+/**
+ * Component: Plex OAuth Login Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getPlexService } from '@/lib/integrations/plex.service';
+
+/**
+ * POST /api/auth/plex/login
+ * Initiates Plex OAuth flow by requesting a PIN
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const plexService = getPlexService();
+
+    // Request PIN from Plex
+    const pin = await plexService.requestPin();
+
+    // Construct callback URL from the request's origin
+    // This allows the app to work when accessed via localhost, local IP, or domain
+    const origin = request.headers.get('origin') || request.headers.get('referer') || 'http://localhost:3030';
+    const baseUrl = origin.replace(/\/$/, ''); // Remove trailing slash if present
+    const callbackUrl = `${baseUrl}/api/auth/plex/callback`;
+
+    // Generate OAuth URL with pinId
+    const authUrl = plexService.getOAuthUrl(pin.code, pin.id, callbackUrl);
+
+    return NextResponse.json({
+      success: true,
+      pinId: pin.id,
+      code: pin.code,
+      authUrl,
+    });
+  } catch (error) {
+    console.error('Failed to initiate Plex OAuth:', error);
+    return NextResponse.json(
+      {
+        error: 'OAuthError',
+        message: 'Failed to initiate Plex authentication',
+      },
+      { status: 500 }
+    );
+  }
+}

src/app/api/auth/plex/switch-profile/route.ts

@@ -0,0 +1,180 @@
+/**
+ * Component: Plex Profile Switch API
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getPlexService } from '@/lib/integrations/plex.service';
+import { getEncryptionService } from '@/lib/services/encryption.service';
+import { generateAccessToken, generateRefreshToken } from '@/lib/utils/jwt';
+import { prisma } from '@/lib/db';
+
+/**
+ * POST /api/auth/plex/switch-profile
+ * Switch to a Plex Home profile and complete authentication
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const mainAccountToken = request.headers.get('X-Plex-Token');
+
+    if (!mainAccountToken) {
+      return NextResponse.json(
+        {
+          error: 'Unauthorized',
+          message: 'Missing authentication token',
+        },
+        { status: 401 }
+      );
+    }
+
+    const body = await request.json();
+    const { userId, pin, pinId, profileInfo } = body;
+
+    if (!userId) {
+      return NextResponse.json(
+        {
+          error: 'ValidationError',
+          message: 'Missing userId',
+        },
+        { status: 400 }
+      );
+    }
+
+    const plexService = getPlexService();
+    const encryptionService = getEncryptionService();
+
+    // Switch to selected profile
+    let profileToken: string;
+    try {
+      const token = await plexService.switchHomeUser(userId, mainAccountToken, pin);
+      if (!token) {
+        throw new Error('Failed to get profile token');
+      }
+      profileToken = token;
+    } catch (error: any) {
+      if (error.message === 'Invalid PIN') {
+        return NextResponse.json(
+          {
+            error: 'InvalidPIN',
+            message: 'Invalid PIN for this profile',
+          },
+          { status: 401 }
+        );
+      }
+      throw error;
+    }
+
+    // Use profile info from request (already has all the info from home users list)
+    // or fall back to getUserInfo for main accounts
+    let profilePlexId: string;
+    let profileUsername: string;
+    let profileEmail: string | null;
+    let profileThumb: string | null;
+
+    if (profileInfo && profileInfo.uuid) {
+      // Use provided profile info (from home users list - more reliable for managed users)
+      profilePlexId = profileInfo.uuid;
+      profileUsername = profileInfo.friendlyName || `User ${userId}`;
+      profileEmail = profileInfo.email || null;
+      profileThumb = profileInfo.thumb || null;
+      console.log('[Profile Switch] Using provided profile info:', {
+        plexId: profilePlexId,
+        username: profileUsername,
+      });
+    } else {
+      // Fall back to getUserInfo (for main accounts without profile info)
+      const profileUser = await plexService.getUserInfo(profileToken);
+
+      if (!profileUser || !profileUser.id) {
+        console.error('[Profile Switch] Failed to get profile user info');
+        return NextResponse.json(
+          {
+            error: 'ServerError',
+            message: 'Failed to get profile information',
+          },
+          { status: 500 }
+        );
+      }
+
+      profilePlexId = typeof profileUser.id === 'string' ? profileUser.id : profileUser.id.toString();
+      profileUsername = profileUser.username || `User ${userId}`;
+      profileEmail = profileUser.email || null;
+      profileThumb = profileUser.thumb || null;
+      console.log('[Profile Switch] Using getUserInfo data:', {
+        plexId: profilePlexId,
+        username: profileUsername,
+      });
+    }
+
+    // Check if this is the first user (should be promoted to admin)
+    const userCount = await prisma.user.count();
+    const isFirstUser = userCount === 0;
+    const role = isFirstUser ? 'admin' : 'user';
+
+    // Create or update user with profile details
+    const user = await prisma.user.upsert({
+      where: { plexId: profilePlexId },
+      create: {
+        plexId: profilePlexId,
+        plexUsername: profileUsername,
+        plexEmail: profileEmail,
+        role,
+        avatarUrl: profileThumb,
+        authToken: encryptionService.encrypt(profileToken),
+        plexHomeUserId: userId, // Store the home user ID
+        lastLoginAt: new Date(),
+      },
+      update: {
+        plexUsername: profileUsername,
+        plexEmail: profileEmail,
+        avatarUrl: profileThumb,
+        authToken: encryptionService.encrypt(profileToken),
+        plexHomeUserId: userId, // Update the home user ID
+        lastLoginAt: new Date(),
+      },
+    });
+
+    console.log('[Profile Switch] User authenticated:', {
+      id: user.id,
+      plexId: user.plexId,
+      username: user.plexUsername,
+      homeUserId: user.plexHomeUserId,
+      role: user.role,
+    });
+
+    // Generate JWT tokens
+    const accessToken = generateAccessToken({
+      sub: user.id,
+      plexId: user.plexId,
+      username: user.plexUsername,
+      role: user.role,
+    });
+
+    const refreshToken = generateRefreshToken(user.id);
+
+    // Return tokens and user info
+    return NextResponse.json({
+      success: true,
+      accessToken,
+      refreshToken,
+      user: {
+        id: user.id,
+        plexId: user.plexId,
+        username: user.plexUsername,
+        email: user.plexEmail,
+        role: user.role,
+        avatarUrl: user.avatarUrl,
+      },
+    });
+  } catch (error) {
+    console.error('Failed to switch profile:', error);
+    return NextResponse.json(
+      {
+        error: 'ServerError',
+        message: 'Failed to switch to selected profile',
+        details: error instanceof Error ? error.message : 'Unknown error',
+      },
+      { status: 500 }
+    );
+  }
+}

src/app/api/auth/providers/route.ts

@@ -0,0 +1,49 @@
+/**
+ * List Available Auth Providers
+ * Documentation: documentation/features/audiobookshelf-integration.md
+ */
+
+import { NextResponse } from 'next/server';
+import { ConfigurationService } from '@/lib/services/config.service';
+
+export async function GET() {
+  try {
+    const configService = new ConfigurationService();
+    const backendMode = await configService.get('system.backend_mode');
+
+    if (backendMode === 'audiobookshelf') {
+      // Audiobookshelf mode - check which auth methods are enabled
+      const oidcEnabled = (await configService.get('oidc.enabled')) === 'true';
+      const registrationEnabled = (await configService.get('auth.registration_enabled')) === 'true';
+      const oidcProviderName = await configService.get('oidc.provider_name') || 'SSO';
+
+      const providers: string[] = [];
+      if (oidcEnabled) providers.push('oidc');
+      if (registrationEnabled) providers.push('local');
+
+      return NextResponse.json({
+        backendMode: 'audiobookshelf',
+        providers,
+        registrationEnabled,
+        oidcProviderName: oidcEnabled ? oidcProviderName : null,
+      });
+    } else {
+      // Plex mode
+      return NextResponse.json({
+        backendMode: 'plex',
+        providers: ['plex'],
+        registrationEnabled: false,
+        oidcProviderName: null,
+      });
+    }
+  } catch (error) {
+    console.error('[Auth] Failed to fetch auth providers:', error);
+    // Default to Plex mode if config can't be read
+    return NextResponse.json({
+      backendMode: 'plex',
+      providers: ['plex'],
+      registrationEnabled: false,
+      oidcProviderName: null,
+    });
+  }
+}

src/app/api/auth/refresh/route.ts

@@ -0,0 +1,80 @@
+/**
+ * Component: Token Refresh Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { verifyRefreshToken, generateAccessToken } from '@/lib/utils/jwt';
+import { prisma } from '@/lib/db';
+
+/**
+ * POST /api/auth/refresh
+ * Refresh access token using refresh token
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const { refreshToken } = body;
+
+    if (!refreshToken) {
+      return NextResponse.json(
+        {
+          error: 'ValidationError',
+          message: 'Refresh token is required',
+        },
+        { status: 400 }
+      );
+    }
+
+    // Verify refresh token
+    const payload = verifyRefreshToken(refreshToken);
+
+    if (!payload) {
+      return NextResponse.json(
+        {
+          error: 'Unauthorized',
+          message: 'Invalid or expired refresh token',
+        },
+        { status: 401 }
+      );
+    }
+
+    // Get user from database
+    const user = await prisma.user.findUnique({
+      where: { id: payload.sub },
+    });
+
+    if (!user) {
+      return NextResponse.json(
+        {
+          error: 'Unauthorized',
+          message: 'User not found',
+        },
+        { status: 401 }
+      );
+    }
+
+    // Generate new access token
+    const accessToken = generateAccessToken({
+      sub: user.id,
+      plexId: user.plexId,
+      username: user.plexUsername,
+      role: user.role,
+    });
+
+    return NextResponse.json({
+      success: true,
+      accessToken,
+      expiresIn: 3600, // 1 hour in seconds
+    });
+  } catch (error) {
+    console.error('Failed to refresh token:', error);
+    return NextResponse.json(
+      {
+        error: 'RefreshError',
+        message: 'Failed to refresh access token',
+      },
+      { status: 500 }
+    );
+  }
+}

src/app/api/auth/register/route.ts

@@ -0,0 +1,75 @@
+/**
+ * User Registration Endpoint
+ * Documentation: documentation/features/audiobookshelf-integration.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { LocalAuthProvider } from '@/lib/services/auth/LocalAuthProvider';
+
+// Rate limiting map (in production, use Redis)
+const registrationAttempts = new Map<string, { count: number; resetAt: number }>();
+const MAX_ATTEMPTS = 5;
+const WINDOW_MS = 60 * 60 * 1000; // 1 hour
+
+function checkRateLimit(ip: string): boolean {
+  const now = Date.now();
+  const attempts = registrationAttempts.get(ip);
+
+  if (!attempts || now > attempts.resetAt) {
+    registrationAttempts.set(ip, { count: 1, resetAt: now + WINDOW_MS });
+    return true;
+  }
+
+  if (attempts.count >= MAX_ATTEMPTS) {
+    return false;
+  }
+
+  attempts.count++;
+  return true;
+}
+
+export async function POST(request: NextRequest) {
+  // Rate limiting
+  const ip = request.headers.get('x-forwarded-for') || 'unknown';
+  if (!checkRateLimit(ip)) {
+    return NextResponse.json(
+      { error: 'Too many registration attempts. Please try again later.' },
+      { status: 429 }
+    );
+  }
+
+  try {
+    const { username, password } = await request.json();
+
+    const provider = new LocalAuthProvider();
+    const result = await provider.register({ username, password });
+
+    if (!result.success) {
+      if (result.requiresApproval) {
+        return NextResponse.json({
+          success: false,
+          pendingApproval: true,
+          message: 'Account created. Waiting for admin approval.',
+        });
+      }
+      return NextResponse.json(
+        { error: result.error },
+        { status: 400 }
+      );
+    }
+
+    // Return tokens for auto-login
+    return NextResponse.json({
+      success: true,
+      user: result.user,
+      accessToken: result.tokens!.accessToken,
+      refreshToken: result.tokens!.refreshToken,
+    });
+  } catch (error) {
+    console.error('[Registration] Error:', error);
+    return NextResponse.json(
+      { error: 'Registration failed' },
+      { status: 500 }
+    );
+  }
+}