Skip to content

Renew sessions with a refresh token, and revoke them on logout - #14

Merged
sahilkalgutkar merged 1 commit into
mainfrom
feature/token-refresh
Aug 31, 2026
Merged

sahilkalgutkar merged 1 commit into
mainfrom
feature/token-refresh

Conversation

@sahilkalgutkar

Copy link
Copy Markdown
Owner

login now requests offline_access, and an expiring session renews itself before the command that needed it runs.

$ modelforgectl whoami        # ID token has 55s left
sahil@example.com (user)      # renewed transparently; no sign-in

Without this, an expiring session means signing in mid-task — which in practice pushes people to a long-lived static token instead, trading an hour-long credential for a permanent one.

Renewal is proactive

Reacting to a 401 means the first call after expiry always fails once, and "it works on the second try" is a bad habit for a tool to teach. The 60-second margin covers clock skew against the provider and the time the request spends in flight — a token with two seconds left is not usable even though it has not technically expired. A credential that is still fresh never contacts the provider at all.

Rotation

A provider that issues a new refresh token on each use — what OAuth 2.1 tells them to do — retires the old one. Keeping only the original works perfectly until it doesn't, and the failure appears days later with no obvious cause. Three chained renewals are tested, because each depends on the previous one having been stored.

The concurrency bug this would otherwise have

Two commands at once both see a stale token and both refresh. Against a rotating provider the second invalidates the first, and whichever writes last leaves a credential the other already broke — a login that mysteriously dies when somebody runs two things in parallel.

Refresh happens under a file lock, and re-reads the credential inside it so a process that waited uses what the winner wrote rather than refreshing again with a token that has since been rotated away. Tested with eight concurrent workers against a rotating provider: exactly one refresh, and the session still works afterwards.

Writes are atomic (temp file + rename, same as the artifact store), because a crash partway through would leave a truncated token where a valid one was — failing in a way that looks like a server problem.

The credential format is now JSON. A bare token written by an older version is still read, so upgrading does not sign anybody out.

The compensating control

When I added the login flow I flagged that a refresh token on disk is a longer-lived secret than the one it replaces. It is — the ID token expires in an hour, a refresh token can be good for weeks, so a stolen credential file is worth considerably more than it was.

So this also makes logout mean something. It calls the provider's RFC 7009 revocation endpoint before deleting the file:

$ modelforgectl logout
revoked this session at the identity provider
removed the stored login from this machine

Verified by putting the deleted credential back afterwards — the provider rejects it, so the session is genuinely dead rather than merely forgotten locally. Previously logout could only say "this is not revocation"; now it usually is.

A provider with no revocation endpoint is reported plainly rather than glossed, because "logged out" quietly meaning two different things depending on the provider is how somebody ends up believing a credential is dead when it is not.

Verified live

Against a provider issuing genuinely short-lived (75s) ID tokens with rotation and revocation: login, a transparent renewal 20 seconds later once the token fell inside the skew, the rotated refresh token stored, then logout revoking, and the restored credential being refused.

Coverage

90.4% across internal/.

login now requests offline_access, and an expiring session is renewed before the
command that needed it runs. Without this an expiring session means signing in
mid-task, which in practice pushes people to a long-lived static token instead —
trading an hour-long credential for a permanent one.

Renewal is proactive rather than a reaction to a 401, because reacting means the
first call after expiry always fails once and "it works on the second try" is a
bad habit for a tool to teach. The 60-second margin covers clock skew against
the provider and the time a request spends in flight; a token with two seconds
left is not usable even though it has not technically expired. A credential that
is still fresh never contacts the provider.

Rotation is honoured. A provider that issues a new refresh token on each use
retires the old one, so keeping only the original works perfectly until it does
not — a failure that appears days later with no obvious cause. Three chained
renewals are tested because each depends on the previous one having been stored.

Refresh happens under a file lock. Two commands at once would both see a stale
token and both refresh, and against a rotating provider the second invalidates
the first, leaving whichever writes last with a credential the other already
broke. Eight concurrent workers now produce exactly one refresh.

Credential writes are atomic, temp file plus rename, for the same reason the
artifact store does it: a crash partway through must not leave a truncated token
where a valid one was, because that fails in a way that looks like a server
problem. The file format is now JSON, and a bare token written by an older
version is still read so that upgrading does not sign anybody out.

I flagged when adding the login flow that a refresh token on disk is a
longer-lived secret than the one it replaces. It is, so this also adds the
compensating control: logout calls the provider's RFC 7009 revocation endpoint
before deleting the local file. Verified by restoring the deleted credential
afterwards and watching the provider reject it. A provider with no revocation
endpoint is reported plainly rather than glossed, because "logged out" meaning
two different things depending on the provider is how somebody ends up believing
a credential is dead when it is not.

Coverage across internal/ is 90.4%.
@sahilkalgutkar
sahilkalgutkar merged commit 53b3f3b into main Aug 31, 2026
2 checks passed
@sahilkalgutkar
sahilkalgutkar deleted the feature/token-refresh branch August 31, 2026 20:03
@codecov

codecov Bot commented Aug 31, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 66.47727% with 59 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/cli/credential.go 60.00% 17 Missing and 15 partials ⚠️
internal/cli/login.go 74.44% 15 Missing and 8 partials ⚠️
internal/cli/cli.go 33.33% 3 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

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