Skip to content

Fix two misleading /oauth/connect/redeem errors: a stuck claim and a swept-too-early expiry - #234

Merged
aterga merged 7 commits into
mainfrom
fix/connect-redeem-claim-and-expiry
Nov 10, 2026
Merged

aterga merged 7 commits into
mainfrom
fix/connect-redeem-claim-and-expiry

Conversation

@aterga

@aterga aterga commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Two bugs in /oauth/connect/redeem make the pinned callback page show the wrong error. They turned up while root-causing the intermittent "This connect request is unknown or already used. Restart from your client." sign-in error. This PR does not fix that error. It removes two ways of getting a misleading message, so the reports we get are easier to trust.

  1. A redemption cut off mid-flight left its claim stuck.
    • connect_redeem marks the pending connect redeeming while its one mcp_register_v2 call is in flight. It cleared the mark only on the error path, after the call returned.
    • When the request future is dropped instead, that code never runs. This happens when the browser disconnects, or when a fronting proxy times the request out.
    • The connect then stayed marked until it expired, and every retry was refused with "This connect request is already being processed".
    • Fix: claim_redemption now returns a guard that owns the mark. The error path awaits the guard's release() before answering, and its Drop clears the mark when the request is cut off.
  2. A sign-in finished after the 10-minute TTL was reported as unknown, not expired.
    • The redeem gate already says "This connect request has expired", but the 60s sweep dropped the entry within a minute of expiry.
    • From then on, the only possible answer was "unknown or already used". A gateway restart or a reloaded callback page produces the same words.
    • Fix: the sweep keeps an expired pending connect for one more hour (EXPIRED_CONNECT_RETENTION), and at the cap admission evicts only the oldest entry.
    • Keeping expired connects around must not let one be redeemed. So no new attempt is claimed on an expired connect, and no code is minted for one. If a registration finished late anyway, the session it was granted is discarded.

Related issues

None filed.

Changes

Redemption claim guard

  • RedeemClaim::Claimed now carries a RedemptionClaim guard (an Arc of the authz map, plus the state). The guard is the only thing that clears redeeming.
    • release() waits for the lock. The error path awaits it before answering.
    • Drop is the fallback for a request cut off mid-flight. It clears the mark at once if the lock is free; otherwise it hands the release to the runtime.
    • On success, the recorded code is what a later claim gets.
  • claim_redemption rechecks the TTL under the lock and returns the new RedeemClaim::Expired. A request whose gate snapshot predates the TTL can therefore not start a registration past it.

Retention

  • Expired pending connects are kept for EXPIRED_CONNECT_RETENTION (1 h).
  • AuthzPending::retained_for measures what is left of that period. The reaper drops a connect only once it reaches zero (forgotten).
  • Admission (make_room in insert_pending) evicts by retained_for, so at the cap only the oldest entry goes. An expired entry is always older than a live one. The cap (MAX_PENDING_CONNECTS) is unchanged.

Mint

  • reserve_code refuses a connect past CONNECT_TTL with the gate's "has expired" message (CONNECT_EXPIRED_MSG).
    • This keeps the promise that imcp2-core's 15-minute pending-session reap relies on (PENDING_CONNECT_TTL_NS): no connect is redeemed past its TTL.
    • Without the check, a slow redemption could mint a code for a session that had been reaped and re-created with a key II never registered.
  • On a refusal, reserve_code drops the session the registration just granted, using the new imcp2-core Identities::discard_session. Nothing else would drop that session before its grant expired.
    • discard_session logs the "session closed" that pairs with "session opened".
    • It runs its removal in a task of its own, so a dropped request can't skip it.

Other

  • AuthzPending.created is now a tokio::time::Instant. Outside a paused test it reads the same monotonic clock.
  • The root crate gets tokio's test-util as a dev-dependency feature. Cargo.lock is unchanged.
  • The README's reaper paragraph mentions the retention.

Testing

Each new test fails when its fix is disabled.

