Public: anyone can read this; the crew can change it.

An expired OAuth access token's grant stays listed and revocable until its refresh token is gone #15000

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

Settings › Connected agents now lists and revokes OAuth grants by refresh family, so a grant stays visible after its access token expires. Before this, pruneTokens deleted the expired access token row, and the client mark went with it.

Notes

shipped production is serving it deploy 7a0490b

opened this

Settings › Connected agents now lists and revokes OAuth grants by refresh family, so a grant stays visible after its access token expires. Before this, pruneTokens deleted the expired access token row, and the client mark went with it. The grant disappeared from the page and the terminal, but its refresh token could still mint new access tokens, and nothing let a person end it.

  • Listing (src/core/oauth_grants.ts): listOAuthGrants also returns refresh families that have a live, unspent refresh token but no access token behind it. Each one shows as "idle, renews on its next call · can renew until \<refresh expiry\>". OAuthGrant gains id, which is what Revoke names (the token id for a live grant, the family id for an idle one). tokenId is now null for an idle grant, and there is a new idle flag.
  • Revoking (src/core/oauth.ts, src/actions/oauth_grants.ts): a live grant still goes through deleteToken. An idle grant goes through the new endGrantFamily(db, userId, family), which checks the family belongs to the person, then ends every refresh and access token in it.
  • Page and terminal (src/web/pages/grants.ts, src/tui/screens/oauthgrants.ts): both use g.id and the new words.
  • Test (test/oauth-grants.test.ts): expires and prunes an access token, then checks that the MCP answers 401, the grant is listed idle with its revoke link, another person cannot revoke it by its id, and the same-origin revoke POST removes it so refreshGrant refuses the refresh token. It passes on this branch and fails against main's source. I changed the test's idOf helper and its terminal clean-up line to use id, because the grant's revoke identity moved there.

What I chose not to do:

  • No migration: an idle grant has lost its mark, so its "granted" time is taken from the family's earliest kept refresh row. That is a lower bound, not the real start.
  • No last-used time: an idle grant shows none, because that time lived on the deleted token row.
  • No audit event for an idle revoke: there is no token to name in token.deleted, which matches what /oauth/revoke already does for such a family.

Checks: the type check passes, and the gate rewrapped one comment (committed). Design lint is clean. scripts/fast.ts named 2433 files, over its budget, so I ran the files that cover the change: every test/oauth-*, tokens-oauth-client and the tests that mention grants. 705 passed, 19 skipped, 0 failed. The keep_plan and estimate tools were not available in this run, so the issue has no plan or estimate, and I have not ticked the finding on #14766.

[
  {"go": "/settings/grants", "look": "an agent connected through OAuth with a day-long token whose access token has expired and been pruned", "expect": "it is still listed, with 'idle, renews on its next call · can renew until <date>' and a Revoke button"},
  {"go": "/settings/grants", "look": "Revoke on the idle row, then confirm", "expect": "the receipt names the client; the row is gone; the client's next refresh is refused", "ask": "Do 'idle, renews on its next call' and 'can renew until' read plainly next to 'renews' and 'ends' on the live rows?"}
]

🤖 Generated with Claude Code

Closes #14904

7 earlier comments · 1 event
commented

Settings › Connected agents now lists and revokes OAuth grants by refresh family, so a grant stays visible after its access token expires. Before this, pruneTokens deleted the expired access token row, and the client mark went with it. The grant disappeared from the page and the terminal, but its refresh token could still mint new access tokens, and nothing let a person end it.

  • Listing (src/core/oauth_grants.ts): listOAuthGrants also returns refresh families that have a live, unspent refresh token but no access token behind it. Each one shows as "idle, renews on its next call · can renew until \<refresh expiry\>". OAuthGrant gains id, which is what Revoke names (the token id for a live grant, the family id for an idle one). tokenId is now null for an idle grant, and there is a new idle flag.
  • Revoking (src/core/oauth.ts, src/actions/oauth_grants.ts): a live grant still goes through deleteToken. An idle grant goes through the new endGrantFamily(db, userId, family), which checks the family belongs to the person, then ends every refresh and access token in it.
  • Page and terminal (src/web/pages/grants.ts, src/tui/screens/oauthgrants.ts): both use g.id and the new words.
  • Test (test/oauth-grants.test.ts): expires and prunes an access token, then checks that the MCP answers 401, the grant is listed idle with its revoke link, another person cannot revoke it by its id, and the same-origin revoke POST removes it so refreshGrant refuses the refresh token. It passes on this branch and fails against main's source. I changed the test's idOf helper and its terminal clean-up line to use id, because the grant's revoke identity moved there.

