GourdianToken v2.0.0: What's New and How to Migrate

Today I released GourdianToken v2.0.0 — the first major version bump for my JWT lifecycle library for Go since I started building it in March 2025. v2 is a breaking release, but a deliberately small one: two breaking changes, both mechanical to migrate, bundled with a set of additions and bug fixes that had been accumulating on the v1 branch for months.

If you just want the upgrade recipe, jump to the migration steps below — for most codebases it's a ten-minute change. The rest of this post walks through why each change was made.

What GourdianToken does

GourdianToken handles the complete JWT lifecycle behind one interface: create, verify, revoke, and rotate, for both access and refresh tokens. Storage is pluggable — in-memory, Redis, GORM (Postgres/MySQL/SQLite), MongoDB, or fully stateless — and eleven signing algorithms are supported, from HS256 to EdDSA. Refresh rotation ships with replay-attack detection built in.

The two breaking changes

Why identifiers became opaque strings

v1 required uuid.UUID for user and session identifiers. That felt rigorous when I wrote it, but in practice it was an over-constraint: the library never relied on UUID semantics — it just serialized the value into a claim. Meanwhile every consumer whose user IDs were strings, integers, or composite keys had to convert them into UUID shape, and every consumer had to import google/uuid whether they wanted to or not.

v2 treats identifiers as opaque. userID must be a non-empty string; sessionID may even be empty for sessionless tokens. Importantly, this is a widening of accepted input, not a narrowing — every previously-valid UUID string still works. And since google/uuid is now only used internally (to generate the jti token ID), consumers who pass their own identifiers no longer need that dependency at all.

1// v1.x — UUIDs required, .String() calls everywhere
2userID := uuid.MustParse(user.ID)
3token, err := maker.CreateAccessToken(ctx, userID, user.Name, roles, sessionID)
4log.Println("issued for", claims.Subject.String())
5
6// v2.0.0 — identifiers are opaque strings
7token, err := maker.CreateAccessToken(ctx, user.ID, user.Name, roles, sessionID)
8log.Println("issued for", claims.Subject) // already a string

What's new

• Sentinel errors for errors.Is: ErrTokenRevoked, ErrTokenRotated, ErrTokenExpired, ErrInvalidSignature, ErrInvalidToken, ErrInvalidClaims, ErrTokenRepositoryRequired, ErrMissingExpClaim, and ErrTokenMaxLifetimeExceeded. Existing error message text is preserved ahead of the wrapped sentinel, so callers that were string-matching keep working unchanged.
• GourdianTokenMakerCloser — an optional interface with an idempotent Close() that stops the background cleanup goroutines. It's a separate interface rather than an addition to GourdianTokenMaker, so external implementers of the main interface don't break.
• WithLogger functional option to control how cleanup goroutines report errors (default stays fmt.Printf-compatible).
• Exported claim-key constants (ClaimIssuer, ClaimAudience, ClaimNotBefore, ClaimMaxLifetimeExpiry) replacing bare string literals.

1claims, err := maker.VerifyRefreshToken(ctx, token)
2switch {
3case errors.Is(err, gourdiantoken.ErrTokenExpired):
4    // normal expiry — client should re-authenticate
5case errors.Is(err, gourdiantoken.ErrTokenRotated):
6    // replay detected — treat as possible theft
7case errors.Is(err, gourdiantoken.ErrTokenRevoked):
8    // logged out — reject
9}

The bug fixes worth reading about

Three of the fixes in this release are interesting enough that they get their own posts in this series. The short versions:

• RotateRefreshToken could permanently lock a user out: the old token was marked rotated before the new one was created, so a creation failure left no valid token behind. v2 creates the new token first. (Full war story in part 3 of this series.)
• The MongoDB backend detected duplicate-key errors inside the transaction callback, which made commit behavior driver-version-dependent. Detection moved to the transaction boundary. (Covered in part 2.)
• RedisTokenRepository.Close() wasn't idempotent — a second call surfaced go-redis's "redis: client is closed". Now guarded with sync.Once.
• A dead-err bug in the verify and revoke paths produced the gloriously unhelpful message "invalid token: <nil>" — an already-nil-checked err was reused in a later error message.
• A doc comment claimed cleanup goroutines were stopped by garbage-collection finalization. They weren't (and can't be) — the real fix is the new Close().

Migration steps

1. 1Update the module: go get github.com/gourdian25/gourdiantoken/v2@latest, then change every import to the /v2 path.
2. 2Pass strings where you previously passed uuid.UUID to CreateAccessToken / CreateRefreshToken. If your IDs were already UUIDs, pass their string form — the values are still accepted.
3. 3Delete .String() calls on claims.Subject, claims.SessionID, and response Subject/SessionID fields — they're already strings, and the compiler will point at every one.
4. 4Optionally drop google/uuid from your go.mod if the library was your only reason for importing it.
5. 5Optionally adopt the new toys: switch string-matched error checks to errors.Is, and call Close() on shutdown via the GourdianTokenMakerCloser interface.

Known issues, flagged honestly

Three inconsistencies are documented in the changelog but deliberately not fixed in this release: the revoke paths' internal jwt.Parse keyfuncs don't re-check the signing algorithm the way the verify paths do (low severity — the typed verification key already bounds algorithm-confusion attacks); the Mongo factory takes an extra positional transactionsEnabled bool that breaks the shape shared by the other factories; and MongoTokenRepository.Close(ctx) has a different signature than the other backends' bare Close(). Each needs its own design decision, and I'd rather ship them as known issues than rush unreviewed changes into a major release.

GourdianToken is MIT-licensed and on GitHub at gourdian25/gourdiantoken. The next two posts in this series dig into the two hardest problems the library solves: making refresh rotation race-free on four very different storage backends, and the ordering bug in rotation that could have locked users out for good.