Test What it covers
a_redemption_cut_off_mid_flight_gives_its_claim_back (new) A claim dropped mid-await, the way hyper drops it on disconnect, is given back.
a_claim_dropped_under_a_held_lock_is_released_once_the_lock_frees (new) The deferred Drop release.
a_released_claim_is_free_by_the_time_release_returns (new) release() waits out a held lock and leaves nothing pending.
a_connect_redeemed_after_its_ttl_is_reported_expired (new, paused clock) "Has expired" after the TTL. "Unknown or already used" only once the retention runs out.
a_full_map_evicts_only_its_oldest_retained_connect (new, paused clock) At the cap, one admission evicts one entry.
no_attempt_is_claimed_on_a_connect_past_its_ttl (new, paused clock) A claim past the TTL is Expired, and nothing is marked.
no_code_is_minted_for_a_connect_past_its_ttl (new, paused clock) Within the TTL a code is minted, idempotently. Past it the code is refused, the granted session is discarded, and the connect stays claimed until the attempt's own claim lets go.
discard_session_drops_even_a_granted_session (new, imcp2-core) A session with a grant is dropped.
discard_session_completes_even_when_its_caller_is_cut_off (new, imcp2-core) A caller dropped mid-discard still gets the session removed.
redemption_claim_is_single_flight (updated) A won claim is held, and dropped to release.
  • cargo build --locked --all-targets
  • cargo test --locked --workspace --all-targets. All pass: imcp2 lib 82, bin 8, routers 10; imcp2-core 216; imcp2-local 21.
  • cargo fmt --all / cargo clippy --workspace --all-targets (tree is warning-free)
  • npm test --prefix monitoring/mcp-status (n/a, dashboard untouched)

Checklist

  • I have read the Contributing guidelines.
  • Docs (README / comments) updated for any user-visible change.
  • No secrets, credentials, or internal-only information are included.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG

`/oauth/connect/redeem` marks the pending connect `redeeming` while its one
`mcp_register_v2` call is in flight, and cleared the mark only on the error
path after that call returned. When the request future is dropped instead —
the browser disconnects, or a fronting proxy times the request out — that
code never runs, so the connect stayed marked until it expired and every
retry was refused as "This connect request is already being processed".

The claim is now a guard returned by `claim_redemption` that clears the mark
when dropped, on every way out of the handler. Releasing after a success is
harmless: the minted code is what a later claim returns first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG
`/oauth/connect/redeem` answers "This connect request has expired" for a
pending connect past its 10-minute TTL, but the 60s sweep dropped the entry
within a minute of expiry. From then on the only possible answer was "This
connect request is unknown or already used", the same words a restart or a
reloaded callback page produce, so a slow sign-in was misreported and hard
to tell apart from those.

The sweep now keeps an expired pending connect for another hour
(EXPIRED_CONNECT_RETENTION) before forgetting it. This costs no live connect
its slot: `make_room` drops expired entries first, and the map stays under
its cap either way.

`AuthzPending.created` is now a `tokio::time::Instant` (the same monotonic
clock outside a paused test), so the new test walks a connect past its TTL
and its retention on a paused clock; the root crate gains tokio's `test-util`
as a dev-dependency feature, which leaves the lockfile unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG
@aterga
aterga requested a max review from Copilot November 6, 2026 15:51
@aterga
aterga marked this pull request as ready for review November 6, 2026 15:52
@aterga
aterga requested a review from a team November 6, 2026 15:52

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Retained expired entries can allow code issuance past CONNECT_TTL, while deferred cleanup after registration failure can incorrectly reject retries as already in progress.

2 open issues
What changed in this PR

Improves error accuracy in the OAuth connect flow without claiming to resolve the underlying intermittent “unknown or already used” failure.

Changes:

  • Adds drop-based cleanup so cancelled redemption attempts release their claims.
  • Retains expired pending connects for another hour, subject to existing map limits, to preserve expiry diagnostics.
  • Adds cancellation, lock-contention, and paused-clock expiry tests.
File Description
src/​auth.rs Implements claim guards, expiry retention, and regression tests.
README.md Documents delayed cleanup of expired pending authorizations.
Cargo.toml Enables Tokio’s test-util feature for paused-clock tests.

Review effort: Max

Comment thread src/auth.rs Resolved
Comment thread src/auth.rs Resolved
The previous commit moved the release onto the claim's `Drop`, which cannot
wait for the `authz` lock: when the lock was busy, the release went to a
spawned task and the error answer could leave first, so for a moment the
connect still read as "already being processed". The error path now awaits
`RedemptionClaim::release` (as it awaited `release_redemption` before), and
`Drop` stays the fallback for a request cut off mid-flight.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG
Copilot AI max review requested due to automatic review settings November 6, 2026 16:05

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

At capacity, insert_pending purges all retained expired entries instead of freeing one slot, causing late callbacks to be reported as unknown or already used before the retention period ends.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Admission eviction purges all retained expired entries

src/​auth.rs:1894

At capacity, insert_pending still passes AuthzPending::remaining to make_room, so one new connect deletes every retained expired entry rather than freeing one slot. Hundreds of late callbacks can therefore revert to “unknown or already used” before the retention period ends. Use the retention deadline for admission eviction so live connects still take priority without purging all retained entries.

2 resolved since last review

Review effort: Max

Admission still bounded the pending-connect map by redeemable time, so once
it was full, one new `/oauth/authorize` dropped EVERY expired entry at once
(`make_room` first purges all zero-remaining entries). That undid the
retention from the previous commits under load: a burst of connects would
turn every late sign-in back into "unknown or already used".