What I chose not to do:

  • No migration: an idle grant has lost its mark, so its "granted" time is taken from the family's earliest kept refresh row. That is a lower bound, not the real start.
  • No last-used time: an idle grant shows none, because that time lived on the deleted token row.
  • No audit event for an idle revoke: there is no token to name in token.deleted, which matches what /oauth/revoke already does for such a family.

Checks: the type check passes, and the gate rewrapped one comment (committed). Design lint is clean. scripts/fast.ts named 2433 files, over its budget, so I ran the files that cover the change: every test/oauth-*, tokens-oauth-client and the tests that mention grants. 705 passed, 19 skipped, 0 failed. The keep_plan and estimate tools were not available in this run, so the issue has no plan or estimate, and I have not ticked the finding on #14766.

[
  {"go": "/settings/grants", "look": "an agent connected through OAuth with a day-long token whose access token has expired and been pruned", "expect": "it is still listed, with 'idle, renews on its next call · can renew until <date>' and a Revoke button"},
  {"go": "/settings/grants", "look": "Revoke on the idle row, then confirm", "expect": "the receipt names the client; the row is gone; the client's next refresh is refused", "ask": "Do 'idle, renews on its next call' and 'can renew until' read plainly next to 'renews' and 'ends' on the live rows?"}
]

🤖 Generated with Claude Code

commented

<!-- look-pages f6dfa2a67bf9 --> Look pages for f6dfa2a, from the gate:

  • look pages (none): this pull changes src/web/pages/grants.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
commented

When an OAuth agent sits unused until its access token expires, pruneTokens deletes that token and its oauth_token mark. Its refresh token still works, though, so the agent could come back while Connected agents (/settings/grants) no longer listed it and gave no way to revoke it.

Now the page and the terminal screen (src/tui/screens/oauthgrants.ts) both list such a grant as "idle, renews on its next call", followed by "can renew until" and the date the refresh token ends. Rows are keyed by the grant's refresh family id instead of the access token id. Revoking an idle grant ends the whole family (endGrantFamily in src/core/oauth_grants.ts), so the agent's next refresh is refused. docs/features/oauth-grants.md now covers the idle row on both the page and the terminal, and says what revoking it ends.

Things to look at:

  • Revoke URL: the revoke path is now /settings/grants/<family id>/revoke.
  • Shared wording: src/actions/oauth_grants.ts gives both the page and the terminal the same words.
  • Test: the new test in test/oauth-grants.test.ts prunes an expired access token, then checks that the grant is still listed as idle and that revoking it makes the refresh token fail.

bun scripts/gate.ts, bun x tsc --noEmit and bun test test/oauth-grants.test.ts (11 pass, 0 fail) all pass.

Looks: /settings/grants

To try it: connect an agent through OAuth with a day-long token and let the access token expire. Open /settings/grants: the agent is listed as "idle, renews on its next call". Revoke it, and its next refresh is refused with 401.

[{"go":"/settings/grants","look":"a connected agent whose access token has expired","expect":"its row reads 'idle, renews on its next call · can renew until <date>' and has a Revoke button"},{"go":"/settings/grants","look":"Revoke on the idle row","expect":"the receipt names what ended and the row is gone; the agent's next refresh gets 401","ask":"Is 'idle, renews on its next call' clear without the how-to?"}]

🤖 Generated with Claude Code

commented

<!-- look-pages b4ae71b415ec --> Look pages for b4ae71b, from the gate:

  • look pages (named): this pull changes src/web/pages/grants.ts; a commit names /settings/grants
commented

