Authentication and Security

Relevant source files

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

• src/middleware/auth.ts
• SECURITY.md
• src/server.ts
• src/index.ts
• src/utils/validation.ts
• src/handlers/admin.ts
• README.md
• src/admin-html.ts

Gr8hopper's security model is designed to be simple yet robust, focusing on protecting the administrative interface and ensuring the integrity of redirect data. The core of the security architecture is HTTP Basic Authentication for all administrative endpoints, enforced by a dedicated middleware. This is complemented by strict input validation, secure configuration practices, and protection against common web vulnerabilities.

The system is stateless regarding user data, storing only redirect configurations. Security relies on a combination of application-level controls (authentication, validation), infrastructure-level recommendations (HTTPS, rate limiting), and secure coding practices (timing-attack resistance, scheme validation).

Authentication

Authentication in gr8hopper is handled exclusively for the admin panel and its associated API endpoints. The public-facing redirect functionality is unauthenticated.

Mechanism: HTTP Basic Authentication

The application uses HTTP Basic Authentication to protect all routes under the configurable admin path (default /admin). This requires a username and password to be sent in the Authorization header of every request to the admin panel.

The basicAuth middleware is applied to all admin routes in both the Node.js and Cloudflare Workers entry points.

• Node.js (server.ts):

  // src/server.ts:147-150
  app.use(`/${ADMIN_PATH}`, cors())
  app.use(`/${ADMIN_PATH}/*`, cors())
  app.use(`/${ADMIN_PATH}`, basicAuth(authConfig))
  app.use(`/${ADMIN_PATH}/*`, basicAuth(authConfig))
  

• Cloudflare Workers (index.ts):

  // src/index.ts:68-72
  const authMiddleware = basicAuth(authConfig!)
  const authResult = await authMiddleware(c, async () => { })
  if (authResult) return authResult // Return 401 if auth failed
  

Sources: src/server.ts:147-150, src/index.ts:68-72, SECURITY.md

Authentication Flow

The following diagram illustrates the sequence of events when a user attempts to access an admin endpoint.

This diagram shows the authentication process within the basicAuth middleware.
Sources: src/middleware/auth.ts:40-75

Timing Attack Prevention

To prevent timing attacks where an attacker could discern valid credentials by measuring server response times, gr8hopper uses a constant-time string comparison function, timingSafeEqual. This function ensures that comparing credentials takes the same amount of time regardless of whether the input matches or not.

It achieves this by:

1. Comparing the length of the strings using bitwise XOR to avoid early exit.
2. Padding both strings to the same length.
3. Iterating through the full length of the padded strings and using bitwise XOR on each byte.

The final result is 0 only if the lengths and all characters were identical.

Sources: src/middleware/auth.ts:8-32, SECURITY.md

Configuration

Authentication credentials and the admin path are configured via environment variables. These are mandatory for running the application.

Variable	Description	Platform
ADMIN_USERNAME	The username for the admin panel. Required. Cannot be 'admin'.	Both
ADMIN_PASSWORD	The password for the admin panel. Required.	Both
ADMIN_PATH	The URL path for the admin panel. Defaults to admin.	Both

The server performs startup checks to ensure these variables are set, exiting with a fatal error if they are missing. It also explicitly rejects admin as a username to discourage weak, guessable credentials.

Sources: src/server.ts:81-133, README.md, SECURITY.md

Server Startup Security Checks

This flowchart shows the mandatory security checks performed when the Node.js server starts.
Sources: src/server.ts:81-133

Logout

The admin panel provides a "Log out" button. This feature works by sending a new request to an authenticated endpoint with invalid credentials (logout:logout). This invalidates the browser's cached Basic Auth credentials, forcing it to prompt for a new login on the next visit.

Sources: src/admin-html.ts:1119-1130

Input Validation and Sanitization

Gr8hopper employs strict validation and sanitization on all user-configurable data, particularly route IDs and destination URLs, to prevent injection attacks and ensure system stability.

