[Feature] Trusted mTLS reverse-proxy authentication for full dashboard management

Read the three cited spots first: management origin resolution in src/server/auth-cors.ts (around lines 134-177), automatic GUI session issuance in src/server/gui-session.ts (171-199), and management session authority in src/server/management-auth.ts (286-315). The issue asks that the trust contract and config interface be agreed with maintainers before any PR, so the first step is a design discussion, not code. Done means an agreed proxy-trust mechanism and permission model, not a patch.

Area

Authentication and account pool

What are you trying to accomplish?

Manage a personal OpenCodex instance through an HTTPS reverse proxy that already authenticates clients with mTLS. The backend listens on 127.0.0.1:10100, and the browser uses a public domain. The operator explicitly authorizes the clients admitted by this proxy to perform all dashboard management operations.

After the browser presents an accepted client certificate, it should be able to use the dashboard without entering an OpenCodex admin token or a separate pairing code. This should cover ordinary settings/account/usage access and privileged dashboard operations, including stored-key disclosure, prompt editing, and Remote Link/Remote Workspace administration where those features are enabled and their runtime prerequisites are satisfied.

What prevents this today?

The deployment that prompted this request uses OpenCodex v2.79.0, the default standalone role, a loopback-only bind, and Caddy with client_auth { mode require_and_verify }. Caddy preserves the public Host and proxies to the loopback backend. The page opens, but shows browser authentication required, unavailable Codex settings, and usage requests failing with 401 Unauthorized.

Source inspection at the fixed v2.81.0 snapshot 19bd34a15354ba8c21fca89598fb18467f9cf9ee still shows the relevant restrictions. This is source inspection, not a claim that the deployment was retested on v2.81.0:

• Management origin resolution rejects a non-loopback Host when the configured listener is loopback. Adding a credential does not remove that independent restriction.
• Automatic GUI session issuance supports loopback entry and a specific trusted Tailscale identity path, but no general authenticating reverse-proxy path.
• Management session authority distinguishes ordinary admin credentials, GUI sessions, pairing, and Tailscale identity. Consequently, injecting the existing admin token does not confer all dashboard permissions. Some operations require a GUI session or specifically authorized issuance.

The missing capability is an explicit contract for accepting authentication and operator authorization delegated to a reverse proxy. This affects the remote-access model and permission semantics, so it deserves architectural discussion before implementation.

What should OpenCodex do?

• Offer an explicit, opt-in way to accept an authenticating reverse proxy as the management entry point, including when the backend listens only on loopback and retains the public Host.
• Allow the operator to authorize admitted proxy clients for full dashboard management. After successful delegated authentication, establish the application's browser session automatically, without another interactive token or pairing step.
• Define full dashboard authority consistently across management operations. Merely passing the ordinary admin-token gate must not leave supported dashboard actions inaccessible because they check a different session source.
• Keep browser Origin/CSRF protection, operation-specific confirmations, and independent device/executor authorization. Full dashboard authority should not automatically enable optional features or bypass their runtime prerequisites.
• Keep management authorization separate from model API credentials and model traffic, and preserve existing access policies when the new mode is not configured.
• Reject access when required proxy trust information is missing or invalid, and clearly distinguish proxy configuration failures from requests for another browser login.

The concrete trust mechanism and configuration interface should be settled with maintainers. A loopback address or caller-supplied forwarded headers alone should not establish proxy identity. TLS server verification also needs to remain distinct from delegated client authentication and administrative authorization.

Example usage or interface

Representative deployment, with certificate issuance details omitted:

OpenCodex: hostname=127.0.0.1, port=10100, runtimeRole=standalone
Browser -> HTTPS + client certificate -> Caddy -> HTTP loopback -> OpenCodex
Browser URL and forwarded Host: ocx.example.com

ocx.example.com {
    tls {
        client_auth {
            mode require_and_verify
            trust_pool file {
                pem_file /etc/caddy/client-ca.pem
            }
        }
    }
    reverse_proxy 127.0.0.1:10100
}

An additional, explicit OpenCodex trust/authorization setup would enroll this proxy; the example above is not a claim that the current deployment already supplies that missing contract.

Expected workflow: configure the trusted management entry point and its full dashboard authorization once, then open https://ocx.example.com, authenticate with the client certificate, and use all available management functions. Refreshing the page or renewing an application session should not require another OpenCodex token or pairing code.

Alternatives or workarounds

• Proxy injection of X-OpenCodex-API-Key: considered, but the current management token does not grant every dashboard permission and does not fix the loopback/public-origin restriction. Unconditionally replacing this header would also replace a browser's GUI-session credential.
• Browser pairing or manual admin-token entry: considered, but adds a separate interaction after the operator's chosen proxy authentication. Current standalone pairing is restricted to its supported local origin.
• Rewriting Host to localhost: considered and excluded from this deployment; it does not establish the original public browser Origin/session contract.
• Tailscale identity integration: an existing precedent for external identity automatically establishing a GUI session, but it does not provide a general mTLS reverse-proxy contract or full dashboard authority.

Possible designs for discussion include a protected management ingress, a proxy-specific credential or authenticated upstream connection, and automatically issued sessions with explicit operator capabilities. The issue does not prescribe one design or new configuration keys.

Additional context

Related to #6650, which proposes separating remote connections, model access, and management access. This request supplies a concrete externally authenticated management-entry scenario for that discussion and could also be handled as an independent capability.

#6650 currently preserves pairing/session authorization for management; its TLS recipient verification should not be interpreted as already authorizing mTLS browser clients. This issue asks whether and how explicit proxy authentication delegation can satisfy management authentication and grant full dashboard authority while retaining the other boundaries.

No dependency on completion of #6650 is assumed. Scope and integration with that proposal should be agreed before starting a PR.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.