DeepWiki

06.a - Admin-Authentication

Relevant source files

This document describes the password-based authentication system that protects the admin panel at /admin. The admin panel allows the owner to generate installation access tokens for customer repositories. This page covers the authentication mechanism, session persistence using localStorage, and the security implications of the implementation.

For details on what the admin panel does after authentication, see Installation Token Generation API. For the complete manual workflow involving admin access, see Manual Repository Access Workflow.

The admin authentication system uses a simple password-based model with client-side session persistence. Unlike the user OAuth flow (see GitHub OAuth Initiation), admin authentication does not involve GitHub or any external identity provider.

Sources: app/admin/page.tsx L1-L137

app/admin/actions.ts L1-L9

The password verification uses a server action to prevent exposing the password comparison logic to the client.

The verifyPassword function is a server action that performs a direct string comparison:

AspectImplementation
Locationapp/admin/actions.ts L3-L8
Function Signatureasync function verifyPassword(password: string)
Environment VariableADMIN_PASSWORD (server-side only)
Comparison MethodDirect string equality (password === process.env.ADMIN_PASSWORD)
Return Valuetrue if match, false otherwise

The function deliberately checks process.env.ADMIN_PASSWORD (not NEXT_PUBLIC_ADMIN_PASSWORD) to ensure the password value is only accessible server-side. However, note the security consideration below regarding the public environment variable.

Sources: app/admin/actions.ts L3-L8

The admin page maintains authentication state using React component state and localStorage.

Sources: app/admin/page.tsx L13-L28

The authentication state persists across page reloads using the browser's localStorage API:

OperationCode LocationKeyValue
Check on mountapp/admin/page.tsx L31-L36admin_authenticated"true" or null
Set on loginapp/admin/page.tsx L43admin_authenticated"true"
Remove on logoutapp/admin/page.tsx L52admin_authenticateddeleted

The useEffect hook checks localStorage when the component mounts:

useEffect(() => {  const authState = localStorage.getItem("admin_authenticated")  if (authState === "true") {    setIsAuthenticated(true)  }}, [])

This allows the admin to remain authenticated across page refreshes and browser sessions (until they explicitly log out or clear browser data).

Sources: app/admin/page.tsx L30-L36

The login process follows a client-side form submission pattern with server-side verification.

Sources: app/admin/page.tsx L38-L48

app/admin/actions.ts L3-L8

The login form appears when isAuthenticated is false:

ComponentPurposeLocation
CardContainer with centered layoutapp/admin/page.tsx L103
Lock iconVisual authentication indicatorapp/admin/page.tsx L106
Input (type="password")Password entry fieldapp/admin/page.tsx L115-L122
Alert (variant="destructive")Error message displayapp/admin/page.tsx L124-L128
Button (type="submit")Form submission triggerapp/admin/page.tsx L129-L131

The form submission handler at app/admin/page.tsx L38-L48

orchestrates the verification:

  1. Prevents default form submission
  2. Calls verifyPassword(password) server action
  3. Updates state based on response
  4. Persists authentication to localStorage if valid
  5. Displays error message if invalid

Sources: app/admin/page.tsx L100-L137

The logout mechanism clears both component state and localStorage.

The handleLogout function at app/admin/page.tsx L50-L55

performs three operations:

const handleLogout = () => {  setIsAuthenticated(false)  localStorage.removeItem("admin_authenticated")  setTokenData(null)  setInstallationId("")}
ActionPurpose
setIsAuthenticated(false)Trigger UI re-render to show login form
localStorage.removeItem("admin_authenticated")Clear persisted session
setTokenData(null)Clear any generated token data
setInstallationId("")Reset installation ID input

The logout button is visible in the admin panel header at app/admin/page.tsx L146-L149

:

<Button variant="outline" onClick={handleLogout}>  <LogOut className="mr-2 h-4 w-4" />  Logout</Button>

Sources: app/admin/page.tsx L50-L55

