# Migrate dgrijalva/jwt-go to golang-jwt in a Go Auth Service

Yes. An agent replaces the archived dgrijalva/jwt-go with golang-jwt v5, pins the refresh-token rules with tests first, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-jwt-go-to-golang-jwt/jwt-go/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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](https://getrush.ai/run/migrate-lazy-static-to-lazylock/lazy-static/)
- [Migrate a chi API from Logrus to log/slog](https://getrush.ai/run/migrate-logrus-to-slog/chi/)
- [Migrate a Sphinx Project From m2r to m2r2](https://getrush.ai/run/migrate-m2r-to-m2r2/m2r/)
- [Migrate a React App From Material-UI v4 to MUI v5](https://getrush.ai/run/migrate-material-ui-to-mui/material-ui/)
- [Migrate From mgo to the Official MongoDB Go Driver](https://getrush.ai/run/migrate-mgo-to-mongo-go-driver/mgo/)
- [Replace minimist With util.parseArgs in a Node.js CLI](https://getrush.ai/run/migrate-minimist-to-parseargs/minimist/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