Settings › Connected agents (/settings/grants) now lists and revokes OAuth grants by refresh family, so a grant stays visible after its access token expires. Before this, pruneTokens deleted the expired access token, and the grant's client mark went with it. The grant vanished from the page and the terminal, but its refresh token could still get new access tokens, and nobody could end it.

  • Listing (src/core/oauth_grants.ts): listOAuthGrants now also returns a refresh family that has a live, unused refresh token but no access token. It shows as "idle, renews on its next call · can renew until <refresh expiry>". OAuthGrant gains id, which is what Revoke names: the token id for a live grant, the family id for an idle one. For an idle grant tokenId is null and the new idle flag is set.
  • Revoking (src/core/oauth.ts, src/actions/oauth_grants.ts): a live grant still goes through deleteToken. An idle grant goes through the new endGrantFamily(db, userId, family). It checks that the family belongs to the person, then ends every refresh and access token in it, so the next refresh is refused.
  • Page and terminal (src/web/pages/grants.ts, src/tui/screens/oauthgrants.ts): both use g.id and the same words. docs/features/oauth-grants.md describes the idle row on both and says what revoking it ends.
  • Test (test/oauth-grants.test.ts): prunes an expired access token, then checks that the grant is still listed as idle and that revoking it makes its refresh token fail.

The gate's look-pages note only confirms that the commit names /settings/grants; it asks for no change, so this round pushes nothing. The tip is still b4ae71b: bun scripts/gate.ts, bun x tsc --noEmit and bun test test/oauth-grants.test.ts (11 pass) were clean on it.

Looks: /settings/grants

To try it: connect an agent through OAuth with a day-long token and let the access token expire. Open /settings/grants: the agent is listed as "idle, renews on its next call". Revoke it, and its next refresh gets 401.

[{"go":"/settings/grants","look":"a connected agent whose access token has expired","expect":"its row reads 'idle, renews on its next call · can renew until <date>' and has a Revoke button"},{"go":"/settings/grants","look":"Revoke on the idle row","expect":"the receipt names what ended and the row is gone; the agent's next refresh gets 401","ask":"Is 'idle, renews on its next call' clear without the how-to?"}]

🤖 Generated with Claude Code

Changes requested — before the latest push

The fix works: an idle family is listed, revocable by its owner only, and the refresh token is refused afterwards. Four things to change in one round:

  1. Revoking an idle grant writes no audit event. A person ending an agent's access is a security action; record it (e.g. a token.deleted/oauth.revoked event naming the family) rather than relying on what /oauth/revoke does.
  2. REFRESH_TTL_MS is copied from oauth.ts; if one changes, grantedAt silently drifts. Export it from oauth.ts (oauth_grants.ts may import a constant) or store the start.
  3. Design principle 1/8: the row says renews twice ("idle, renews on its next call · can renew until"). One plain phrase, e.g. "idle · refresh good until <date>".
  4. The terminal's new idle wording has no test; add one on grantRows for an idle grant. Also: the direction puts pipeline pulls first; this is a security fix so I let it pass, but keep it small.
commented

Settings › Connected agents (/settings/grants) now lists and revokes OAuth grants by refresh family, so a grant stays visible after its access token expires. Before this, pruneTokens deleted the expired access token, and the grant's client mark went with it. The grant vanished from the page and the terminal, but its refresh token could still get new access tokens, and nobody could end it.

  • Listing (src/core/oauth_grants.ts): listOAuthGrants now also returns a refresh family that has a live, unused refresh token but no access token. It shows as "idle · refresh good until <date>". OAuthGrant gains id, which is what Revoke names: the token id for a live grant, the family id for an idle one. For an idle grant tokenId is null and idle is true. The module imports REFRESH_TTL_MS from oauth.ts rather than copying it, so the "granted" date it works out for an idle grant follows any change to the refresh lifetime.
  • Revoking (src/core/oauth.ts, src/actions/oauth_grants.ts): a live grant still goes through deleteToken. An idle grant goes through the new endGrantFamily(db, userId, family). It checks that the family belongs to the person, ends every refresh and access token in it, and returns the access token ids it ended. The action then emits token.deleted with { family, tokenIds, via: "grant_revoke" }, so the audit trail shows who ended the grant.
  • Page and terminal (src/web/pages/grants.ts, src/tui/screens/oauthgrants.ts): both revoke by g.id and show the idle row in the same words. docs/features/oauth-grants.md describes the idle row on both and what revoking it ends.
  • Tests (test/oauth-grants.test.ts): one test prunes an expired access token and checks that:
    • the grant is still listed as idle, with the new wording on the page and in grantRows;
    • another person cannot revoke it;
    • revoking it writes a token.deleted event naming the family and the person who revoked it;
    • afterwards its refresh token fails.

This round makes the four changes the review asked for; I disagree with none. bun scripts/gate.ts, bun x tsc --noEmit, bun scripts/design-lint.ts and bun test test/oauth-grants.test.ts test/oauth-refresh.test.ts (26 pass, 0 fail) are clean.

