merge develop/v2 to v2 (#853)

* Update deps * Protect jws.Verify() and jwe.Encrypt() from panic on go1.19+ (#841) * Protect jws.Verify() from panic on go1.19+ * Same problem, but in jwe * Update Changes * fix example (#843) I have a feeling we inadvertently reverted some commit * Action updates, doc tweaks (#844) * Use tparse (#845) * Use tparse * s/all/alltags/ * fix typo (#846) * fix typo (#847) * Bump kentaro-m/auto-assign-action from 1.2.0 to 1.2.4 (#848) Bumps [kentaro-m/auto-assign-action](https://github.com/kentaro-m/auto-assign-action) from 1.2.0 to 1.2.4. - [Release notes](https://github.com/kentaro-m/auto-assign-action/releases) - [Commits](kentaro-m/auto-assign-action@v1.2.0...v1.2.4) --- updated-dependencies: - dependency-name: kentaro-m/auto-assign-action dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump codecov/codecov-action from 1 to 3 (#849) Bumps [codecov/codecov-action](https://github.com/codecov/codecov-action) from 1 to 3. - [Release notes](https://github.com/codecov/codecov-action/releases) - [Changelog](https://github.com/codecov/codecov-action/blob/main/CHANGELOG.md) - [Commits](codecov/codecov-action@v1...v3) --- updated-dependencies: - dependency-name: codecov/codecov-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Work with invalid JWT buffers better (#851) * Work with invalid JWT buffers better * spelling * Update Changes * typo * Tweak Changes * Update Changes Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
lestrrat-go · Nov 25, 2022 · 7803b82 · 7803b82
1 parent 6e8e918
commit 7803b82
Show file tree

Hide file tree

Showing 29 changed files with 232 additions and 71 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -15,3 +15,8 @@ updates:
     schedule:
       interval: "daily"
     target-branch: "develop/v1"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    target-branch: "develop/v2"
diff --git a/.github/workflows/assign-pr.yml b/.github/workflows/assign-pr.yml
@@ -7,6 +7,6 @@ jobs:
   add-reviews:
     runs-on: ubuntu-latest
     steps:
-      - uses: kentaro-m/[email protected].0
+      - uses: kentaro-m/[email protected].4
         with:
           configuration-path: .github/auto-assign-pr.yml
diff --git a/.github/workflows/autodoc.yml b/.github/workflows/autodoc.yml
@@ -13,7 +13,7 @@ jobs:
     if: github.event.pull_request.merged == true
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Process markdown files
         run: |
           find . -name '*.md' | xargs perl tools/autodoc.pl

diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
@@ -13,9 +13,9 @@ jobs:
     name: "Test [ Go ${{ matrix.go }} / JSON Backend ${{ matrix.json_backend }} ]"
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Cache Go modules
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: |
             ~/go/pkg/mod

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -10,14 +10,14 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go_tags: [ 'stdlib', 'goccy', 'es256k', 'all']
+        go_tags: [ 'stdlib', 'goccy', 'es256k', 'alltags']
         go: [ '1.19', '1.18', '1.17' ]
     name: "Test [ Go ${{ matrix.go }} / Tags ${{ matrix.go_tags }} ]"
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Cache Go modules
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: |
             ~/go/pkg/mod
@@ -42,6 +42,8 @@ jobs:
           echo "::add-path::$(go env GOPATH)/bin"
       - name: Install stringer
         run: go install golang.org/x/tools/cmd/stringer@latest
+      - name: Install tparse
+        run: go install github.com/mfridman/tparse@latest
       - name: Install jose
         run: sudo apt-get install -y --no-install-recommends jose
       - run: make generate
@@ -51,7 +53,7 @@ jobs:
         run: make cover-${{ matrix.go_tags }}
       - name: Upload code coverage to codecov
         if: matrix.go == '1.19'
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v3
         with:
           file: ./coverage.out
       - name: Check difference between generation code and commit code

diff --git a/.github/workflows/smoke.yml b/.github/workflows/smoke.yml
@@ -13,17 +13,17 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go_tags: [ 'stdlib', 'goccy', 'es256k', 'all' ]
+        go_tags: [ 'stdlib', 'goccy', 'es256k', 'alltags' ]
         go: [ '1.19', '1.18', '1.17' ]
     name: "Smoke [ Go ${{ matrix.go }} / Tags ${{ matrix.go_tags }} ]"
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Check documentation generator
         run: |
           find . -name '*.md' | xargs env AUTODOC_DRYRUN=1 perl tools/autodoc.pl
       - name: Cache Go modules
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: |
             ~/go/pkg/mod
@@ -38,6 +38,8 @@ jobs:
           check-latest: true
       - name: Install stringer
         run: go install golang.org/x/tools/cmd/stringer@latest
+      - name: Install tparse
+        run: go install github.com/mfridman/tparse@latest
       - name: Install jose
         run: sudo apt-get install -y --no-install-recommends jose
       - run: make generate

diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
@@ -7,7 +7,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v4
+      - uses: actions/stale@v6
         with:
           stale-issue-message: 'This issue is stale because it has been open 14 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
           stale-pr-message: 'This PR is stale because it has been open 14 days with no activity. Remove stale label or comment or this will be closed in 14 days.'

diff --git a/Changes b/Changes
@@ -4,6 +4,23 @@ Changes
 v2 has many incompatibilities with v1. To see the full list of differences between
 v1 and v2, please read the Changes-v2.md file (https://github.com/lestrrat-go/jwx/blob/develop/v2/Changes-v2.md)
 
+v2.0.8 - 25 Nov 2022
+[Security Fixes]
+  * [jws][jwe] Starting from go 1.19, code related to elliptic algorithms
+    panics (instead of returning an error) when certain methods
+    such as `ScalarMult` are called using points that are not on the
+    elliptic curve being used.
+
+    Using inputs that cause this condition, and you accept unverified JWK
+    from the outside it may be possible for a third-party to cause panics
+    in your program.
+
+    This has been fixed by verifying that the point being used is actually
+    on the curve before such computations (#840)
+[Miscellaneous]
+  * `jwx.GuessFormat` now returns `jwx.InvalidFormat` when the heuristics
+    is sure that the buffer format is invalid.
+
 v2.0.7 - 15 Nov 2022
 [New features]
   * [jwt] Each `jwt.Token` now has an `Options()` method

diff --git a/Makefile b/Makefile
@@ -11,58 +11,58 @@ realclean:
 	rm coverage.out
 
 test-cmd:
-	go test -v -race $(TESTOPTS)
+	env TESTOPTS="$(TESTOPTS)" ./tools/test.sh
 
 test:
-	$(MAKE) TESTOPTS=./... test-cmd
-	$(MAKE) -f $(PWD)/Makefile -C examples test-cmd
-	$(MAKE) -f $(PWD)/Makefile -C bench/performance test-cmd
+	$(MAKE) test-stdlib TESTOPTS=
+
+test-stdlib:
+	$(MAKE) test-cmd TESTOPTS=
+
+test-goccy:
+	$(MAKE) test-cmd TESTOPTS="-tags jwx_goccy"
+
+test-es256k:
+	$(MAKE) test-cmd TESTOPTS="-tags jwx_es256k"
+
+test-alltags:
+	$(MAKE) test-cmd TESTOPTS="-tags jwx_goccy,jwx_es256k"
 
 cover-cmd:
-	$(MAKE) test-cmd 
-	$(MAKE) -f $(PWD)/Makefile -C examples TESTOPTS= test-cmd
-	$(MAKE) -f $(PWD)/Makefile -C bench/performance TESTOPTS= test-cmd
-	$(MAKE) -f $(PWD)/Makefile -C cmd/jwx TESTOPTS= test-cmd
-	@# This is NOT cheating. tools to generate code, and tools to
-	@# run tests don't need to be included in the final result.
-	@cat coverage.out.tmp | grep -v "internal/jose" | grep -v "internal/jwxtest" | grep -v "internal/cmd" > coverage.out
-	@rm coverage.out.tmp
+	env MODE=cover ./tools/test.sh
 
 cover:
 	$(MAKE) cover-stdlib
 
 cover-stdlib:
-	$(MAKE) cover-cmd TESTOPTS="-coverpkg=./... -coverprofile=coverage.out.tmp ./..."
+	$(MAKE) cover-cmd TESTOPTS=
 
 cover-goccy:
-	$(MAKE) cover-cmd TESTOPTS="-tags jwx_goccy -coverpkg=./... -coverprofile=coverage.out.tmp ./..."
+	$(MAKE) cover-cmd TESTOPTS="-tags jwx_goccy"
 
 cover-es256k:
-	$(MAKE) cover-cmd TESTOPTS="-tags jwx_es256k -coverpkg=./... -coverprofile=coverage.out.tmp ./..."
+	$(MAKE) cover-cmd TESTOPTS="-tags jwx_es256k"
 
-cover-all:
-	$(MAKE) cover-cmd TESTOPTS="-tags jwx_goccy,jwx_es256k -coverpkg=./... -coverprofile=coverage.out.tmp ./..."
+cover-alltags:
+	$(MAKE) cover-cmd TESTOPTS="-tags jwx_goccy,jwx_es256k"
 
 smoke-cmd:
-	$(MAKE) test-cmd
-	$(MAKE) -f $(PWD)/Makefile -C examples test-cmd
-	$(MAKE) -f $(PWD)/Makefile -C bench/performance test-cmd
-	$(MAKE) -f $(PWD)/Makefile -C cmd/jwx test-cmd
+	env MODE=short ./tools/test.sh
 
 smoke:
 	$(MAKE) smoke-stdlib
 
 smoke-stdlib:
-	$(MAKE) smoke-cmd TESTOPTS="-short ./..."
+	$(MAKE) smoke-cmd TESTOPTS=
 
 smoke-goccy:
-	$(MAKE) smoke-cmd TESTOPTS="-short -tags jwx_goccy ./..."
+	$(MAKE) smoke-cmd TESTOPTS="-tags jwx_goccy"
 
 smoke-es256k:
-	$(MAKE) smoke-cmd TESTOPTS="-short -tags jwx_es256k ./..."
+	$(MAKE) smoke-cmd TESTOPTS="-tags jwx_es256k"
 
-smoke-all:
-	$(MAKE) smoke-cmd TESTOPTS="-short -tags jwx_goccy,jwx_es256k ./..."
+smoke-alltags:
+	$(MAKE) smoke-cmd TESTOPTS="-tags jwx_goccy,jwx_es256k"
 
 viewcover:
 	go tool cover -html=coverage.out

diff --git a/bench/performance/go.mod b/bench/performance/go.mod
@@ -2,4 +2,4 @@ module github.com/lestrrat-go/jwx/v2/bench/performance
 
 go 1.16
 
-require github.com/lestrrat-go/jwx/v2 v2.0.6
+require github.com/lestrrat-go/jwx/v2 v2.0.7
diff --git a/bench/performance/go.sum b/bench/performance/go.sum
@@ -14,18 +14,20 @@ github.com/lestrrat-go/httprc v1.0.4 h1:bAZymwoZQb+Oq8MEbyipag7iSq6YIga8Wj6GOiJG
 github.com/lestrrat-go/httprc v1.0.4/go.mod h1:mwwz3JMTPBjHUkkDv/IGJ39aALInZLrhBp0X7KGUZlo=
 github.com/lestrrat-go/iter v1.0.2 h1:gMXo1q4c2pHmC3dn8LzRhJfP1ceCbgSiT9lUydIzltI=
 github.com/lestrrat-go/iter v1.0.2/go.mod h1:Momfcq3AnRlRjI5b5O8/G5/BvpzrhoFTZcn06fEOPt4=
-github.com/lestrrat-go/jwx/v2 v2.0.6 h1:RlyYNLV892Ed7+FTfj1ROoF6x7WxL965PGTHso/60G0=
-github.com/lestrrat-go/jwx/v2 v2.0.6/go.mod h1:aVrGuwEr3cp2Prw6TtQvr8sQxe+84gruID5C9TxT64Q=
+github.com/lestrrat-go/jwx/v2 v2.0.7 h1:vNh7cA5pKS/1muWYpM1GeUHBCf/r1UFxYN60iv7LFRA=
+github.com/lestrrat-go/jwx/v2 v2.0.7/go.mod h1:zLxnyv9rTlEvOUHbc48FAfIL8iYu2hHvIRaTFGc8mT0=
 github.com/lestrrat-go/option v1.0.0 h1:WqAWL8kh8VcSoD6xjSH34/1m8yxluXQbDeKNfvFeEO4=
 github.com/lestrrat-go/option v1.0.0/go.mod h1:5ZHFbivi4xwXxhxY9XHDe2FHo6/Z7WWmtT7T5nBBp3I=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 golang.org/x/crypto v0.0.0-20220427172511-eb4f295cb31f h1:OeJjE6G4dgCY4PIXvIRQbE8+RX+uXZyGhUy/ksMGJoc=
 golang.org/x/crypto v0.0.0-20220427172511-eb4f295cb31f/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
 golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=

diff --git a/cmd/jwx/go.mod b/cmd/jwx/go.mod
@@ -3,7 +3,7 @@ module github.com/lestrrat-go/jwx/v2/cmd/jwx
 go 1.17
 
 require (
-	github.com/lestrrat-go/jwx/v2 v2.0.6
+	github.com/lestrrat-go/jwx/v2 v2.0.7
 	github.com/urfave/cli/v2 v2.3.0
 	golang.org/x/crypto v0.0.0-20220427172511-eb4f295cb31f
 )

diff --git a/cmd/jwx/go.sum b/cmd/jwx/go.sum
@@ -18,8 +18,8 @@ github.com/lestrrat-go/httprc v1.0.4 h1:bAZymwoZQb+Oq8MEbyipag7iSq6YIga8Wj6GOiJG
 github.com/lestrrat-go/httprc v1.0.4/go.mod h1:mwwz3JMTPBjHUkkDv/IGJ39aALInZLrhBp0X7KGUZlo=
 github.com/lestrrat-go/iter v1.0.2 h1:gMXo1q4c2pHmC3dn8LzRhJfP1ceCbgSiT9lUydIzltI=
 github.com/lestrrat-go/iter v1.0.2/go.mod h1:Momfcq3AnRlRjI5b5O8/G5/BvpzrhoFTZcn06fEOPt4=
-github.com/lestrrat-go/jwx/v2 v2.0.6 h1:RlyYNLV892Ed7+FTfj1ROoF6x7WxL965PGTHso/60G0=
-github.com/lestrrat-go/jwx/v2 v2.0.6/go.mod h1:aVrGuwEr3cp2Prw6TtQvr8sQxe+84gruID5C9TxT64Q=
+github.com/lestrrat-go/jwx/v2 v2.0.7 h1:vNh7cA5pKS/1muWYpM1GeUHBCf/r1UFxYN60iv7LFRA=
+github.com/lestrrat-go/jwx/v2 v2.0.7/go.mod h1:zLxnyv9rTlEvOUHbc48FAfIL8iYu2hHvIRaTFGc8mT0=
 github.com/lestrrat-go/option v1.0.0 h1:WqAWL8kh8VcSoD6xjSH34/1m8yxluXQbDeKNfvFeEO4=
 github.com/lestrrat-go/option v1.0.0/go.mod h1:5ZHFbivi4xwXxhxY9XHDe2FHo6/Z7WWmtT7T5nBBp3I=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -30,10 +30,12 @@ github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQD
 github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/urfave/cli/v2 v2.3.0 h1:qph92Y649prgesehzOrQjdWyxFOp/QVM+6imKHad91M=
 github.com/urfave/cli/v2 v2.3.0/go.mod h1:LJmUH05zAU44vOAcrfzZQKsZbVcdbOG8rtL3/XcUArI=
 golang.org/x/crypto v0.0.0-20220427172511-eb4f295cb31f h1:OeJjE6G4dgCY4PIXvIRQbE8+RX+uXZyGhUy/ksMGJoc=

diff --git a/docs/00-anatomy.md b/docs/00-anatomy.md
@@ -50,6 +50,16 @@ The signed content can be encoded in two different formats. The most common one
 eyJhbGciOiJFUzI1NiJ9.SGVsbG8sIFdvcmxkCg.3q5N5JyFphiJolUZuBuUZhuWDfmLDR__rZe3lnuaxWe3bfrfvJS9HmUUhie56NqkyN7vjOl8hm6tzJKTc2oNsg
 ```
 
+Please note that a JWS message may take three forms: compact, full JSON, and flattened JSON serialization.
+
+```mermaid
+graph TD
+    RawData[Raw Data] --> |"three base64 encoded segments,<br/> concatenated with ."| Compact[Compact Serialization]
+    RawData --> | JSON | JSON[JSON Serialization]
+    JSON --> |"does NOT have'signature'"| FullJSON[Full JSON Serialization]
+    JSON --> |"has 'signature'"| Flat[Flattened JSON Serialization]
+```
+
 JWS is implemented in github.com/lestrrat-go/jwx/v2/jws package. This package provides ways to sign arbitrary payload into JWS message, and ways to verify them.
 
 ## Documentation for `github.com/lestrrat-go/jwx/v2/jws`

diff --git a/docs/01-jwt.md b/docs/01-jwt.md
@@ -1159,9 +1159,14 @@ source: [examples/jwt_flatten_audience_example_test.go](https://github.com/lestr
 
 ## Access JWS headers
 
-Note: If you are considering using JWS header fields to decide on which key to use for verification, consider [using a `jwt.KeyProvider`](#parse-and-verify-a-jwt-using-arbitrary-keys).
+The RFC defines JWS as an envelope to JWT (JWS can carry any payload, you just happened to assign a JWT to it). A JWT is just a bag of arbitrary key/value pairs, where some of them are predefined for validation. This means that JWS headers are NOT part of a JWT -- and thus you will not be able to access them through the `jwt.Token` itself.
 
-In order to access JWS headers such as `kid`, `alg`, etc, Please [look at the JWS documentation for it](./02-jws.md#parse-a-jws-message-and-access-jws-headers).
+If you need to access these JWS headers while parsing JWS signed JWT, you will need to reach into the tools defined in the `jws` package.
+
+* If you are considering using JWS header fields to decide on which key to use for verification, consider [using a `jwt.KeyProvider`](#parse-and-verify-a-jwt-using-arbitrary-keys).
+* If you are looking for ways to 
+
+Please [look at the JWS documentation for it](./02-jws.md#parse-a-jws-message-and-access-jws-headers) .
 
 ## Get/Set fields
 

diff --git a/examples/go.mod b/examples/go.mod
@@ -4,9 +4,7 @@ go 1.16
 
 require (
 	github.com/cloudflare/circl v1.1.0
-	github.com/lestrrat-go/jwx/v2 v2.0.6
+	github.com/lestrrat-go/jwx/v2 v2.0.7
 )
 
 replace github.com/cloudflare/circl v1.0.0 => github.com/cloudflare/circl v1.0.1-0.20210104183656-96a0695de3c3
-
-replace github.com/lestrrat-go/jwx/v2 => ../
diff --git a/examples/go.sum b/examples/go.sum
@@ -17,6 +17,8 @@ github.com/lestrrat-go/httprc v1.0.4 h1:bAZymwoZQb+Oq8MEbyipag7iSq6YIga8Wj6GOiJG
 github.com/lestrrat-go/httprc v1.0.4/go.mod h1:mwwz3JMTPBjHUkkDv/IGJ39aALInZLrhBp0X7KGUZlo=
 github.com/lestrrat-go/iter v1.0.2 h1:gMXo1q4c2pHmC3dn8LzRhJfP1ceCbgSiT9lUydIzltI=
 github.com/lestrrat-go/iter v1.0.2/go.mod h1:Momfcq3AnRlRjI5b5O8/G5/BvpzrhoFTZcn06fEOPt4=
+github.com/lestrrat-go/jwx/v2 v2.0.7 h1:vNh7cA5pKS/1muWYpM1GeUHBCf/r1UFxYN60iv7LFRA=
+github.com/lestrrat-go/jwx/v2 v2.0.7/go.mod h1:zLxnyv9rTlEvOUHbc48FAfIL8iYu2hHvIRaTFGc8mT0=
 github.com/lestrrat-go/option v1.0.0 h1:WqAWL8kh8VcSoD6xjSH34/1m8yxluXQbDeKNfvFeEO4=
 github.com/lestrrat-go/option v1.0.0/go.mod h1:5ZHFbivi4xwXxhxY9XHDe2FHo6/Z7WWmtT7T5nBBp3I=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

diff --git a/examples/jws_verify_detached_payload_example_test.go b/examples/jws_verify_detached_payload_example_test.go
@@ -20,7 +20,7 @@ func ExampleJWS_VerifyDetachedPayload() {
 
 	verified, err := jws.Verify([]byte(serialized), jws.WithKey(jwa.HS256, key), jws.WithDetachedPayload([]byte(payload)))
 	if err != nil {
-		fmt.Printf("failed to sign payload: %s\n", err)
+		fmt.Printf("failed to verify payload: %s\n", err)
 		return
 	}
 

diff --git a/examples/jws_verify_with_key_example_test.go b/examples/jws_verify_with_key_example_test.go
@@ -19,7 +19,7 @@ func ExampleJWS_VerifyWithKey() {
 
 	buf, err := jws.Verify([]byte(src), jws.WithKey(jwa.HS256, key))
 	if err != nil {
-		fmt.Printf("failed to sign payload: %s\n", err)
+		fmt.Printf("failed to verify payload: %s\n", err)
 		return
 	}
 	fmt.Printf("%s\n", buf)

diff --git a/format.go b/format.go
@@ -7,8 +7,15 @@ import (
 
 type FormatKind int
 
+// These constants describe the result from guessing the format
+// of the incoming buffer.
 const (
-	UnknownFormat FormatKind = iota
+	// InvalidFormat is returned when the format of the incoming buffer
+	// has been deemed conclusively invalid
+	InvalidFormat FormatKind = iota
+	// UnknownFormat is returned when GuessFormat was not able to conclusively
+	// determine the format of the
+	UnknownFormat
 	JWE
 	JWS
 	JWK
@@ -66,7 +73,7 @@ func GuessFormat(payload []byte) FormatKind {
 		case 4:
 			return JWE
 		default:
-			return UnknownFormat
+			return InvalidFormat
 		}
 	}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@ module github.com/lestrrat-go/jwx/v2/bench/performance

		go 1.16

		require github.com/lestrrat-go/jwx/v2 v2.0.6
		require github.com/lestrrat-go/jwx/v2 v2.0.7