DeepSeek-Reasonix HTTP Serve Frontend Authentication Modes: none, token, or password

The HTTP serve frontend in DeepSeek-Reasonix supports three authentication configurations—none for unrestricted access, token for Bearer token verification via the Authorization header, and password for session-based email and password login—controlled via the FRONTEND_AUTH_MODE environment variable.

The esengine/DeepSeek-Reasonix repository provides an HTTP serve frontend that powers the Reasonix dashboard web interface. Selecting the appropriate authentication mode is critical for securing your deployment, whether you are running local tests, automated CI pipelines, or production user-facing instances.

Overview of the Three Authentication Modes

The authentication strategy is determined at startup by reading environment variables, typically defined in workers/crash-report/src/env.ts. The system supports three distinct modes, each suited for different operational contexts.

Mode 1: none (Open Access)

When FRONTEND_AUTH_MODE is set to none, the server disables all authentication checks. The requireAuth middleware is omitted from the request pipeline, allowing unrestricted access to routes defined in workers/crash-report/src/registry/routes/packages.ts and workers/crash-report/src/registry/routes/admin.ts. This mode is intended strictly for local development or isolated networks where security is handled at the infrastructure level.

Mode 2: token (Bearer Token)

In token mode, the requireAuth middleware defined in workers/crash-report/src/registry/http/auth.ts intercepts incoming requests and validates a Bearer token provided in the Authorization HTTP header. The middleware extracts the token and forwards it to the accounts service for verification. This mode is ideal for programmatic access from CLI tools or external services that cannot maintain browser sessions.

Mode 3: password (Session-Based)

The password mode enables traditional user authentication via email and password credentials. The accounts service (workers/accounts/src/routes/auth.ts) handles credential verification and issues a secure, HTTP-only session cookie (session_token). Subsequent requests automatically include this cookie, which the requireAuth middleware validates against the accounts service. This is the standard configuration for human users accessing the dashboard through a browser.

Configuration and Environment Setup

The deployment environment determines which authentication layer is active. The server reads configuration variables at startup to wire the appropriate middleware.

Environment Variable

The primary configuration knob is FRONTEND_AUTH_MODE, which accepts the string values none, token, or password. This variable is typically parsed alongside other environment constants in workers/crash-report/src/env.ts.

// Conceptual configuration from workers/crash-report/src/env.ts
export const FRONTEND_AUTH_MODE = process.env.FRONTEND_AUTH_MODE || "password";

Middleware Registration

Based on the configured mode, the application conditionally applies the authentication layer. In none mode, the middleware is skipped entirely. For token and password modes, the requireAuth middleware is mounted on protected routes.

Implementation Details by Mode

Each authentication mode relies on specific source files to enforce its security model.

None Mode Implementation

When authentication is disabled, routes bypass the requireAuth function entirely. This eliminates any calls to the accounts service for identity verification, reducing latency but removing security boundaries.

Token Mode Implementation

In workers/crash-report/src/registry/http/auth.ts, the token validation logic extracts the Authorization header and expects a Bearer token format:

// Implementation concept from workers/crash-report/src/registry/http/auth.ts
const requireAuth = async (c, next) => {
  const authHeader = c.req.header("authorization");
  const token = authHeader?.replace("Bearer ", "");
  
  // Token forwarded to accounts service for verification
  const user = await verifyTokenWithAccountsService(token);
  if (!user) return c.json({ error: "Unauthorized" }, 401);
  
  c.set("user", user);
  await next();
};

Password Mode Implementation

Password authentication leverages the accounts worker. The login endpoint in workers/accounts/src/routes/auth.ts accepts credentials, validates them against hashed passwords, and sets the session cookie:

// Login route concept from workers/accounts/src/routes/auth.ts
app.post("/auth/login", async (c) => {
  const { email, password } = await c.req.json();
  const user = await validateCredentials(email, password);
  if (!user) return c.json({ error: "Invalid credentials" }, 401);
  
  const sessionToken = await createSession(user.id);
  setCookie(c, "session_token", sessionToken, { 
    httpOnly: true, 
    secure: true,
    sameSite: "strict"
  });
  return c.json({ success: true });
});

The requireAuth middleware then reads this cookie on subsequent requests to identify the user.

Practical Code Examples

Configuring the Authentication Mode

Set the environment variable before starting the server:

# Run with no authentication (development only)

FRONTEND_AUTH_MODE=none npm run serve

# Run with token-based authentication

FRONTEND_AUTH_MODE=token npm run serve

# Run with password authentication (default)

FRONTEND_AUTH_MODE=password npm run serve

Making Requests with Token Authentication

When using token mode, include the Bearer token in your API requests:

// Accessing protected packages with token auth
const response = await fetch("https://reasonix.internal/api/v1/packages", {
  method: "GET",
  headers: {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
});

if (response.status === 401) {
  console.error("Invalid or missing token");
}

Authenticating with Password Mode

For browser-based or scripted password authentication:

// Step 1: Log in to obtain session cookie
const loginRes = await fetch("https://id.reasonix.io/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "user@example.com",
    password: "secure-password-123"
  }),
  credentials: "include" // Important for cookie handling
});

if (loginRes.ok) {
  // Step 2: Access protected resources (cookie sent automatically)
  const data = await fetch("https://reasonix.internal/api/v1/packages", {
    credentials: "include"
  });
}

Summary

• Three modes available: none (disabled), token (Bearer header), and password (session cookie).
• Configuration: Controlled by the FRONTEND_AUTH_MODE environment variable defined in workers/crash-report/src/env.ts.
• Token implementation: workers/crash-report/src/registry/http/auth.ts validates Bearer tokens against the accounts service.
• Password implementation: workers/accounts/src/routes/auth.ts handles credential verification and session creation.
• Production guidance: Use none only for local testing, token for service-to-service communication, and password for end-user dashboard access.

Frequently Asked Questions

What happens if I set FRONTEND_AUTH_MODE to none?

When set to none, the application skips the requireAuth middleware entirely, allowing all requests to access protected routes in workers/crash-report/src/registry/routes/packages.ts and workers/crash-report/src/registry/routes/admin.ts without verifying identity. This should only be used in isolated development environments.

How do I obtain a Bearer token for token mode?

Tokens are typically generated through the accounts service or provided via your deployment infrastructure. The requireAuth middleware in workers/crash-report/src/registry/http/auth.ts expects the token in the Authorization: Bearer <token> header format and forwards it to the accounts service for validation.

Is the password mode suitable for API clients?

Password mode is optimized for browser-based sessions using HTTP-only cookies. API clients should use token mode instead, as the session cookie mechanism requires cookie jar support and is designed for interactive user sessions rather than programmatic access.

Where is the session cookie validated?

The session cookie is validated by the requireAuth middleware in workers/crash-report/src/registry/http/auth.ts, which extracts the session_token cookie and verifies it against the accounts service. The actual cookie creation occurs in workers/accounts/src/routes/auth.ts during the login process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}