Add trusted management origin allowlist for reverse-proxy logins

[maiphucgiang]

Changes

• Fixes 我在自己的VPS上绑了域名后，用HTTPS访问，无法登录 #31: behind a reverse proxy that rewrites the forwarded Host/scheme (HTTPS domain while the container sees HTTP), the browser Origin no longer matches what the server sees, so login fails the Origin check. Add admin_allowed_origins (WebUI system settings, hot) plus CODEBUDDY2API_ADMIN_ORIGINS / --admin-allowed-origins: comma-separated origins or bare domains (https://chat.example.com, chat.example.com; bare domains mean HTTPS), validated and normalized, at most 32 entries. An explicit CLI or environment value locks the WebUI field under the existing precedence rules.
• Login and Cookie-authenticated management Origin checks now accept exact whitelisted origins; strict same-origin matching, the same-origin Referer fallback and CSRF token requirements are unchanged, and requests without an Origin never use the allowlist.
• Synchronize CLI, WebUI settings, Compose, the environment template and concise bilingual documentation. No dependency, database-schema or version changes (1.2.6).

Verification

• All 52 backend test scripts pass (1062 tests), including new exact-origin allowlist matching, proxied foreign-origin login and Cookie writes, settings validation/normalization/hot-apply, CLI/environment/persisted precedence and locking, and deployment-template coverage.
• Booted the actual gateway twice locally: with --admin-allowed-origins chat.example.com, http://10.0.0.1:8787, whitelisted-Origin logins return 200 while a missing or unlisted Origin stays 403, and the settings API reports the normalized value as locked with CLI source. Without the flag, a WebUI PATCH of proxy.example.com normalizes to https://proxy.example.com, applies hot (login then returns 200), reports source management, and rejects an invalid entry with 400.
• Reverse-proxy advice in the docs now prefers the allowlist over disabling CSRF protection; the startup-only admin_csrf escape hatch is unchanged.

Scope and rollback