URL and Scheme Validation

All destination template URLs and fallback_url settings are validated to prevent malicious schemes.

The isValidUrlScheme function performs the following checks:

1. Removes control characters (e.g., \n, \r, null bytes) to prevent CRLF/HTTP Header Injection.
2. Enforces a maximum URL length of 2048 characters.
3. Blocks a list of dangerous schemes.
4. Blocks protocol-relative URLs (e.g., //example.com).
5. Ensures that if a full URL is provided, it uses an allowed scheme (http: or https:).

Blocked Schemes
javascript:
data:
vbscript:
file:
about:
blob:
filesystem:

Sources: src/utils/validation.ts:13-22, 91-131, SECURITY.md

URL Validation Logic

This diagram outlines the steps taken to validate a URL template.
Sources: src/utils/validation.ts:91-131

Route ID Sanitization and Validation

Route IDs, which can be simple strings or complex patterns, undergo sanitization and validation to ensure they are safe and well-formed.

• Sanitization: The sanitizeRouteId function converts the ID to lowercase and allows a specific set of characters: a-z, 0-9, and pattern characters (/, {, }, *, ., :, ?, &, =, -). Backslashes are stripped to prevent escape injection.
• Validation: The validateRouteIdPattern function checks for syntactical correctness, such as balanced braces ({}), non-empty parameter names, and well-formed query string specifications.

These measures, combined with backtracking limits in the pattern matcher, help protect against Regular Expression Denial of Service (ReDoS) attacks.

Sources: src/handlers/admin.ts:47-64, src/utils/validation.ts:29-89, SECURITY.md

Deployment and Operational Security

The project documentation provides several recommendations for securing a production deployment.

HTTPS Enforcement

It is critical to deploy gr8hopper behind HTTPS. HTTP Basic Auth sends credentials in a simple Base64 encoding, which is easily intercepted over an unencrypted HTTP connection. Cloudflare deployments enforce HTTPS by default; for VPS deployments, an Nginx reverse proxy with SSL is recommended.

Sources: SECURITY.md, README.md

Rate Limiting

To protect the admin panel against brute-force login attempts, rate limiting is strongly recommended.

• Cloudflare: Use WAF Rate Limiting Rules to block IPs that make excessive requests to the admin path (e.g., /admin).
• VPS (Nginx): Use the limit_req_zone directive to apply rate limits to the location block proxying to the admin path.

Sources: README.md, SECURITY.md

Security Headers

For VPS deployments, adding security headers via a reverse proxy like Nginx enhances protection against attacks like clickjacking and cross-site scripting.

Header	Recommended Value	Purpose
Strict-Transport-Security	max-age=31536000; includeSubDomains	Enforces HTTPS connections.
X-Frame-Options	DENY	Prevents the site from being embedded in an <iframe>.
X-Content-Type-Options	nosniff	Prevents MIME-type sniffing.
Referrer-Policy	no-referrer	Prevents sending the referrer header.

Sources: SECURITY.md

Cache Purge Security

The feature to purge the Cloudflare CDN cache is protected. It is only enabled if the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID environment variables are set. The API token is a secret used to authenticate with the Cloudflare API.

The /admin/purge-cache/status endpoint checks for the presence of these variables to determine if the feature is available, and the /admin/purge-cache endpoint uses them to make the authenticated API call to Cloudflare.

Sources: src/handlers/admin.ts:316-347, src/index.ts:51-54

Summary

Gr8hopper's security posture is built on a layered defense strategy. It begins with mandatory, strong authentication for all administrative functions, protected against timing attacks. This is reinforced by rigorous input validation that blocks dangerous URL schemes and malformed route patterns. Finally, the documentation provides clear guidance on essential operational security practices, such as enforcing HTTPS, implementing rate limiting, and applying security headers, ensuring that the application can be deployed and managed securely in a production environment.