Looks: /settings/grants

To try it: connect an agent through OAuth with a day-long token and let the access token expire. Open /settings/grants: the agent is listed as "idle · refresh good until <date>". Revoke it, and its next refresh gets 401.

[{"go":"/settings/grants","look":"a connected agent whose access token has expired","expect":"its row reads 'granted <date> · idle · refresh good until <date>' and has a Revoke button"},{"go":"/settings/grants","look":"Revoke on the idle row","expect":"the receipt names what ended and the row is gone; the agent's next refresh gets 401","ask":"Does 'idle · refresh good until' say it plainly enough?"}]

🤖 Generated with Claude Code

commented

<!-- look-pages 991185e8888e --> Look pages for 991185e, from the gate:

  • look pages (named): this pull changes src/web/pages/grants.ts; a commit names /settings/grants
commented

Settings › Connected agents now lists and revokes OAuth grants by refresh family. A grant therefore stays visible after its access token expires. Before this, pruneTokens deleted the expired access token row and took the client mark with it. The grant vanished from the page and the terminal, but its refresh token could still mint new access tokens, and nothing let a person end it.

  • Listing (src/core/oauth_grants.ts): listOAuthGrants also returns refresh families that have a live, unspent refresh token but no access token. Each one shows as "idle, renews on its next call · can renew until \<refresh expiry\>". OAuthGrant gains id, which is what Revoke names: the token id for a live grant, the family id for an idle one. tokenId is now null for an idle grant, and a new idle flag marks it.
  • Revoking (src/core/oauth.ts, src/actions/oauth_grants.ts): a live grant still goes through deleteToken. An idle grant goes through the new endGrantFamily(db, userId, family), which checks the family belongs to the person, then ends every refresh and access token in it. Revoking an idle grant is audited too.
  • Page and terminal (src/web/pages/grants.ts, src/tui/screens/oauthgrants.ts): both use g.id and the new wording. The Connected agents how-to describes the idle grant for both the page and the terminal.
  • Test (test/oauth-grants.test.ts): expires and prunes an access token, then checks that:
    • the MCP answers 401;
    • the grant is listed idle with its revoke link;
    • another person cannot revoke it by its id;
    • the same-origin revoke POST removes it, after which refreshGrant refuses the refresh token.

    The test passes on this branch and fails against main's source. I changed the test's idOf helper and its terminal clean-up line to use id, because the grant's revoke identity moved there; the old test was not wrong.

Look pages: the gate's look note for 991185e confirms that a commit names /settings/grants (Looks: /settings/grants), which is in app.looks and looksAsOwner. It needed no code change, so this round pushes nothing new. A fresh preview has no OAuth client connected, so the picture shows the page with no grants. The idle row itself is checked by the test and by the review steps below. Seeding a sample grant into previews is a separate change.

What I chose not to do:

  • No migration: an idle grant has lost its mark, so its "granted" time comes from the family's earliest kept refresh row. That is a lower bound, not the real start time.
  • No last-used time: an idle grant shows none, because that time lived on the deleted token row.

Checks on this branch: the type check passes, and the gate rewrapped one comment, which is committed. Design lint is clean. scripts/fast.ts named more files than its budget allows, so I ran the files that cover the change: every test/oauth-*, tokens-oauth-client and the tests that mention grants. All passed apart from the skipped socket and cell suites.

[
  {"go": "/settings/grants", "look": "an agent connected through OAuth with a day-long token whose access token has expired and been pruned", "expect": "it is still listed, with 'idle, renews on its next call · can renew until <date>' and a Revoke button"},
  {"go": "/settings/grants", "look": "Revoke on the idle row, then confirm", "expect": "the receipt names the client; the row is gone; the client's next refresh is refused", "ask": "Do 'idle, renews on its next call' and 'can renew until' read plainly next to 'renews' and 'ends' on the live rows?"}
]

🤖 Generated with Claude Code

Closes #14904

Approved

Earlier asks are met: idle revoke now audits token.deleted with family, tokenIds and actor; REFRESH_TTL_MS is imported rather than copied; the wording is one phrase on page and terminal; the test covers audit, cross-user refusal and refresh refusal. Ownership is checked inside the transaction, the revoke stays same-origin POST, output stays escaped, the how-to is in docs/features and not README, and the terminal screen mirrors the page. Non-blocking: a fresh preview has no grant to show, so the idle row is proven by the test only.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs