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
Check · Review · Land · Live done — Landed and live in production.
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.
shipped production is serving it deploy 7a0490b
7 earlier comments · 1 event
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):listOAuthGrantsalso 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\>".OAuthGrantgainsid, which is what Revoke names (the token id for a live grant, the family id for an idle one).tokenIdis now null for an idle grant, and there is a newidleflag. - Revoking (
src/core/oauth.ts,src/actions/oauth_grants.ts): a live grant still goes throughdeleteToken. An idle grant goes through the newendGrantFamily(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 useg.idand 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 sorefreshGrantrefuses the refresh token. It passes on this branch and fails against main's source. I changed the test'sidOfhelper and its terminal clean-up line to useid, 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/revokealready 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
<!-- 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
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.tsgives both the page and the terminal the same words. - Test: the new test in
test/oauth-grants.test.tsprunes 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
<!-- 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
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):listOAuthGrantsnow 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>".OAuthGrantgainsid, which is what Revoke names: the token id for a live grant, the family id for an idle one. For an idle granttokenIdis null and the newidleflag is set. - Revoking (
src/core/oauth.ts,src/actions/oauth_grants.ts): a live grant still goes throughdeleteToken. An idle grant goes through the newendGrantFamily(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 useg.idand the same words.docs/features/oauth-grants.mddescribes 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
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:
- 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.
- 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.
- 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>".
- 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.
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):listOAuthGrantsnow also returns a refresh family that has a live, unused refresh token but no access token. It shows as "idle · refresh good until <date>".OAuthGrantgainsid, which is what Revoke names: the token id for a live grant, the family id for an idle one. For an idle granttokenIdis null andidleis true. The module importsREFRESH_TTL_MSfromoauth.tsrather 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 throughdeleteToken. An idle grant goes through the newendGrantFamily(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 emitstoken.deletedwith{ 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 byg.idand show the idle row in the same words.docs/features/oauth-grants.mddescribes 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.deletedevent naming the family and the person who revoked it; - afterwards its refresh token fails.
- the grant is still listed as idle, with the new wording on the page and in
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
<!-- 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
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):listOAuthGrantsalso 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\>".OAuthGrantgainsid, which is what Revoke names: the token id for a live grant, the family id for an idle one.tokenIdis now null for an idle grant, and a newidleflag marks it. - Revoking (
src/core/oauth.ts,src/actions/oauth_grants.ts): a live grant still goes throughdeleteToken. An idle grant goes through the newendGrantFamily(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 useg.idand 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
refreshGrantrefuses the refresh token.
The test passes on this branch and fails against main's source. I changed the test's
idOfhelper and its terminal clean-up line to useid, 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
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.
Settings › Connected agents now lists and revokes OAuth grants by refresh family, so a grant stays visible after its access token expires. Before this,
pruneTokensdeleted 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.src/core/oauth_grants.ts):listOAuthGrantsalso 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\>".OAuthGrantgainsid, which is what Revoke names (the token id for a live grant, the family id for an idle one).tokenIdis now null for an idle grant, and there is a newidleflag.src/core/oauth.ts,src/actions/oauth_grants.ts): a live grant still goes throughdeleteToken. An idle grant goes through the newendGrantFamily(db, userId, family), which checks the family belongs to the person, then ends every refresh and access token in it.src/web/pages/grants.ts,src/tui/screens/oauthgrants.ts): both useg.idand the new words.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 sorefreshGrantrefuses the refresh token. It passes on this branch and fails against main's source. I changed the test'sidOfhelper and its terminal clean-up line to useid, because the grant's revoke identity moved there.What I chose not to do:
token.deleted, which matches what/oauth/revokealready does for such a family.Checks: the type check passes, and the gate rewrapped one comment (committed). Design lint is clean.
scripts/fast.tsnamed 2433 files, over its budget, so I ran the files that cover the change: everytest/oauth-*,tokens-oauth-clientand the tests that mention grants. 705 passed, 19 skipped, 0 failed. Thekeep_planandestimatetools were not available in this run, so the issue has no plan or estimate, and I have not ticked the finding on #14766.🤖 Generated with Claude Code
Closes #14904