# pardnchiu/go-jwt

> Go JWT authentication library: ES256 JWT tokens, Redis-backed refresh token rotation and revocation, device binding, Gin middleware. By 邱敬幃 Pardn Chiu.

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd, Taiwan · Infrastructure Engineering. Source: https://github.com/pardnchiu/go-jwt

Full text in one file: [English](https://go-jwt.pardn.io/llms-full.txt) · [中文](https://go-jwt.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://go-jwt.pardn.io/index.md): Go JWT authentication library: ES256 JWT tokens, Redis-backed refresh token rotation and revocation, device binding, Gin middleware. By 邱敬幃 Pardn Chiu.
- [Getting Started](https://go-jwt.pardn.io/getting-started.md): Install go-jwt, start Redis, and run a net/http server that logs in, verifies, and logs out with ES256 JWTs in a few minutes.

## Concepts

- [Architecture](https://go-jwt.pardn.io/architecture.md): One diagram of go-jwt layers: middleware, Create/Verify/refresh/Revoke, fingerprinting, cookies, PEM keys, and Redis state.
- [Token Model](https://go-jwt.pardn.io/core-concepts.md): How go-jwt uses an ES256 Access Token, a SHA-256 Refresh ID, and a Redis JTI whitelist, including JWT claims and RefreshData fields.
- [Verification Flow](https://go-jwt.pardn.io/verification.md): The nine checks Verify runs in order: revocation, signature, nbf/iat, Refresh ID and fingerprint binding, JTI whitelist, with failure codes.
- [Transparent Refresh](https://go-jwt.pardn.io/refresh.md): How expired JWTs refresh transparently: Redis lock, CheckAuth, re-sign versus full refresh token rotation by MaxVersion and TTL, and 429 handling.
- [Revocation](https://go-jwt.pardn.io/revocation.md): How Revoke logs out: cleared cookies, Redis revoke record for the Access Token, a 5-second Refresh ID grace window, and edge cases.
- [Device Fingerprint](https://go-jwt.pardn.io/device-fingerprint.md): How go-jwt derives a SHA-256 device fingerprint from User-Agent and device ID, why curl needs X-Device-FP, and binding trade-offs.

## Integration

- [Middleware](https://go-jwt.pardn.io/middleware.md): Gin and net/http JWT middleware: failure responses, reading Auth from context, the "user" context key, and scope checks.
- [Client Integration](https://go-jwt.pardn.io/client-integration.md): Cookies and headers go-jwt reads and sets, plus browser, mobile, and API client setup including full-reissue cookies and 429 retries.

## Reference

- [Configuration](https://go-jwt.pardn.io/configuration.md): Config, Redis, Option, and Cookie fields with defaults: token lifetimes, cookie names, MaxVersion, RefreshTTL, and syslog logging.
- [Key Management](https://go-jwt.pardn.io/key-management.md): ES256 key loading order, PKCS#8/PKIX format, P-256 requirement, OpenSSL commands, shared keys across instances, and rotation.
- [API Reference](https://go-jwt.pardn.io/api-reference.md): Every exported go-jwt/core function, JWTAuth method, and type: New, Create, Verify, Revoke, middleware, JWTAuthResult, Auth.
- [Status Codes and Error Tags](https://go-jwt.pardn.io/error-codes.md): Every JWTAuthResult StatusCode and ErrorTag pair (400, 401, 429, 500) with its trigger, plus how to branch on tags.
- [Redis Keys](https://go-jwt.pardn.io/redis-keys.md): The four Redis keys go-jwt writes (refresh, jti, lock, revoke), their TTLs, per-operation reads and writes, and the unlock script.
- [Removed API](https://go-jwt.pardn.io/removed-api.md): Symbols removed from go-jwt by version, from v0.4.0 to the v1.0.3 move to the core subpackage, with replacements.

## Symbols

Exported symbol -> page that documents it.

- `Auth` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Middleware](https://go-jwt.pardn.io/middleware.md)
- `Config` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Architecture](https://go-jwt.pardn.io/architecture.md)
- `Cookie` (core): [Configuration](https://go-jwt.pardn.io/configuration.md), [Token Model](https://go-jwt.pardn.io/core-concepts.md)
- `File` (core): [Configuration](https://go-jwt.pardn.io/configuration.md)
- `GetAuthDataFromGinContext` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Architecture](https://go-jwt.pardn.io/architecture.md)
- `GetAuthDataFromHTTPRequest` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Middleware](https://go-jwt.pardn.io/middleware.md)
- `JWTAuth` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Getting Started](https://go-jwt.pardn.io/getting-started.md)
- `JWTAuthResult` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Architecture](https://go-jwt.pardn.io/architecture.md)
- `New` (core): [Configuration](https://go-jwt.pardn.io/configuration.md), [Getting Started](https://go-jwt.pardn.io/getting-started.md)
- `Option` (core): [Key Management](https://go-jwt.pardn.io/key-management.md)
- `Pem` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md)
- `Redis` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Verification Flow](https://go-jwt.pardn.io/verification.md)
- `RefreshData` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md), [Token Model](https://go-jwt.pardn.io/core-concepts.md)
- `RefreshId` (core): [API Reference](https://go-jwt.pardn.io/api-reference.md)

## 中文文件

- [首頁](https://go-jwt.pardn.io/zh/index.md): Go JWT Token 驗證函式庫：Redis 管理 ES256 JWT 與 Refresh Token 輪替、撤銷、裝置綁定及 Gin 中介層，作者邱敬幃。
- [快速開始](https://go-jwt.pardn.io/zh/getting-started.md): 安裝 go-jwt、啟動 Redis，幾分鐘內跑起以 ES256 JWT 登入、驗證與登出的 net/http 伺服器。
- [架構](https://go-jwt.pardn.io/zh/architecture.md): 一張圖看懂 go-jwt 分層：中介層、Create／Verify／刷新／Revoke、裝置指紋、Cookie、金鑰與 Redis。
- [Token 模型](https://go-jwt.pardn.io/zh/core-concepts.md): go-jwt 如何組合 ES256 Access Token、SHA-256 Refresh ID 與 Redis JTI 白名單，以及 JWT claims。
- [驗證流程](https://go-jwt.pardn.io/zh/verification.md): Verify 依序執行的九項檢查：撤銷、簽章、nbf／iat、Refresh ID 與指紋綁定、JTI 白名單，以及各自的錯誤碼。
- [透明刷新](https://go-jwt.pardn.io/zh/refresh.md): JWT 過期如何透明刷新：Redis 鎖、CheckAuth、依 MaxVersion 與 TTL 決定重簽或 Refresh Token 輪替。
- [撤銷](https://go-jwt.pardn.io/zh/revocation.md): Revoke 如何登出：清除 Cookie、寫入 Access Token 撤銷紀錄、Refresh ID 5 秒緩衝期與邊界情境。
- [裝置指紋](https://go-jwt.pardn.io/zh/device-fingerprint.md): go-jwt 如何由 User-Agent 與裝置 ID 算出 SHA-256 指紋、curl 為何需要 X-Device-FP，以及綁定強度取捨。
- [中介層](https://go-jwt.pardn.io/zh/middleware.md): Gin 與 net/http 的 JWT 中介層：失敗回應、從 context 取出 Auth、"user" context key 與 scope 授權。
- [客戶端整合](https://go-jwt.pardn.io/zh/client-integration.md): go-jwt 讀寫的 Cookie 與 header，以及瀏覽器、行動 App、API 客戶端的串接方式與 429 重送。
- [設定](https://go-jwt.pardn.io/zh/configuration.md): Config、Redis、Option、Cookie 欄位與預設值：Token 有效期、Cookie 名稱、MaxVersion、RefreshTTL。
- [金鑰管理](https://go-jwt.pardn.io/zh/key-management.md): ES256 金鑰載入順序、PKCS#8／PKIX 格式、P-256 限制、OpenSSL 指令、多實例共用金鑰與輪替。
- [API 參考](https://go-jwt.pardn.io/zh/api-reference.md): go-jwt/core 所有匯出函式、方法與型別：New、Create、Verify、Revoke、中介層、JWTAuthResult。
- [狀態碼與錯誤標籤](https://go-jwt.pardn.io/zh/error-codes.md): JWTAuthResult 每組 StatusCode 與 ErrorTag（400、401、429、500）的觸發情境，以及依標籤分流的寫法。
- [Redis Key](https://go-jwt.pardn.io/zh/redis-keys.md): go-jwt 寫入的四種 Redis key（refresh、jti、lock、revoke）、TTL、各操作的讀寫與解鎖腳本。
- [已移除 API](https://go-jwt.pardn.io/zh/removed-api.md): go-jwt 歷次移除的符號，從 v0.4.0 到 v1.0.3 移至 core 子套件，附移除版本與替代做法。

## Optional

- [Release Notes](https://go-jwt.pardn.io/released/index.md): pardnchiu/go-jwt changelog by version