Authentication API (/api/auth)

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/auth/route.ts
• app/login/page.tsx
• middleware.ts
• lib/auth.ts
• README.md

The Authentication API in the GeNCorE project provides a lightweight, secure mechanism for managing administrative sessions. Its primary purpose is to gate access to the Command Center dashboard and sensitive operations, such as task creation and pull request management. The system relies on a single ADMIN_TOKEN environment variable to authenticate users and maintains sessions via secure, HTTP-only cookies.

The architecture emphasizes security through the use of HMAC-SHA256 hashing, ensuring that the raw ADMIN_TOKEN is never stored on the client side or transmitted back to the server in plain text after the initial login. Global route protection is handled by a Next.js middleware that validates these hashes against the server-side secret.

Sources: README.md:95-103, middleware.ts:1-5

API Endpoints

The authentication system is exposed via a single route handler supporting POST and DELETE methods for session lifecycle management.

POST /api/auth

Used to authenticate a user and establish a session. The endpoint compares the provided token with the environment variable using a timing-safe comparison to prevent side-channel attacks.

• Request Body: { "token": string }
• Success Response: Sets an auth cookie containing a HMAC-SHA256 hash of the ADMIN_TOKEN.

DELETE /api/auth

Used to terminate the current session.

• Action: Clears the auth cookie from the client.

Sources: app/api/auth/route.ts:7-40, README.md:27

Security Implementation

The system implements several layers of security to protect the administrative panel:

Feature	Description	Implementation Detail
Hash Protection	Raw tokens are never stored in cookies.	HMAC-SHA256(ADMIN_TOKEN, 'gencore:session:v1')
Timing Attack Resistance	Prevents measuring string comparison time.	timingSafeEqual function
Session Persistence	Sessions are valid for 7 days.	maxAge: 60 * 60 * 24 * 7
Middleware Guard	Global protection for /api and dashboard routes.	Next.js Middleware
Transport Security	Cookies are flagged as Secure in production.	secure: process.env.NODE_ENV === 'production'

Sources: lib/auth.ts:14-34, app/api/auth/route.ts:28-35, middleware.ts:50-60, README.md:95-100

Authentication Flow

The following sequence diagram illustrates the process from user login to subsequent authenticated requests.

The diagram shows how the ADMIN_TOKEN is verified and transformed into a secure HMAC hash for session persistence.
Sources: app/login/page.tsx:16-30, app/api/auth/route.ts:22-38, middleware.ts:50-60

Internal Logic and Cryptography

The system utilizes the Web Crypto API (crypto.subtle) for cryptographic operations, ensuring compatibility across Node.js and Edge runtimes.

Hashing Mechanism

The hashAdminToken function generates a signature using a fixed payload (gencore:session:v1) and the ADMIN_TOKEN as the key. This ensures that even if a cookie is intercepted, the raw token remains unknown.

// Sources: lib/auth.ts:14-26
export async function hashAdminToken(adminToken: string): Promise<string> {
  const enc = new TextEncoder()
  const key = await crypto.subtle.importKey(
    'raw',
    enc.encode(adminToken),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  )
  const sig = await crypto.subtle.sign('HMAC', key, enc.encode('gencore:session:v1'))
  return Array.from(new Uint8Array(sig))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('')
}

Sources: lib/auth.ts:14-26

Middleware Verification

The middleware acts as a gatekeeper. It caches the expected hash of the ADMIN_TOKEN in memory to avoid repeated cryptographic operations on every request. If the auth cookie does not match the cached hash, users are redirected to /login or receive a 401 Unauthorized response for API calls.

This flowchart describes the logic used in the middleware to determine if a request should be authorized.
Sources: middleware.ts:23-60

Summary

The Authentication API provides a robust security layer for the GeNCorE Command Center by leveraging standard cryptographic practices and Next.js Middleware. By abstracting the ADMIN_TOKEN into HMAC hashes and enforcing timing-safe comparisons, the project ensures that administrative access is strictly controlled without requiring a complex database-backed session store.
Sources: README.md:95-103, middleware.ts:1-5