# How the Reasonix Web Frontend Serve Command Handles Authentication

> Discover how the Reasonix web frontend serve command manages authentication with none, token, or password modes. Learn about its authGate struct and configuration options.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-27

---

**The `reasonix serve` command implements an optional authentication layer via the `authGate` struct in [`internal/serve/auth.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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](https://github.com/esengine/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go), the `Server` struct contains an optional `auth` field of type `*authGate`:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```bash
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go):

```

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

```

The `auth.middleware` function (defined in [`internal/serve/auth.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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**

```bash

# 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml):

```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)**

```bash
reasonix serve

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

```

**Sharing with Token Authentication**

```bash
reasonix serve --auth token

# Use the printed URL with embedded token for browser access

# Or include: Authorization: Bearer Vg5z7wE3tL…

```

**Production Deployment with Password**

```bash
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/auth.go), instantiated in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.