Session Management & Middleware

Relevant source files

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

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

The session management system in GeNCorE Command Center provides a secure, cookie-based authentication layer to protect the dashboard and its administrative API endpoints. It ensures that only authorized users can interact with AI agent configurations and GitHub repository actions.

The architecture relies on a central ADMIN_TOKEN defined in environment variables. Instead of storing this raw token in the browser, the system uses HMAC-SHA256 hashing to generate a session identifier stored in a secure cookie. A Next.js Middleware component intercepts incoming requests to validate this session before granting access to protected routes.

Sources: README.md:120-128, middleware.ts:1-5

Authentication Flow

The authentication process involves validating a user-provided token against the server-side ADMIN_TOKEN. Upon successful validation, a hashed version of the token is stored in an auth cookie for subsequent requests.

The diagram above illustrates the sequence from the initial login attempt to the setting of a secure session cookie.
Sources: app/api/auth/route.ts:7-35, lib/auth.ts:15-28

Key Authentication Components

Component	Function	Implementation
hashAdminToken	Generates a persistent session hash	Uses Web Crypto API (HMAC-SHA256)
timingSafeEqual	Compares tokens securely	Constant-time string comparison
ADMIN_TOKEN	Master password	Environment variable
auth Cookie	Client-side session storage	httpOnly, secure (prod), 7-day expiry

Sources: lib/auth.ts:1-38, app/api/auth/route.ts:32-38

Middleware Enforcement

The system utilizes a Next.js Middleware to protect the application globally. It acts as a gatekeeper for both UI routes and API endpoints, except for a defined set of public paths.

The flowchart demonstrates the logic applied by the middleware to determine if a request should be processed, redirected, or blocked.
Sources: middleware.ts:21-60

Route Protection Logic

The middleware classifies paths into two categories:

1. Public Paths: Includes static assets (/_next, favicon), and the authentication routes (/login, /api/auth).
2. Protected Paths: All other routes including the Dashboard (/), Task Panel (/task), and Review Panel (/review).

If the ADMIN_TOKEN is missing in a production environment, the middleware purposefully fails with a 500 status to prevent accidental public exposure of the panel.
Sources: middleware.ts:7-10, middleware.ts:35-49

Security Implementation Details

Token Hashing

To prevent the exposure of the raw ADMIN_TOKEN, the system generates a HMAC-SHA256 signature using the string gencore:session:v1 as the payload. This ensures that the value stored in the user's browser cannot be reversed to find the original secret.

const PAYLOAD = 'gencore:session:v1'

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(PAYLOAD))
  return Array.from(new Uint8Array(sig))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('')
}

Sources: lib/auth.ts:9-28

Protection Against Timing Attacks

The timingSafeEqual function is used during token validation. It iterates through the entire length of the strings regardless of where a mismatch is found, preventing attackers from deducing token characters based on server response times.
Sources: lib/auth.ts:34-42

Session Termination

Sessions are terminated by making a DELETE request to /api/auth, which instructs the browser to clear the auth cookie.
Sources: app/api/auth/route.ts:43-47

Summary

Session Management in GeNCorE is a robust, server-side-driven architecture. By leveraging Next.js Middleware and the Web Crypto API, it ensures that administrative capabilities are restricted to users possessing the ADMIN_TOKEN, while maintaining high security standards through HMAC hashing and timing-attack mitigation.