How --trusted-origins Bypasses Authentication Origin Checks in code-server

The --trusted-origins flag injects a whitelist into the origin-checking middleware that allows specified origins to skip strict host-origin validation, returning early from the authentication check before a "Forbidden" error is thrown.

The coder/code-server repository implements strict origin validation to protect its HTTP endpoints from cross-origin attacks. When deploying behind complex reverse proxies or accessing from multiple domains, administrators may need to bypass these checks for specific origins. This article explains how the --trusted-origins CLI argument interacts with the authenticateOrigin function in src/node/http.ts to selectively disable origin authentication.

How Origin Authentication Works

The origin verification system relies on two key components in src/node/http.ts: the ensureOrigin middleware and the authenticateOrigin validation function.

The ensureOrigin Middleware

When a request arrives at the code-server HTTP interface, the ensureOrigin middleware intercepts it before processing continues. According to the source in src/node/http.ts, this middleware wraps the authentication logic in a try-catch block and invokes authenticateOrigin(req) to validate the request's origin header against expected values.

Host Header Validation Logic

Under normal operation, authenticateOrigin extracts the Origin header from the incoming request and parses its host component. The function then performs a strict comparison between this origin host and the request's Host header, which represents the expected origin for correctly proxied deployments. If these values mismatch and no bypass mechanisms are active, the function throws a "Forbidden" error that blocks the request.

How --trusted-origins Bypasses Authentication

The --trusted-origins flag modifies the validation logic by injecting a whitelist that is consulted before the strict host-origin comparison occurs.

Trusted Origins Array Matching

The CLI flag is defined in src/node/cli.ts with the configuration "trusted-origins": { type: "string[]", description: "Disables authenticate origin check for trusted origin. Useful if not able to access reverse proxy configuration." }. When code-server starts, this array is parsed into req.args["trusted-origins"] and becomes available to the authentication middleware.

Inside authenticateOrigin in src/node/http.ts, the logic retrieves this array with const trustedOrigins = req.args["trusted-origins"] || [];. Before performing the strict host-origin validation, the function checks: if (trustedOrigins.includes(origin) || trustedOrigins.includes("*")) { return; }. If the incoming origin matches any entry in this array, the function returns early, effectively bypassing the authentication origin check and allowing the request to proceed.

Wildcard Support for All Origins

The implementation specifically supports the wildcard string "*" as a trusted origin value. When present in the array, this wildcard matches any incoming origin, completely disabling origin verification for all requests. This configuration requires extreme caution as it removes all origin-based protection from the server's authentication layer.

Configuration Examples

You can supply trusted origins through command-line arguments or configuration files depending on your deployment requirements.

Command Line Usage

Pass specific domains as comma-separated values or as repeated flags:

# Allow requests from https://example.com without origin verification

code-server --trusted-origins example.com

# Disable origin verification for all origins (use with extreme caution)

code-server --trusted-origins "*"

YAML Configuration File

Define the array in a configuration file for persistent settings:

trusted-origins:
  - example.com
  - staging.myapp.io

Start the server with the config file:

code-server --config config.yaml

Programmatic Request Behavior

Without the flag, a request from an untrusted origin would be blocked:

// This request would normally receive a 403 Forbidden response
fetch('https://my-code-server.com/api', {
  method: 'GET',
  credentials: 'include',
  headers: {
    Origin: 'https://untrusted.com'
  }
})

When the server runs with --trusted-origins untrusted.com, the authenticateOrigin function recognizes the match and returns early, allowing the request to succeed without triggering the host-origin validation failure.

Summary

• The ensureOrigin middleware in src/node/http.ts calls authenticateOrigin to validate all incoming HTTP requests against their origin headers.
• Under normal operation, authenticateOrigin compares the request's Origin header host against the Host header, rejecting mismatches with a "Forbidden" error.
• The --trusted-origins flag, defined in src/node/cli.ts, populates req.args["trusted-origins"] with an array of whitelisted domains.
• If the incoming origin matches any entry in the trusted array—or if the wildcard "*" is present—authenticateOrigin returns early and skips the strict host-origin validation.
• This mechanism provides a controlled bypass for reverse proxy configurations where the standard origin checks would otherwise block legitimate traffic.

Frequently Asked Questions

What is the difference between --trusted-origins and disabling authentication entirely?

The --trusted-origins flag specifically bypasses only the origin validation step within the authentication pipeline, whereas disabling authentication would remove all security checks including password verification and session validation. Origin checking ensures that requests originate from expected domains, while authentication verifies the user's identity. The flag relaxes the former without affecting the latter.

Why would I need to use --trusted-origins instead of fixing my reverse proxy?

According to the source code description in src/node/cli.ts, this flag is "Useful if not able to access reverse proxy configuration." Some deployment environments—such as managed hosting platforms or corporate networks with restricted infrastructure access—prevent administrators from modifying proxy headers like X-Forwarded-Host. In these scenarios, the origin header seen by code-server may not match the expected host value through no fault of the deployment architecture, necessitating a whitelist-based bypass.

Is it safe to use the wildcard "*" with --trusted-origins?

Using --trusted-origins "*" disables origin verification for all incoming requests, which the source code comments and documentation indicate should be used with "extreme caution." This configuration removes protection against cross-site request forgery (CSRF) attacks that rely on malicious websites making authenticated requests to your code-server instance. Only deploy the wildcard in highly controlled network environments where other security layers, such as network segmentation or VPN requirements, mitigate the risk of unauthorized cross-origin requests.

Where does the origin validation logic reside in the codebase?

The validation logic is implemented in src/node/http.ts within the authenticateOrigin function, which is invoked by the ensureOrigin middleware. The CLI argument definition and parsing reside in src/node/cli.ts, which populates req.args["trusted-origins"] that the HTTP layer consumes. These two files form the complete bypass mechanism from configuration to execution.

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