No change to same-origin matching rules, Referer fallback, CSRF tokens, session handling or /v1/*; the allowlist only relaxes the browser Origin comparison for explicitly configured addresses. Remove the setting (or clear it in the WebUI) and the extra origins stop being trusted immediately; no persisted-state migration is needed.

Summary by Sourcery

Support trusted management origins for reverse-proxy deployments without weakening the existing Origin and CSRF protections.

New Features:

• Add a configurable management-origin allowlist through WebUI settings, environment variables, and a CLI option to support reverse-proxy deployments.
• Allow explicitly trusted origins for management login and cookie-authenticated writes while preserving existing same-origin, Referer, and CSRF protections.

Bug Fixes:

• Fix management login failures when reverse proxies rewrite the forwarded host or scheme and the browser Origin differs from the server-visible origin.

Enhancements:

• Validate, normalize, deduplicate, limit, and enforce precedence and locking for configured management origins.

Deployment:

• Expose the management-origin setting in Docker Compose and deployment environment templates.

Documentation:

• Document configuring trusted management origins in English and Chinese, recommending the allowlist over disabling CSRF protection for reverse-proxy setups.

Tests:

• Add coverage for exact-origin matching, proxied login and cookie writes, settings hot application, configuration precedence and locking, and deployment templates.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sourcery-ai]

Reviewer's Guide

Introduces a validated, hot-reloadable allowlist for trusted management origins to support reverse-proxy logins without weakening same-origin or CSRF protections, with startup precedence/locking, deployment wiring, tests, and bilingual documentation.

Sequence diagram for trusted-origin management authentication

sequenceDiagram
    participant Browser
    participant AdminAPI
    participant AdminAuth
    participant Settings

    Browser->>AdminAPI: POST /admin/session
    AdminAPI->>AdminAuth: csrf_enabled()
    AdminAPI->>AdminAuth: allowed_origins()
    AdminAuth->>Settings: Read admin_allowed_origins
    Settings-->>AdminAuth: Normalized origin set
    AdminAPI->>AdminAuth: same_origin(request, allowed_origins)
    alt Same origin or exact allowed Origin
        AdminAPI->>AdminAuth: login(request, api_key)
        AdminAuth-->>Browser: 200 login response
    else Origin rejected
        AdminAPI-->>Browser: 403 Origin check failure
    end

Loading

Sequence diagram for allowlisted management writes with CSRF protection

sequenceDiagram
    participant Browser
    participant AdminAPI
    participant AdminAuth
    participant Session

    Browser->>AdminAPI: Cookie-authenticated management write
    AdminAPI->>AdminAuth: allowed_origins()
    AdminAuth-->>AdminAPI: Normalized allowlist
    AdminAPI->>AdminAuth: same_origin(request, allowed_origins)
    AdminAPI->>Session: Compare x-csrf-token with session csrf_token
    alt Origin accepted and CSRF token valid
        AdminAPI-->>Browser: Management response
    else Origin or CSRF validation fails
        AdminAPI-->>Browser: 403 validation failure
    end

Loading

Flow diagram for allowed-origin normalization

flowchart TD
    INPUT[Comma or space separated origins] --> COUNT{At most 32 entries?}
    COUNT -- No --> INVALID[Reject setting]
    COUNT -- Yes --> SCHEME[Add https to bare domains]
    SCHEME --> VALIDATE{Valid http or https origin?}
    VALIDATE -- No --> INVALID
    VALIDATE -- Yes --> NORMALIZE[Normalize host and default ports]
    NORMALIZE --> DEDUPE[Remove duplicates]
    DEDUPE --> STORED[Store hot normalized value]

Loading

File-Level Changes

Change	Details	Files
Add normalized, hot-reloadable management-origin allowlist configuration with CLI, environment, and WebUI integration.	Support comma/whitespace-separated HTTPS/HTTP origins and bare HTTPS domains. Normalize, deduplicate, validate, and cap entries at 32. Apply CLI-over-environment-over-persisted-management precedence and lock the WebUI field for explicit startup configuration. Propagate the setting through runtime defaults, Compose, and deployment configuration.	app/settings.py converter.py docker-compose.yml tests/test_environment_config.py tests/test_runtime_endpoints.py tests/test_deployment.py
Relax management browser-origin checks only for explicitly allowlisted origins while preserving existing CSRF protections.	Use exact normalized scheme, hostname, and effective-port matching for login and cookie-authenticated management writes. Retain same-origin matching, strict Referer fallback behavior, CSRF token checks, and rejection of requests without Origin. Read the allowlist from hot configuration so additions and removals take effect immediately.	app/admin_auth.py app/admin_api.py tests/test_admin_api.py
Document reverse-proxy configuration and deployment usage for the new trusted-origin mechanism.	Add bilingual guidance, environment-variable references, and examples for allowlisted proxy domains. Recommend the allowlist over disabling CSRF protection while retaining the existing startup-only escape hatch. Cover optional Compose and environment-template wiring.	docs/advanced.md docs/advanced.zh-CN.md docker-compose.yml tests/test_deployment.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#31	Allow users accessing the management WebUI through an HTTPS domain and reverse proxy to log in when the proxy rewrites the Host or scheme seen by the container.	✅
#31	Provide a secure, explicitly configured allowlist of trusted management origins, while preserving strict same-origin checks, CSRF-token requirements, Referer behavior, and rejecting missing or unlisted origins.	✅
#31	Expose the trusted-origin configuration through WebUI settings, CLI/environment variables, Docker Compose, and bilingual documentation with validation, normalization, precedence, locking, and hot application where applicable.	✅

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-16T22:38:43.766497Z	dfdaa0b	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Needs a human reviewer. This changes the trust boundary for admin login and cookie-authenticated writes by allowing configured browser origins to bypass the server-observed same-origin check. If the allowlist or proxy assumptions are wrong, an attacker-controlled origin could trigger administrative actions and obtain a session immediately; reverting prevents future requests but does not undo actions already performed.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook