Skip to content
Back to search

jwx-v4

MarketplaceWorks with Claude CodeGitHub

Complete implementation of JWx (Javascript Object Signing and Encryption/JOSE) technologies for Go. #golang #jwt #jws #jwk #jwe

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/lestrrat-go/jwx with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/lestrrat-go/jwx'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lestrrat-go--jwx/badge.svg)](/listings/lestrrat-go--jwx)

HTML

<a href="/listings/lestrrat-go--jwx"><img src="/api/listings/lestrrat-go--jwx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

go get github.com/lestrrat-go/jwx/v4

Claude Code Skill

If you use [Claude Code](https://claude.com/claude-code), install the bundled `jwx-dev-v4` skill so the assistant can guide you through using this library — picking algorithms, parsing/signing JWTs, working with JWS/JWE/JWK, and avoiding common footguns:

/plugin marketplace add lestrrat-go/jwx
/plugin install jwx-dev-v4

The skill is scoped to **v4** only. It is intended for developers *using* jwx, not for working on the library itself.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "jwx-v4",
  3. "owner": {
  4. "name": "lestrrat",
  5. "url": "https://github.com/lestrrat-go/jwx"
  6. },
  7. "plugins": [
  8. {
  9. "name": "jwx-dev-v4",
  10. "source": "./agents/plugin",
  11. "description": "Guide for developing Go applications with github.com/lestrrat-go/jwx v4 — parse and sign JWTs, work with JWS/JWE/JWK, pick algorithms, and avoid common footguns."
  12. }
  13. ]
  14. }
