How the Reasonix Web Frontend Serve Command Handles Authentication

The reasonix serve command implements an optional authentication layer via the authGate struct in internal/serve/auth.go, supporting three modes—none, token-based, and password-based—controlled by CLI flags or TOML configuration.

The reasonix serve command in the DeepSeek-Reasonix repository launches an HTTP server that exposes the Reasonix controller through a browser-based interface. According to the source code, authentication is wired into the server during initialization as an optional middleware layer that validates requests before they reach core application handlers.

Authentication Architecture

In internal/serve/serve.go, the Server struct contains an optional auth field of type *authGate:

type Server struct {
    // ...
    auth *authGate  // nil when authentication is disabled
}

The New function initializes this field by calling newAuthGate(serveCfg), which reads the ServeConfig populated from CLI flags (--auth token, --auth password, --auth none) or the reasonix.example.toml configuration file. This design keeps the transport layer agnostic while allowing security to be toggled per deployment.

Authentication Modes Explained

The authGate implementation in internal/serve/auth.go supports three distinct modes that determine how the middleware validates incoming requests.

None (Disabled)

When auth_mode is set to none (the default for local development), the auth field remains nil. The Server.handler() method skips authentication middleware entirely, accepting all requests without validation. This mode is intended strictly for localhost-only usage where network isolation provides security.

Token-Based Authentication

In token mode, the server generates a random 20-byte base64-encoded token using crypto/rand at startup. The AuthToken() method returns this value, which the CLI prints as a shareable URL:

reasonix serve --auth token

# Output: Share URL: http://127.0.0.1:8787?token=Vg5z7wE3tL…

The middleware checks every request for this token in either the ?token= query parameter or the Authorization: Bearer <token> header. Requests missing the correct token receive an HTTP 401 Unauthorized response.

Password-Based Authentication

In password mode, the server hashes the supplied password using bcrypt (golang.org/x/crypto/bcrypt) and stores the hash in memory. The middleware validates the Authorization: Basic ... header against this hash. If the hash is missing or validation fails, the server returns 401 Unauthorized with a WWW-Authenticate: Basic challenge, prompting browsers to request credentials from the user.

Request Flow and Middleware Chain

The HTTP request processing follows a strict chain defined in internal/serve/serve.go:

handler() → logMiddleware → auth.middleware → csrfGuard → mux

The auth.middleware function (defined in internal/serve/auth.go) wraps subsequent handlers. When authGate is nil, it acts as a pass-through. Otherwise, it performs mode-specific validation before allowing the request to proceed to the csrfGuard, which enforces application/json content types on POST requests to prevent cross-origin attacks.

Configuration Methods

Authentication behavior is controlled through two primary configuration channels.

Command-Line Flags

# No authentication (default)

reasonix serve

# Token-based

reasonix serve --auth token

# Password-based with plaintext (hashed automatically)

reasonix serve --auth password --password "my-secret"

TOML Configuration

For persistent or scriptable deployments, specify the mode in reasonix.toml:

[serve]
auth_mode = "password"
password_hash = "$2a$10$K9c…"

This approach allows pre-computed bcrypt hashes to be stored securely without exposing plaintext passwords in configuration files.

Practical Implementation Examples

Local Development (No Auth)

reasonix serve

# Accessible at http://127.0.0.1:8787 with no credentials required

Sharing with Token Authentication

reasonix serve --auth token

# Use the printed URL with embedded token for browser access

# Or include: Authorization: Bearer Vg5z7wE3tL…

Production Deployment with Password

reasonix serve --auth password --password "secure-password-123"

# Browser prompts for credentials

# Or programmatically: curl -u user:secure-password-123 http://host:8787/api/status

Summary

• The reasonix serve command implements authentication through the authGate struct in internal/serve/auth.go, instantiated in internal/serve/serve.go.
• Three modes are available: none (nil gate, no checks), token (random 20-byte base64 string), and password (bcrypt hash validation).
• Token authentication accepts credentials via the ?token= query parameter or Authorization: Bearer headers.
• Password authentication requires Authorization: Basic headers and uses bcrypt hashing via golang.org/x/crypto/bcrypt.
• Configuration originates from CLI flags (--auth, --password) or the TOML ServeConfig section.
• The middleware chain processes auth.middleware before CSRF protection, ensuring unauthorized requests are rejected early.

Frequently Asked Questions

How do I disable authentication for local development?

Set auth_mode = "none" in your TOML configuration or simply omit the --auth flag when starting the server. In this mode, the auth field in the Server struct remains nil, and the middleware passes all requests through without validation. This is the default behavior intended for localhost-only access.

Where is the authentication token stored when using --auth token?

The token is generated at runtime using crypto/rand and exists only in memory within the authGate struct. It is not persisted to disk. The AuthToken() method returns this value so the CLI can display the share URL, but the server itself maintains no record after shutdown.

Can I use a pre-hashed password instead of plaintext in the configuration?

Yes. Rather than providing --password on the command line, configure password_hash in your reasonix.toml file with a valid bcrypt hash. The server loads this hash directly into the authGate during initialization, avoiding plaintext exposure in process lists or configuration files.

What happens if I provide the wrong authentication credentials?

The auth.middleware function returns an HTTP 401 Unauthorized status. For token mode, this occurs immediately when the query parameter or Bearer header mismatches. For password mode, the server additionally includes a WWW-Authenticate: Basic header, triggering browser credential prompts or indicating to API clients that Basic authentication is required.

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