Skip to content

fix(oauth): include error_description in authorization callback errors - #626

Merged
hogan-yuan merged 7 commits into
mainfrom
fix/oauth-callback-error-description
Nov 18, 2026
Merged

hogan-yuan merged 7 commits into
mainfrom
fix/oauth-callback-error-description

Conversation

@hogan-yuan

@hogan-yuan hogan-yuan commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Reopens #619, which was closed by mistake. The branch had been deleted, so GitHub would not let the PR be reopened; this is the same work, with main merged in.

Summary

  • The local OAuth callback server only read error from the redirect and dropped error_description. An unknown or placeholder client_id (e.g. your-client-id from the examples) surfaced as a bare OAuth authorization failed: invalid_client, with nothing saying which client id was wrong.
  • error_description (RFC 6749 §4.1.2.1) is now appended: OAuth authorization failed: invalid_client: unknown client_id: <id>. The same text appears on the browser callback page.
  • Security: that text comes from the redirect query string, and the browser page previously inserted it as raw HTML — a reflected XSS on the localhost origin, reachable by any web page while an authorization was pending. It is now HTML-escaped.
  • Security: state is checked on every callback, including error redirects. A callback with a mismatched or missing state gets a 400 page and is ignored, and the flow keeps waiting for the real redirect. Previously any web page could end a pending authorization with an error text of its choosing.
  • The redirect text is sanitized: control characters (ANSI escapes and CR/LF included), line/paragraph separators, zero-width characters and bidi overrides are replaced, and error and error_description are each capped at 512 characters before reaching the error, the logs or the terminal.

Behaviour change worth noting

CsrfTokenMismatch (error code 8) is no longer returned by the authorization flow. The variant is kept for compatibility and marked as such in the code tables. A redirect with a wrong or missing state now leaves the flow waiting, so without a valid redirect it ends in AuthorizationTimeout after 5 minutes. Rust code matching CsrfTokenMismatch from the flow should handle AuthorizationTimeout instead.

Other language layers pass AuthorizationFailed { message } through unchanged, so no binding changes were needed.

Testing

Unit and flow tests: escaping, message format, sanitization; forged callbacks (wrong state, carrying either a code or an attacker-written error) are ignored and the real callback still completes the flow; error_description containing <script> is reported in the error and escaped on the page. cargo test -p longbridge-oauth: 52 passed, 1 ignored. cargo +nightly fmt --all --check clean; cargo clippy --all --all-features unchanged against main's baseline.

Downstream cargo check --all-targets on longbridge-terminal and longbridge-mcp with the workspace patched to this branch: the CLI drives the browser flow via OAuthBuilder::build and needs no change; the MCP only uses OAuth::from_token and is unaffected.

End-to-end against the live gateways

Driven with a non-existent client_id, relaying the gateway's real error redirect into the local callback server. Production (openapi.longbridge.com) and staging (openapi-global.longbridge.xyz) behave identically:

redirect: error=invalid_client
          error_description=unknown+client_id%3A+<id>
          state=<echoed correctly>

SDK error: OAuth authorization failed: invalid_client: unknown client_id: <id>

Security behaviour, verified against a live flow (the real error text contains no special characters, so these were injected into the callback directly):

case result
forged callback, wrong state attacker text never reaches the page
forged callback, no state attacker text never reaches the page
after both forgeries the flow is still waiting, not terminated
correct state + <script>alert(1)</script> no raw <script> on the page; < escaped to &lt;
same, plus CRLF and an ANSI escape CR/LF and ESC stripped from the error string

Note for reviewers

An earlier version of this description said the server returns internal_server_error rather than invalid_client for an unknown client, and called that an out-of-scope backend issue. That is no longer the case: both environments now return invalid_client with an accurate unknown client_id: <id> description. Nothing in this PR depends on which code the server sends — the fix is that whatever description it sends is now surfaced, escaped and sanitized.