README.md · README · 283 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # github.com/lestrrat-go/jwx/v4 [![CI](https://github.com/lestrrat-go/jwx/actions/workflows/ci.yml/badge.svg)](https://github.com/lestrrat-go/jwx/actions/workflows/ci.yml) [![Go Reference](https://pkg.go.dev/badge/github.com/lestrrat-go/jwx/v4.svg)](https://pkg.go.dev/github.com/lestrrat-go/jwx/v4) [![Ask DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-blue)](https://deepwiki.com/lestrrat-go/jwx)
  2. Go module implementing various JWx (JWA/JWE/JWK/JWS/JWT, otherwise known as JOSE) technologies.
  3. If you are using this module in your product or your company, please add your product and/or company name in the [Wiki](https://github.com/lestrrat-go/jwx/wiki/Users)! It really helps keeping up our motivation.
  4. # Requirements
  5. * Go 1.26 or later
  6. * `GOEXPERIMENT=jsonv2`, **on Go 1.26 only**
  7. v4 uses `encoding/json/v2`, which sits behind `GOEXPERIMENT=jsonv2` on Go 1.26 and is part of the standard library from Go 1.27 on. On Go 1.27 leave `GOEXPERIMENT` unset: naming an experiment the toolchain already ships rebuilds the standard library under a non-default configuration for no benefit.
  8. # Install
  9. ```
  10. go get github.com/lestrrat-go/jwx/v4
  11. ```
  12. ## Claude Code Skill
  13. If you use [Claude Code](https://claude.com/claude-code), install the bundled `jwx-dev-v4` skill so the assistant can guide you through using this library — picking algorithms, parsing/signing JWTs, working with JWS/JWE/JWK, and avoiding common footguns:
  14. ```
  15. /plugin marketplace add lestrrat-go/jwx
  16. /plugin install jwx-dev-v4
  17. ```
  18. The skill is scoped to **v4** only. It is intended for developers *using* jwx, not for working on the library itself.
  19. # Migrating from v3
  20. If you are migrating from `github.com/lestrrat-go/jwx/v3`, see [`MIGRATION.md`](MIGRATION.md) for a step-by-step guide with before/after code examples. For a complete list of breaking changes and new features, see [`Changes-v4.md`](Changes-v4.md).
  21. # Features
  22. | Feature | Description |
  23. |---------|-------------|
  24. | **Complete JWA/JWE/JWK/JWS/JWT coverage** | Not just JWT + minimum tool set. Supports JWS messages with multiple signatures (compact and JSON serialization), JWS with detached payload, JWS with unencoded payload (RFC 7797), JWE messages with multiple recipients (compact and JSON serialization). Most operations work with either JWK or raw keys (e.g. `*rsa.PrivateKey`, `*ecdsa.PrivateKey`). |
  25. | **Opinionated, uniform API** | Everything is symmetric and follows a standard convention: `jws.Parse`/`Verify`/`Sign`, `jwe.Parse`/`Encrypt`/`Decrypt`. Arguments are organized as explicit required parameters and optional `WithXXXX()` style options. |
  26. | **Post-quantum cryptography** | Supports ML-KEM, ML-DSA, and HPKE. |
  27. | **Extension module architecture** | Opt-in features via extension modules. See [Extension Modules](docs/10-extensions.md). |
  28. | **JWK Caching** | [`jwkfetch`](https://github.com/jwx-go/jwkfetch) extension to always keep a JWKS up-to-date. |
  29. | **Bazel Support** | [Bazel](https://bazel.build)-ready. |
  30. # SYNOPSIS
  31. <!-- INCLUDE(examples/jwx_readme_example_test.go) -->
  32. ```go
  33. package examples_test
  34. import (
  35. "bytes"
  36. "fmt"
  37. "net/http"
  38. "time"
  39. "github.com/lestrrat-go/jwx/v4/jwa"
  40. "github.com/lestrrat-go/jwx/v4/jwe"
  41. "github.com/lestrrat-go/jwx/v4/jwk"
  42. "github.com/lestrrat-go/jwx/v4/jws"
  43. "github.com/lestrrat-go/jwx/v4/jwt"
  44. )
  45. func Example() {
  46. // Parse, serialize, slice and dice JWKs!
  47. privkey, err := jwk.ParseKey(jsonRSAPrivateKey)
  48. if err != nil {
  49. fmt.Printf("failed to parse JWK: %s\n", err)
  50. return
  51. }
  52. pubkey, err := jwk.PublicKeyOf(privkey)
  53. if err != nil {
  54. fmt.Printf("failed to get public key: %s\n", err)
  55. return
  56. }
  57. // Work with JWTs!
  58. {
  59. // Build a JWT!
  60. tok, err := jwt.NewBuilder().
  61. Issuer(`github.com/lestrrat-go/jwx`).
  62. IssuedAt(time.Now()).
  63. Build()
  64. if err != nil {
  65. fmt.Printf("failed to build token: %s\n", err)
  66. return
  67. }
  68. // Sign a JWT!
  69. signed, err := jwt.Sign(tok, jwt.WithKey(jwa.RS256(), privkey))
  70. if err != nil {
  71. fmt.Printf("failed to sign token: %s\n", err)
  72. return
  73. }
  74. // Verify a JWT!
  75. {
  76. verifiedToken, err := jwt.Parse(signed, jwt.WithKey(jwa.RS256(), pubkey))
  77. if err != nil {
  78. fmt.Printf("failed to verify JWS: %s\n", err)
  79. return
  80. }
  81. _ = verifiedToken
  82. }
  83. // Work with *http.Request!
  84. {
  85. req, _ := http.NewRequest(http.MethodGet, `https://github.com/lestrrat-go/jwx`, nil)
  86. req.Header.Set(`Authorization`, fmt.Sprintf(`Bearer %s`, signed))
  87. verifiedToken, err := jwt.ParseRequest(req, jwt.WithKey(jwa.RS256(), pubkey))
  88. if err != nil {
  89. fmt.Printf("failed to verify token from HTTP request: %s\n", err)
  90. return
  91. }
  92. _ = verifiedToken
  93. }
  94. }
  95. // Encrypt and Decrypt arbitrary payload with JWE!
  96. {
  97. encrypted, err := jwe.Encrypt(payloadLoremIpsum, jwe.WithKey(jwa.RSA_OAEP_256(), jwkRSAPublicKey))
  98. if err != nil {
  99. fmt.Printf("failed to encrypt payload: %s\n", err)
  100. return
  101. }
  102. decrypted, err := jwe.Decrypt(encrypted, jwe.WithKey(jwa.RSA_OAEP_256(), jwkRSAPrivateKey))
  103. if err != nil {
  104. fmt.Printf("failed to decrypt payload: %s\n", err)
  105. return
  106. }
  107. if !bytes.Equal(decrypted, payloadLoremIpsum) {
  108. fmt.Printf("verified payload did not match\n")
  109. return
  110. }
  111. }
  112. // Sign and Verify arbitrary payload with JWS!
  113. {
  114. signed, err := jws.Sign(payloadLoremIpsum, jws.WithKey(jwa.RS256(), jwkRSAPrivateKey))
  115. if err != nil {
  116. fmt.Printf("failed to sign payload: %s\n", err)
  117. return
  118. }
  119. verified, err := jws.Verify(signed, jws.WithKey(jwa.RS256(), jwkRSAPublicKey))
  120. if err != nil {
  121. fmt.Printf("failed to verify payload: %s\n", err)
  122. return
  123. }
  124. if !bytes.Equal(verified, payloadLoremIpsum) {
  125. fmt.Printf("verified payload did not match\n")
  126. return
  127. }
  128. }
  129. // OUTPUT:
  130. }
  131. ```
  132. source: [examples/jwx_readme_example_test.go](https://github.com/jwx-go/examples/blob/v4/jwx_readme_example_test.go)
  133. <!-- END INCLUDE -->
  134. # Documentation
  135. * [API Reference](https://pkg.go.dev/github.com/lestrrat-go/jwx/v4)
  136. * [How-to Documentation](./docs)
  137. * [Runnable Examples](https://github.com/jwx-go/examples)
  138. * [Extension Modules](docs/10-extensions.md)
  139. # Packages and Standards
  140. This module implements the following specifications:
  141. | Package | Specification |
  142. |---------|---------------|
  143. | [jwa](./jwa) | [RFC 7518](https://tools.ietf.org/html/rfc7518) (JSON Web Algorithms) |
  144. | [jwk](./jwk) | [RFC 7517](https://tools.ietf.org/html/rfc7517) (JSON Web Key), [RFC 7638](https://tools.ietf.org/html/rfc7638) (JWK Thumbprint), [RFC 8037](https://tools.ietf.org/html/rfc8037) (CFRG Curves) |
  145. | [jws](./jws) | [RFC 7515](https://tools.ietf.org/html/rfc7515) (JSON Web Signature), [RFC 7797](https://tools.ietf.org/html/rfc7797) (Unencoded Payload) |
  146. | [jwe](./jwe) | [RFC 7516](https://tools.ietf.org/html/rfc7516) (JSON Web Encryption), [draft-ietf-jose-hpke-encrypt](https://datatracker.ietf.org/doc/draft-ietf-jose-hpke-encrypt/) (HPKE) |
  147. | [jwt](./jwt) | [RFC 7519](https://tools.ietf.org/html/rfc7519) (JSON Web Token) |
  148. Additionally supported via the main module or [extension modules](docs/10-extensions.md):
  149. | Specification | Support |
  150. |---------------|---------|
  151. | [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final) (ML-KEM) | JWE key encapsulation via [`github.com/jwx-go/mlkem`](https://github.com/jwx-go/mlkem): ML-KEM-768, ML-KEM-1024, hybrid variants (draft-ietf-jose-pqc-kem) |
  152. | [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final) (ML-DSA) | JWS signatures: native from Go 1.27 on, via [`github.com/jwx-go/mldsa`](https://github.com/jwx-go/mldsa) on Go 1.26 ([details](docs/10-extensions.md#which-implementation-you-get)) |
  153. ## History
  154. My goal was to write a server that heavily uses JWK and JWT. At first glance
  155. the libraries that already exist seemed sufficient, but soon I realized that
  156. 1. To completely implement the protocols, I needed the entire JWT, JWK, JWS, JWE (and JWA, by necessity).
  157. 2. Most of the libraries that existed only deal with a subset of the various JWx specifications that were necessary to implement their specific needs
  158. For example, a certain library looks like it had most of JWS, JWE, JWK covered, but then it lacked the ability to include private claims in its JWT responses. Another library had support of all the private claims, but completely lacked in its flexibility to generate various different response formats.
  159. Because I was writing the server side (and the client side for testing), I needed the *entire* JOSE toolset to properly implement my server, **and** they needed to be *flexible* enough to fulfill the entire spec that I was writing.
  160. So here's `github.com/lestrrat-go/jwx/v4`. This library is extensible, customizable, and hopefully well organized to the point that it is easy for you to slice and dice it.
  161. ## Why would I use this library?
  162. There are several other major Go modules that handle JWT and related data formats,
  163. so why should you use this library?
  164. From a purely functional perspective, the only major difference is this:
  165. Whereas most other projects only deal with what they seem necessary to handle
  166. JWTs, this module handles the **_entire_** spectrum of JWS, JWE, JWK, and JWT.
  167. That is, if you need to not only parse JWTs, but also to control JWKs, or
  168. if you need to handle payloads that are NOT JWTs, you should probably consider
  169. using this module. You should also note that JWT is built _on top_ of those
  170. other technologies. You simply cannot have a complete JWT package without
  171. implementing the entirety of JWS/JWE/JWK, which this library does.
  172. Next, from an implementation perspective, this module differs significantly
  173. from others in that it tries very hard to expose only the APIs, and not the
  174. internal data. For example, individual JWT claims are not accessible through
  175. struct field lookups. You need to use one of the getter methods.
  176. This is because this library takes the stance that the end user is fully capable
  177. and even willing to shoot themselves on the foot when presented with a lax
  178. API. By making sure that users do not have access to open structs, we can protect
  179. users from doing silly things like creating _incomplete_ structs, or access the
  180. structs concurrently without any protection. This structure also allows
  181. us to put extra smarts in the structs, such as doing the right thing when
  182. you want to parse / write custom fields (this module does not require the user
  183. to specify alternate structs to parse objects with custom fields)
  184. In the end I think it comes down to your usage pattern, and priorities.
  185. Some general guidelines that come to mind are:
  186. * If you want a single library to handle everything JWx, such as using JWE, JWK, JWS, handling [auto-refreshing JWKs](https://github.com/jwx-go/jwkfetch), use this module.
  187. * If you want to honor all possible custom fields transparently, use this module.
  188. * If you want a standardized clean API, use this module.
  189. Otherwise, feel free to choose something else.
  190. # Contributions
  191. ## Issues
  192. For bug reports and feature requests, please try to follow the issue templates as much as possible.
  193. For either bug reports or feature requests, failing tests are even better.
  194. ## Pull Requests
  195. Please make sure to include tests that exercise the changes you made.
  196. If you are editing auto-generated files (those files with the `_gen.go` suffix, please make sure that you do the following:
  197. 1. Edit the generator, not the generated files (e.g. `internal/jwxcodegen/cmd/jwxcodegen/`)
  198. 2. Run `make generate` (or `go generate`) to generate the new code
  199. 3. Commit _both_ the generator _and_ the generated files
  200. ## Discussions / Usage
  201. Please try [discussions](https://github.com/lestrrat-go/jwx/discussions) first.
  202. # Credits
  203. * Initial work on this library was generously sponsored by HDE Inc (https://www.hde.co.jp)
  204. * Lots of code, especially JWE was initially taken from go-jose library (https://github.com/square/go-jose)
  205. * Lots of individual contributors have helped this project over the years. Thank each and everyone of you very much.
  206. # Quid pro quo
  207. If you use this software to build products in a for-profit organization, we ask you to _consider_
  208. contributing back to FOSS in the following manner:
  209. * For every 100 employees (direct hires) of your organization, please consider contributing minimum of $1 every year to either this project, **or** another FOSS projects that this project uses. For example, for 100 employees, we ask you contribute $100 yearly; for 10,000 employees, we ask you contribute $10,000 yearly.
  210. * If possible, please make this information public. You do not need to disclose the amount you are contributing, but please make the information that you are contributing to particular FOSS projects public. For this project, please consider writing your name on the [Wiki](https://github.com/lestrrat-go/jwx/wiki/Users)
  211. This is _NOT_ a licensing term: you are still free to use this software according to the license it
  212. comes with. This clause is only a plea for people to acknowledge the work from FOSS developers whose
  213. work you rely on each and everyday.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.