Admission now evicts by how long an entry is still remembered
(`AuthzPending::retained_for`), so at the cap only the oldest entry goes.
Live connects keep priority, since an expired entry is always older than a
live one; the map's cap is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG
Copilot AI max review requested due to automatic review settings November 6, 2026 16:18

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

A critical redemption race can recreate a swept session with an unregistered key, making sign-in appear successful while subsequent authenticated calls fail.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

High severity Prevent redemption from recreating a session with an unregistered key

src/​auth.rs:1903

If a redemption passes the 10-minute gate but finishes after the 15-minute session sweep, set_grant_expiration recreates the session with a fresh key even though II registered the original key. Retaining authz now lets that response mint a code for the unregistered key, so sign-in appears successful but subsequent authenticated calls fail. Keep the original session alive during redemption, or reject completion if its key was removed instead of recreating it.

Review effort: Max

`imcp2-core` reaps an unredeemed connect's session 15 minutes in, on the
stated promise that a connect past the 10-minute CONNECT_TTL can't be
redeemed. The mint step never checked the TTL itself; before this PR the
sweep had dropped the `authz` entry by about 11 minutes, so a redemption
that outlived the session reap failed with "no longer available". With
expired connects now retained, such a redemption would reach the mint, and
`set_grant_expiration` would have re-created the reaped session with a fresh
key II never registered, handing the client a code for a session whose
every signed call fails.

The reservation step (now `reserve_code`) refuses a connect past its TTL
with the same "has expired" message the gate uses, which keeps the promise
deterministically instead of by sweep timing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG
Copilot AI max review requested due to automatic review settings November 6, 2026 16:30

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical expiry-path bugs can allow concurrent registrations and leave unreachable granted sessions consuming capacity for up to 30 days.

2 open issues

Review effort: Max

Comment thread src/auth.rs Resolved
Comment thread src/auth.rs Resolved
Two follow-ups to refusing a code past CONNECT_TTL:

- `reserve_code` cleared `redeeming` itself, while the attempt's
  `RedemptionClaim` was still held. On the refused path no code is recorded,
  so between that unlock and the guard's drop another request could claim
  the connect, and the first guard's drop would then clear the new claim's
  mark, letting a third registration run alongside it. The mark is now left
  to the claim that set it; on success the recorded code is what a later
  claim gets.

- The refused path runs after `mcp_register_v2` succeeded, so the session
  already holds a live grant. Neither the pending-connect reaper nor the
  admission bound drops a granted session, so it would hold its slot (and
  count as live) until the grant expired, up to 30 days, with no code ever
  reaching it. `imcp2-core` gains `Identities::discard_session`, which
  `reserve_code` calls on a refusal; it logs the "session closed" that pairs
  with the grant's "session opened".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG
Copilot AI max review requested due to automatic review settings November 6, 2026 16:44

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Redemption lacks a TTL recheck under the claim lock, and cancelled cleanup can leave unreachable sessions consuming capacity for up to 30 days.

2 open issues
2 resolved since last review

Review effort: Max

Comment thread src/auth.rs Resolved
Comment thread src/auth.rs Resolved
- `claim_redemption` now rechecks the TTL under the `authz` lock and answers
  `Expired`. The gate's snapshot can predate the TTL; a request that crossed
  it before claiming would otherwise start a registration that could only be
  refused at the mint (after II had granted it), or fail on a session a late
  attempt had just discarded with a confusing "no registration key" error.

- `Identities::discard_session` runs its removal in a task of its own, so a
  caller cut off while it waits for the session lock (a dropped request)
  still has the granted session discarded instead of left holding a slot for
  the rest of its grant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VP2vTJm9ipTPD18xW9HyVG
Copilot AI max review requested due to automatic review settings November 6, 2026 16:58

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed for a critical registration-expiry race that can revoke the prior grant while discarding the new session, leaving both connections unusable.

No open issues 🎉

2 resolved since last review

Review effort: Max

@aterga
aterga merged commit 6aed375 into main Nov 10, 2026
17 checks passed
aterga added a commit that referenced this pull request Nov 10, 2026
Brings the branch up to date with 27 commits on main. Two of them needed
changes on this side:

- #221 validates the PKCE code_challenge at /oauth/authorize, so the
  router test's branding round trip now authorizes with a well-formed S256
  challenge (the conflict in tests/routers.rs).
- #234 reads pending connects on tokio's clock and keeps expired ones
  around so the redeem gate can say "expired". branding_is_bound_to_the_session
  now runs on a paused clock: it walks a connect past CONNECT_TTL and checks
  that an expired but still-retained connect gets no branding, replacing
  the old checked_sub check that some hosts skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.

4 participants