fix(gateway): allow bearer-auth session history reads by medns · Pull Request #81815 · openclaw/openclaw

medns · 2026-05-14T13:18:16Z

Summary

Problem: GET /sessions/:key/history and its SSE stream was overly strict, requiring operator.read explicitly even for shared-secret (API key) callers, leading to 403 or stream disconnects.
Why it matters: OpenAI-compatible HTTP callers (who just use Authorization: Bearer <key>) couldn't fetch their own session history, breaking integrations that expect API keys to work for history.
What changed: Switched resolveTrustedHttpOperatorScopes to resolveOpenAiCompatibleHttpOperatorScopes in sessions-history-http.ts, matching /v1/chat/completions and other compat endpoints. Also added a new test case and removed the outdated 403 expectations.
What did NOT change (scope boundary): Other strictly managed endpoints (like control-ui and session-kill) still require strong identity/explicit scopes.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #
This PR fixes a bug or regression

Real behavior proof

Behavior or issue addressed: Fixed 403 missing scope: operator.read and SSE disconnects on /sessions/:key/history for standard bearer API keys.
Real environment tested: Local development gateway (pnpm gateway:dev).
Exact steps or command run after this patch:
Start gateway locally:
$env:OPENCLAW_SKIP_CHANNELS="1"; $env:OPENCLAW_GATEWAY_TOKEN="test-token-12345"; $env:OPENCLAW_GATEWAY_AUTH_MODE="token"; node scripts/run-node.mjs --dev gateway

First, seed a session, then fetch the seeded history using the bearer token via REST:
curl -s -H "Authorization: Bearer test-token-12345" http://127.0.0.1:19001/sessions/agent:main:test-session/history?limit=1

Then, establish an SSE connection using the bearer token to verify it stays authorized across transcript updates:
curl -N -H "Authorization: Bearer test-token-12345" -H "Accept: text/event-stream" http://127.0.0.1:19001/sessions/agent:main:test-session/history

Evidence after fix:
Console output for seeded REST fetch:

{"sessionKey":"agent:main:test-session","items":[{"role":"assistant","content":[{"type":"text","text":"this is a seeded real-behavior-proof message"}],"__openclaw":{"id":"msg-1","seq":1}}],"messages":[{"role":"assistant","content":[{"type":"text","text":"this is a seeded real-behavior-proof message"}],"__openclaw":{"id":"msg-1","seq":1}}],"hasMore":false}

Console output for SSE connection during a transcript update:

retry: 1000

event: history
data: {"sessionKey":"agent:main:test-session","items":[{"role":"assistant","content":[{"type":"text","text":"this is a seeded real-behavior-proof message"}],"__openclaw":{"id":"msg-1","seq":1}}],"messages":[{"role":"assistant","content":[{"type":"text","text":"this is a seeded real-behavior-proof message"}],"__openclaw":{"id":"msg-1","seq":1}}]}

event: message
data: {"sessionKey":"agent:main:test-session","message":{"role":"assistant","content":[{"type":"text","text":"this is an SSE transcript update test"}]},"messageId":"msg-2","messageSeq":2}

Observed result after fix: The gateway successfully authenticates the bearer token and returns the seeded history payload. The SSE stream successfully establishes and correctly stays authorized (no disconnects) when new message chunks are emitted to the stream.
What was not tested: None.

Root Cause (if applicable)

Root cause: /sessions/:key/history incorrectly used resolveTrustedHttpOperatorScopes instead of resolveOpenAiCompatibleHttpOperatorScopes, making it out-of-sync with other compatible endpoints like /v1/chat.
Missing detection / guardrail: We lacked a direct test for normal API-key fetches of /sessions/:key/history.
Contributing context (if known): PR gateway: ignore bearer-declared HTTP operator scopes #57783 locked down operator scopes for Bearer auth but missed adding sessions-history-http.ts to the compatible API whitelist.

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/sessions-history-http.test.ts
Scenario the test should lock in: Ensure shared-secret Bearer auth allows history reads without 403.
Why this is the smallest reliable guardrail: Checks the exact API surface with the exact authentication mock.
Existing test that already covers this (if any): None.
If no new test is added, why not: New test was added.

User-visible / Behavior Changes

Callers using a simple Authorization: Bearer <Token> without the x-openclaw-scopes header can now successfully read /sessions/:key/history and establish SSE history streams without receiving a 403 or getting unexpectedly disconnected by the heartbeat check.

Diagram (if applicable)

