Security Architecture

Relevant source files

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

• README.md
• lib/auth.ts
• middleware.ts
• app/api/auth/route.ts
• app/api/review/route.ts
• app/api/merge/route.ts
• app/api/task/route.ts

Introduction

The security architecture of GeNCorE Command Center is designed to provide a secure, authenticated interface for managing AI agents and GitHub repository workflows. The system follows a server-side gatekeeper pattern where sensitive credentials like the GITHUB_TOKEN are strictly confined to the server environment, never reaching the client-side application.

The architecture centers around a custom authentication layer using HMAC-SHA256 hashing for session validation, a global middleware for route protection, and rigorous input validation to prevent common web vulnerabilities such as Server-Side Request Forgery (SSRF) and timing attacks.

Authentication and Session Management

The system implements a password-less authentication flow based on a pre-configured ADMIN_TOKEN. Access is managed through a secure cookie-based session that stores a cryptographic hash rather than raw credentials.

Secure Token Hashing

To prevent the exposure of the raw ADMIN_TOKEN in the user's browser, the application uses the Web Crypto API to generate an HMAC-SHA256 signature. This signature is derived from the ADMIN_TOKEN and a static payload (gencore:session:v1).

Sources: lib/auth.ts:1-26, README.md:100-101

Timing Attack Prevention

The timingSafeEqual function is utilized during token verification. This function performs a constant-time comparison of strings by XORing character codes, ensuring that the time taken to validate a token does not leak information about its content.

Sources: lib/auth.ts:33-41

Authentication Flow

When a user logs in, the ADMIN_TOKEN is verified. Upon success, an auth cookie is set containing the HMAC hash. This cookie is configured with httpOnly, secure (in production), and sameSite: 'lax' attributes to mitigate XSS and CSRF risks.

Middleware Protection Layer

A global Next.js middleware acts as a centralized security gatekeeper. It intercepts all incoming requests (except for static assets and public login routes) to verify the session.

• Unauthorized Access: Requests without a valid auth cookie are redirected to /login for HTML pages or receive a 401 Unauthorized JSON response for API routes.
• Fail-Safe Mechanism: In production environments, if the ADMIN_TOKEN environment variable is missing, the middleware returns a 500 Internal Server Error to prevent the dashboard from defaulting to a public, unprotected state.

API Security and Data Validation

The application interacts with the GitHub REST API using a GITHUB_TOKEN. This token is stored exclusively in environment variables and is never exposed to the frontend.

Input Sanitization and SSRF Protection

All API routes that accept numeric identifiers (like Pull Request numbers) implement strict validation. For example, in the /api/review and /api/merge routes, the prNumber is:

1. Converted to a number.
2. Validated as an integer.
3. Checked against a maximum safe integer limit (2,147,483,647).
4. Checked to be greater than zero.

This prevents attackers from injecting malicious paths or exploiting SSRF vulnerabilities by manipulating the GitHub API URL construction.

Sources: app/api/review/route.ts:32-36, app/api/merge/route.ts:28-32, README.md:105

Validation Logic Table

Endpoint	Logic	Security Measure
/api/task	Validates agent ID against AGENT_IDS constant	Prevents injection of unknown agents
/api/review	Validates event against APPROVE, REQUEST_CHANGES, COMMENT	Ensures only valid GitHub actions are taken
/api/merge	Validates mergeMethod against merge, squash, rebase	Restricts merge operations to allowed types
/api/chat	Validates Anthropic API key prefix (sk-ant-)	Basic credential format verification

Sources: app/api/task/route.ts:34-40, app/api/review/route.ts:38-42, app/api/merge/route.ts:34-38, app/api/chat/route.ts:28-33

Environment Configuration

The security of the system relies on four primary environment variables. These must be managed through secure provider settings (e.g., Vercel Environment Variables) and are not checked into source control.

Variable	Scope	Purpose
GITHUB_TOKEN	Server-only	Used for GitHub API authentication (Repo scope required)
ADMIN_TOKEN	Server-only	The primary secret used to authenticate users and sign cookies
NEXT_PUBLIC_REPO_OWNER	Client/Server	The GitHub organization or username owning the target repo
NEXT_PUBLIC_REPO_NAME	Client/Server	The name of the repository managed by the panel

Sources: README.md:46-56, app/api/task/route.ts:4-6

Summary

The GeNCorE security architecture prioritizes the protection of sensitive GitHub credentials and the integrity of the command center's access control. By combining cryptographic session signing, constant-time comparisons, and strict server-side validation of all user-provided inputs, the system mitigates common attack vectors while maintaining a streamlined management interface for AI-driven development workflows.