app/admin/page.tsx L146-L149

The admin authentication implementation has several notable security characteristics and trade-offs.

The system uses two environment variables related to admin password:

VariableVisibilityPurposeSecurity Impact
ADMIN_PASSWORDServer-side onlyUsed for verification in verifyPassword()✅ Secure - not exposed to client
NEXT_PUBLIC_ADMIN_PASSWORDClient-accessibleReferenced in .env.example L8⚠️ Security concern if populated

Critical Security Note: The .env.example file shows NEXT_PUBLIC_ADMIN_PASSWORD as a configuration option. Any environment variable prefixed with NEXT_PUBLIC_ is bundled into the client JavaScript and accessible via browser DevTools. This means if this variable is set, the admin password becomes publicly visible.

The actual verification logic uses process.env.ADMIN_PASSWORD (without the NEXT_PUBLIC_ prefix), which is the correct approach. The presence of NEXT_PUBLIC_ADMIN_PASSWORD in the environment configuration suggests it may be used elsewhere in the codebase (potentially for automation scripts that need the password) but should never contain the actual admin password.

Sources: .env.example L8

app/admin/actions.ts L4

Sources: app/admin/page.tsx L38-L48

app/admin/actions.ts L3-L8

VulnerabilityDescriptionMitigation Status
Brute-force attacksNo rate limiting or account lockout mechanism. Attacker can attempt unlimited passwords.❌ Not mitigated
Session hijackinglocalStorage accessible to any JavaScript. If XSS vulnerability exists elsewhere, session can be stolen.⚠️ Partially mitigated by HTTP-only cookie pattern elsewhere (but not used here)
Session persistenceSession never expires. Once authenticated, remains authenticated until explicit logout or browser data clear.❌ Not mitigated
Password exposureIf NEXT_PUBLIC_ADMIN_PASSWORD is set, password becomes public.⚠️ Depends on deployment configuration
CSRF attacksNo CSRF token validation on admin actions. However, server actions in Next.js 14 have built-in CSRF protection.✅ Mitigated by framework

Sources: app/admin/page.tsx L31-L48

app/admin/actions.ts L3-L8

For a production system, consider implementing:

  1. Rate limiting: Add rate limiting on login attempts (e.g., 5 attempts per 15 minutes)
  2. Session expiration: Implement token-based sessions with expiration (e.g., 1-hour timeout)
  3. IP whitelisting: Restrict admin panel access to known IP addresses
  4. Audit logging: Log all authentication attempts with timestamps and IP addresses
  5. HTTP-only cookies: Move session persistence from localStorage to HTTP-only cookies
  6. Password hashing: Hash the password in environment variables and use bcrypt for comparison
  7. Remove public password variable: Ensure NEXT_PUBLIC_ADMIN_PASSWORD is never populated or remove it entirely

Design Trade-off: The simple authentication model is intentional for a low-volume, single-operator system. The documentation in CLAUDE.md acknowledges this is not enterprise-grade security. For the current use case (manual repository processing with 1-9 hour turnaround), the risk is deemed acceptable.

Sources: app/admin/page.tsx L1-L363

app/admin/actions.ts L1-L9

.env.example L8

Once authenticated, the admin interface allows generating installation access tokens. The password is re-sent with each token generation request:

const response = await fetch("/api/admin/generate-token", {  method: "POST",  headers: { "Content-Type": "application/json" },  body: JSON.stringify({    installationId,    password: password // Password sent with API request  }),})

This pattern provides defense-in-depth: even if an attacker bypasses the client-side authentication check (e.g., by manipulating localStorage), they still cannot call the token generation API without the actual password. The API endpoint re-verifies the password server-side before generating tokens.

For details on the token generation API and its authentication, see Installation Token Generation API.

Sources: app/admin/page.tsx L64-L71

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

Syntax error in text

mermaid version 11.4.1

06.a - Admin-Authentication | DeepWiki | godeep.wiki