N/A

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? Yes
If any Yes, explain risk + mitigation: We are intentionally granting CLI_DEFAULT_OPERATOR_SCOPES to shared-secret API key callers on /sessions/:key/history, to align with other compatible APIs. This is safe as possessing the global API key implies operator access.

Repro + Verification

Environment

OS: Windows
Runtime/container: Node.js / pnpm
Model/provider: N/A
Integration/channel (if any): N/A
Relevant config (redacted): N/A

Steps

Start gateway.
Fetch /sessions/:key/history with a valid Authorization: Bearer <key>.
Read the history.

Expected

200 OK with history payload.

Actual

200 OK with history payload.

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: I verified the HTTP API behavior through pnpm test.
Edge cases checked: I also patched the SSE heartbeat check isStreamStillAuthorized() to ensure stream connections aren't dropped.
What you did not verify: None.

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.

Compatibility / Migration

Backward compatible? Yes
Config/env changes? No
Migration needed? No
If yes, exact upgrade steps:

Risks and Mitigations

Risk: Broadening the scopes granted to simple API key bearers.
- Mitigation: The change applies specifically and only to the /sessions/:key/history endpoint, aligning it perfectly with already-existing compatible routes (/v1/*).

Copilot

Pull request overview

This PR adjusts the session history HTTP endpoint auth path so shared-secret Bearer callers can read session history consistently with OpenAI-compatible gateway surfaces.

Changes:

Switches /sessions/:key/history and its SSE reauth check to use OpenAI-compatible operator scope resolution.
Updates session history auth tests to keep WS scope rejection coverage and add Bearer default-scope HTTP read coverage.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
`src/gateway/sessions-history-http.ts`	Uses OpenAI-compatible scope resolution for history reads and SSE authorization checks.
`src/gateway/sessions-history-http.test.ts`	Updates auth regression expectations and adds a Bearer-auth history read test.

clawsweeper · 2026-05-14T13:21:30Z

Codex review: needs maintainer review before merge.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
The branch switches HTTP session-history REST and SSE authorization to the shared-secret scope resolver, updates session-history regression tests, and documents session history as a full shared-secret operator surface.

Reproducibility: yes. from source inspection, though I did not execute tests in this read-only review. Current main routes HTTP session history through the strict resolver, which returns no scopes for shared-secret bearer auth and therefore fails chat.history with missing operator.read.

PR rating
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Summary: Focused patch with solid live-output proof and regression coverage, with the overall rating capped by the intentional auth-boundary decision.

Rank-up moves:

Get explicit maintainer/security acceptance for treating HTTP session history as a shared-secret full-operator surface.
After that decision, rerun the targeted session-history tests on the current head before merge.

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Real behavior proof
Sufficient (live_output): The PR body includes after-fix local gateway commands plus copied REST and SSE output showing bearer-auth history reads and a transcript update on the stream.

Risk before merge

Merging intentionally lets any valid shared-secret token/password caller read and stream HTTP session history without an explicit x-openclaw-scopes header; maintainers should accept that as part of the full-operator secret boundary before landing.
The PR does not block internal session-history namespaces; fix(gateway): block internal session history over HTTP #55928 remains the linked follow-up for that narrower HTTP exposure policy.

Maintainer options:

Accept session history as a full-operator HTTP surface (recommended)
Merge after maintainer/security review confirms that shared-secret token/password holders may read and stream session history just like other direct trusted HTTP surfaces.
Pause for internal namespace policy
Hold this PR until fix(gateway): block internal session history over HTTP #55928 or an equivalent policy decides whether internal subagent, cron, and ACP session keys must be blocked over HTTP first.
Narrow the endpoint before granting default scopes
If the accepted boundary is only ordinary main-session history, revise this PR to enforce that namespace restriction before switching to shared-secret default scopes.

Next step before merge
The remaining blocker is maintainer/security acceptance of the authorization boundary, not a narrow automated code repair.

Security
Needs attention: No supply-chain issue was found, but the patch deliberately changes a gateway history-read authorization boundary.

Review details

Best possible solution:

Land the narrow resolver, docs, and regression-test change if maintainers accept HTTP session history as a shared-secret full-operator surface, while keeping internal namespace blocking tracked separately.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection, though I did not execute tests in this read-only review. Current main routes HTTP session history through the strict resolver, which returns no scopes for shared-secret bearer auth and therefore fails chat.history with missing operator.read.

Is this the best way to solve the issue?

Yes, with the explicit boundary caveat. Switching both initial REST authorization and SSE reauthorization to the shared-secret resolver is the narrowest maintainable code fix if maintainers accept session history as part of the full-operator HTTP secret model.

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix local gateway commands plus copied REST and SSE output showing bearer-auth history reads and a transcript update on the stream.

Label justifications:

P2: This is a focused gateway/auth compatibility bug fix with limited code surface but real API impact.
merge-risk: 🚨 security-boundary: The diff deliberately broadens HTTP session-history reads for shared-secret bearer credentials, so the trust boundary needs explicit maintainer acceptance.
rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🦞 diamond lobster, patch quality is 🐚 platinum hermit, and Focused patch with solid live-output proof and regression coverage, with the overall rating capped by the intentional auth-boundary decision.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body includes after-fix local gateway commands plus copied REST and SSE output showing bearer-auth history reads and a transcript update on the stream.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix local gateway commands plus copied REST and SSE output showing bearer-auth history reads and a transcript update on the stream.

Security concerns:

[medium] Confirm shared-secret history read boundary — src/gateway/sessions-history-http.ts:132
Changing session-history authorization to resolveSharedSecretHttpOperatorScopes makes token/password bearer auth a default-scope history-read surface, so maintainers should explicitly accept that data-access boundary before merge.
Confidence: 0.86

Acceptance criteria:

node scripts/run-vitest.mjs src/gateway/sessions-history-http.test.ts src/gateway/sessions-history-http.revocation.test.ts src/gateway/http-utils.request-context.test.ts
Review the linked internal session-history namespace policy before merge.

What I checked:

Current-main source behavior: Current main authorizes /sessions/:key/history with resolveTrustedHttpOperatorScopes, and that helper returns no scopes when a shared-secret bearer request cannot trust declared HTTP scopes, which explains the missing operator.read failure path. (src/gateway/sessions-history-http.ts:131, 4399eee6e0e4)
PR implementation: The PR head routes both the initial history request and SSE reauthorization through resolveSharedSecretHttpOperatorScopes, so token/password bearer auth receives the default operator scope set on this endpoint. (src/gateway/sessions-history-http.ts:132, 6d57d90f7647)
Regression coverage in PR: The PR adds REST and SSE cases that fetch history with only the bearer token, then append a transcript update and expect the SSE stream to deliver the new message. (src/gateway/sessions-history-http.test.ts:799, 6d57d90f7647)
Documentation update: The PR updates the security docs to say HTTP session history endpoints follow the same shared-secret full-operator rule as /tools/invoke, while identity-bearing modes still honor declared scopes. Public docs: docs/gateway/security/index.md. (docs/gateway/security/index.md:938, 6d57d90f7647)
Branch currency and hygiene: The PR head is exactly two commits ahead of current main with current main as merge-base, and the scoped diff has no whitespace errors. (6d57d90f7647)
Related boundary work: The GitHub context links open pull request fix(gateway): block internal session history over HTTP #55928 for blocking internal session-history namespaces over HTTP; this PR leaves that narrower policy question separate.

Likely related people:

Jacob Tomlinson: Auth helper and session-history scope behavior were changed in gateway: ignore bearer-declared HTTP operator scopes and earlier session-history scope alignment work. (role: auth hardening and session-history scope contributor; confidence: high; commits: 1c4512323151, f0af18672676; files: src/gateway/http-auth-utils.ts, src/gateway/sessions-history-http.ts, src/gateway/sessions-history-http.test.ts)
clay-datacurve: Introduced the direct session history HTTP and SSE endpoint as part of the session management/dashboard API work. (role: feature introducer; confidence: medium; commits: 7b61ca1b0615; files: src/gateway/sessions-history-http.ts, src/gateway/sessions-history-http.test.ts, src/gateway/server-http.ts)
Peter Steinberger: Recent history shows substantial session-history snapshot refactors and shared-gateway trust-boundary docs work around the same surface. (role: recent session-history and gateway docs contributor; confidence: medium; commits: 9e0d6329283f, b04dd6d05c3d, 7d55277d725e; files: src/gateway/sessions-history-http.ts, src/gateway/session-history-state.ts, docs/gateway/security/index.md)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4399eee6e0e4.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

clawsweeper · 2026-05-15T03:52:03Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/25899248654
Updated: 2026-05-15T03:58:14.306Z

clawsweeper · 2026-05-21T19:59:12Z

ClawSweeper PR egg

🔥 Warming up: real-behavior proof passed; findings, security review, or rank-up moves are still in progress.

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

odysseus0 · 2026-05-21T20:23:25Z

Merged via squash.

Prepared head SHA: eb49667324f589a6c591de1b9b895874bda33f78
Merge commit: 01d95b9757a0a8fc593a957ef1f45a3e800792dd

Thanks @medns!

@odysseus0