学宁 and others added 6 commits November 5, 2026 13:46
The local callback server only read `error` from the redirect and dropped
`error_description`, so an unknown/placeholder client_id surfaced as a bare
`OAuth authorization failed: internal_server_error`. Append the description
(RFC 6749 §4.1.2.1) to the error, and HTML-escape the text shown on the
browser callback page since it comes from the query string.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…k errors

- the callback handler checks state for every redirect, error redirects
  included; a mismatched or missing state gets an error page and is
  ignored (the flow keeps waiting), so another page can neither abort a
  pending authorization nor inject an error text. CsrfTokenMismatch is
  no longer returned by the flow
- redirect-supplied error text has control characters (ANSI escapes,
  CR/LF) replaced and is capped at 512 characters before reaching the
  error, logs and the page (which still HTML-escapes it)
- tests: escape/format/sanitize units; flows tests for forged callbacks
  being ignored and for error_description + page escaping; existing
  flows send the correct state
- CHANGELOG: entries for the description, the XSS fix and the state
  check
… the CsrfTokenMismatch change

Review of 99c98b6:
- the page for a callback with a mismatched state no longer says
  "Authorization Failed": the SDK keeps waiting, so it tells the user to
  finish in the most recently opened window
- sanitize also replaces line/paragraph separators, zero-width
  characters and bidi overrides, not only control characters
- error code tables (Rust, C header) mark code 8 as no longer returned
- CHANGELOG: a mismatched redirect now ends in AuthorizationTimeout
  after 5 minutes instead of CsrfTokenMismatch; the 512-character cap
  applies to error and error_description each
Two claims did not match the code. Control characters become spaces, but an
ANSI escape sequence is not 'replaced': only its leading ESC is a control
character, so the rest survives as literal text — which defuses the sequence
without removing it, as the crate's own test asserts. And a truncated value is
512 characters plus an appended '…', not 512. Fixed in the CHANGELOG and in
sanitize's own doc comment, which carried the same two errors.
hogan-yuan added a commit to longbridge/openapi-go that referenced this pull request Nov 17, 2026
Ports the correction from longbridge/openapi#626. Two claims did not
match the code, in both the CHANGELOG and the function's own comment.
Control characters become spaces, but an ANSI escape sequence is not
replaced: unicode.IsControl matches only its leading ESC, so the rest
survives as literal text — which defuses the sequence without removing
it. And a truncated value is 512 characters plus an appended "…", not
512.
@hogan-yuan
hogan-yuan merged commit 19e7efd into main Nov 18, 2026
56 checks passed
@hogan-yuan
hogan-yuan deleted the fix/oauth-callback-error-description branch November 18, 2026 02:13
hogan-yuan added a commit to longbridge/openapi-go that referenced this pull request Nov 19, 2026
Documentation only — no behaviour change.

The CHANGELOG entry and the `sanitizeCallbackText` doc comment both
listed "control characters **including ANSI escapes**" among what gets
replaced with spaces. That is not what the function does, and the
wording mattered because it is the security note a reader relies on.

## What it actually does

```go
func isUnsafeRune(r rune) bool {
	return unicode.IsControl(r) || ...
}
```

Only the **leading ESC** of an ANSI sequence is a control character. The
rest — `[31m` — is ordinary printable text and survives verbatim. The
sequence is defused, not removed.

The second inaccuracy: both places said the fields are "capped at 512
characters" without mentioning that `…` is appended, so the cap is
effectively 512 + 1.

## Verified by running it

```
ANSI  in="\x1b[31mRED\x1b[0m"
     out=" [31mRED [0m"                       <- ESC -> space, "[31m" left as text

TRUNC inLen=562  outRunes=513  endsWithEllipsis=true
EXACT inLen=512  outRunes=512  endsWithEllipsis=false
```

So the defusing works, the escape text does remain, and `…` is added
only when something was actually cut.

## Note

The same two inaccuracies were in the Rust SDK's CHANGELOG and were
corrected there (longbridge/openapi#626). This brings the Go wording in
line.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant