What the agent does
The agent starts with what the service does with tokens, because the library swap is small and the rules around it are not. In a service like ashishjuyal/banking-auth, go.mod declares go 1.15 and requires github.com/dgrijalva/jwt-go v3.2.0+incompatible, and five files import it: domain/authToken.go, domain/claims.go, domain/login.go, dto/refreshTokenRequest.go and service/authService.go. go test ./... prints [no test files] for all five packages. So before changing an import the agent writes tests for Refresh and Verify in the service package, with a fake AuthRepository in place of MySQL: an expired access token with a stored refresh token gets a new one, an expired token signed with another key gets invalid token, a live token gets cannot generate a new access token until the current one expires, and a string that is not a token gets invalid token. All four hold on the old library.
Then it moves to github.com/golang-jwt/jwt/v5. go get raises the go line from 1.15 to 1.21, because v5.3.1, the release current when this page was written, needs it, and at that level go.mod also starts listing indirect requirements. The compiler then reports the work one package at a time. domain fails first with undefined: jwt.StandardClaims, at six places in claims.go and login.go: both claims structs embed it and four literals fill ExpiresAt with time.Now().Add(...).Unix(). The embedded type becomes jwt.RegisteredClaims and each expiry becomes jwt.NewNumericDate(...). dto fails next with undefined: jwt.ValidationError, the type IsAccessTokenValid returns, so that method returns a plain error. service fails last on jwt.ValidationErrorExpired.
That last line decides who may refresh. Refresh issues a new access token only when vErr.Errors == jwt.ValidationErrorExpired, an exact comparison. On the old library an expired token signed with the wrong key carries Errors 20, expired plus invalid signature, so the comparison with 16 turns it away. In v5 the replacement is errors.Is(err, jwt.ErrTokenExpired), and it is safe for a different reason: v5 checks the signature before the claims, so the same forged token reports only ErrTokenSignatureInvalid. The agent does not argue this from documentation. The forged-and-expired test it wrote first has to pass on both sides of the change. It also adds jwt.WithValidMethods([]string{"HS256"}) to the three parse calls, since none of the key functions looks at token.Method.
Last, it checks what callers see. A token built with StandardClaims and one built with RegisteredClaims for the same claims and expiry are the same string, so tokens issued before a deploy verify after it. Error text is not the same. Verify copies err.Error() into the message field of its JSON answer, so an expired token changes from token is expired by 1h0m0s to token has invalid claims: token is expired, and a bad signature from signature is invalid to token signature is invalid: signature is invalid. The agent prints both columns instead of deciding for you whether a client depends on the old wording.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Replace github.com/dgrijalva/jwt-go with github.com/golang-jwt/jwt/v5 in this Go service. First read go.mod and every file that imports the old package, and list each type, constant and function used from it. Run go build ./... and go test ./... and say which packages have no tests. Before changing any import, write tests for the token refresh and verify paths with a fake repository in place of the database: an expired access token with a stored refresh token, an expired token signed with a different key, a token that has not expired, and a string that is not a token. Run them on the old library and keep the output. Then switch to v5: StandardClaims to RegisteredClaims with NumericDate expiries, ValidationError checks to errors.Is with the v5 sentinel errors, and WithValidMethods on every parse call. Do not weaken the rule that only an expired, correctly signed token may be refreshed. Run the same tests again. Compare a token signed before and after for identical claims, and list every error string a handler returns to clients that changed. Run govulncheck before and after. Report the new go directive and any CI or image file that pins an older Go. Open a pull request with every command and its output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes go.mod, go.sum and the five source files, and adds one test file in service. domain/authToken.go changes on its import line only. The description lists what was used from the old package and its v5 counterpart, the three rounds of compiler errors, the test output on the old library and on the new one, and a two-column table of the error strings clients receive. It quotes govulncheck before the change, which names GO-2020-0017 against github.com/dgrijalva/jwt-go@v3.2.0+incompatible with Fixed in: N/A, and after.
A reviewer reads the refresh condition first and the test that guards it second, then the go line: 1.21 is a floor for every build image and CI job that compiles this service, and the description names any file that pins something older. Two things are left alone and said so. The signing secret is still the constant HMAC_SAMPLE_SECRET in domain/claims.go, and the service still has no tests for login against a real database. Both are separate changes.
Run it on every service still importing dgrijalva/jwt-go
The old module is archived, so the job is the same in every repository that still requires it. Find them with a code search for dgrijalva/jwt-go in go.mod, then send this body to POST /o/{org}/sessions once per repository, with that repository in resources and a request_id that is a UUID v5 of its full name, so sending the batch again starts nothing twice.
A key runs up to its max_concurrent at once and the rest wait as queued, so a batch needs no retry loop. If the key has a webhook_url, each run posts run.completed there when its turn ends, and the session read carries the pull request to review.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
An authentication change is judged by cases, and the cases here did not exist until the agent wrote them. On Rush the old library and the new one are both compiled and tested in the run's own sandbox, and the output of each go test is kept with the run, so the claim that a forged, expired token is still refused is a quoted result and not a sentence in a description.
The parts that are easy to miss are found by commands too. The jump of the go directive comes from go get, the changed error strings from running the handlers, and the advisory from govulncheck. A find-and-replace of the import path in an editor reaches the first compiler error and tells you none of the three.
Frequently asked questions
Can I move to golang-jwt v4 instead of v5?
Yes, and it is the smaller step. v4 keeps StandardClaims and ValidationError, so changing the import path is enough for this code to compile. v5 is the current major version, which is why the request above asks for it; change one line of the prompt to stop at v4.
Will tokens issued before the deploy still be accepted?
Yes. The claim names and the HS256 signature do not change, and a token signed by either library for the same claims is the same string. The agent shows this by signing with both and comparing, and by parsing an old-library token with v5.
Why does go.mod change so much for one dependency?
golang-jwt v5.3.1 declares Go 1.21, so go get lifts the go line from 1.15. From Go 1.17 on, go.mod lists indirect requirements, so a block of them appears that was only implied before. The pull request explains this so the diff is not mistaken for new dependencies.
Does v5 validate anything the old library did not?
It validates differently. It checks the signature before the claims, it no longer rejects a token because of its iat, and it offers options such as WithValidMethods and WithExpirationRequired. A token with no exp is accepted by default in both versions, so the agent reports that and leaves the choice to you.
More jobs like this: Upgrade dependencies weekly
- Replace lazy_static With std::sync::LazyLock in a Rust Project (lazy_static)
- Migrate a chi API from Logrus to log/slog (chi)
- Migrate a Sphinx Project From m2r to m2r2 (m2r)
- Migrate a React App From Material-UI v4 to MUI v5 (Material-UI)
- Migrate From mgo to the Official MongoDB Go Driver (mgo)
- Replace minimist With util.parseArgs in a Node.js CLI (minimist)