PR #57218: fix(gateway): restore headerless bearer compatibility on OpenAI-compatible HTTP routes

• Repository: openclaw/openclaw
• Author: buddyh
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/57218

Description (problem / solution / changelog)

Summary

• Problem: #56763 reports that /v1/models and /v1/chat/completions now reject valid gateway bearer auth with missing scope: operator.read/write unless clients also send x-openclaw-scopes.
• Why it matters: This regressed OpenAI-compatible HTTP clients that were previously documented to work with shared gateway bearer auth alone, including Open WebUI-style integrations.
• What changed: Restore the documented compatibility path on the OpenAI-compatible HTTP routes by granting the default operator scope bundle only when the scope header is absent and shared gateway auth succeeded via token or password.
• What did NOT change (scope boundary): Explicit x-openclaw-scopes remains authoritative, explicit empty/downscoped headers still fail, and trusted-proxy does not get the implicit fallback.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #56763
• Related #57113
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: the HTTP OpenAI-compatible route checks started enforcing method scopes from x-openclaw-scopes, but the shared gateway bearer auth path does not derive scopes onto the request.
• Missing detection / guardrail: there was no route-level regression test covering headerless bearer auth on /v1/models and /v1/chat/completions.
• Prior context (git blame, prior PR, issue, or refactor if known): the issue was reported after the recent HTTP scope-hardening work, especially #56618 for chat completions; /v1/models had a similar hardening path already in place.
• Why this regressed now: the scope checks assumed all HTTP clients would send x-openclaw-scopes, but the documented compatibility contract for shared bearer auth did not require that.
• If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/models-http.test.ts, src/gateway/openai-http.test.ts, plus helper coverage in src/gateway/http-auth-helpers.test.ts
• Scenario the test should lock in: headerless token/password bearer auth succeeds on OpenAI-compatible HTTP routes, while explicit empty or downscoped headers still fail.
• Why this is the smallest reliable guardrail: the regression lives at the HTTP auth-to-method-scope seam, not in the lower-level auth primitive alone.
• Existing test that already covers this (if any): none for the headerless compatibility path
• If no new test is added, why not: N/A

User-visible / Behavior Changes

OpenAI-compatible HTTP clients using valid gateway bearer auth no longer need to send x-openclaw-scopes just to call /v1/models or /v1/chat/completions. Explicitly supplied scopes still behave as before.

Diagram (if applicable)

Before:
[HTTP bearer auth succeeds] -> [missing x-openclaw-scopes] -> [required method scope checks []] -> [403 missing scope]

After:
[HTTP bearer auth succeeds] -> [missing x-openclaw-scopes] -> [compatibility fallback for token/password auth] -> [method scope check passes]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 24 / Bun 1.3.x local dev runtime
• Model/provider: not relevant to the auth regression
• Integration/channel (if any): OpenAI-compatible HTTP gateway routes
• Relevant config (redacted): shared gateway auth via token/password

Steps

1. Start the gateway with shared auth enabled.
2. Call /v1/models or /v1/chat/completions with valid Authorization: Bearer ... and no x-openclaw-scopes header.
3. Compare with explicit empty or downscoped x-openclaw-scopes headers.

Expected

• Valid headerless bearer auth succeeds on the OpenAI-compatible HTTP routes.
• Explicit empty or insufficient scopes still fail.

Actual

• Before this fix, headerless bearer auth fails with missing scope: operator.read or missing scope: operator.write.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • helper-level scope resolution: token/password headerless auth gets the default operator scope bundle; empty/downscoped headers stay denied; trusted-proxy gets no implicit fallback
  • endpoint-level /v1/models probes: token headerless 200, token empty-scope 403, token downscoped 403, password headerless 200
  • changed files pass oxlint and oxfmt --check
• Edge cases checked:
  • explicit empty scope header remains empty rather than being treated as missing
  • trusted-proxy remains excluded from the compatibility fallback
• What you did not verify:
  • I did not get a completed focused Vitest run in this environment; the targeted Vitest command stayed in startup/compile with no test-body output, so I am relying on the direct runtime probes plus CI for the full suite.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: route-local compatibility fallback could be misread as broad auth widening
  • Mitigation: keep it scoped to the OpenAI-compatible HTTP routes, only when the scope header is absent, and only for token / password auth; explicit scopes and trusted-proxy behavior are unchanged

Changed files

• src/gateway/http-auth-helpers.test.ts (modified, +94/-2)
• src/gateway/http-auth-helpers.ts (modified, +63/-12)
• src/gateway/http-endpoint-helpers.test.ts (modified, +10/-8)
• src/gateway/http-endpoint-helpers.ts (modified, +11/-6)
• src/gateway/models-http.test.ts (modified, +54/-4)
• src/gateway/models-http.ts (modified, +13/-8)
• src/gateway/openai-http.test.ts (modified, +34/-0)
• src/gateway/openai-http.ts (modified, +2/-0)