`JW*` Decode

[mistermoe]

Overview

Collaborative effort with @KendallWeihe to split Verify into two distinct functions Decode and Verify

[!IMPORTANT] Most of the code changes in this PR are from moving things around. not much net new logic was added

Rationale

we've run into multiple scenarios where we need to:

1. verify a JWT or JWS and then use a number of fields from within the header or the payload/claims
2. decode a JWT or JWS, check some stuff within the payload or headers, and then verify

In order to access claims within a JWT the caller currently has to do this:

package main

import (
    "encoding/json"
    "fmt"

    "github.com/tbd54566975/web5-go/jwt"
)

func main() {
        signedJwt := "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDpqd2s6ZXlKcmRIa2lPaUpQUzFBaUxDSmpjbllpT2lKRlpESTFOVEU1SWl3aWVDSTZJbFpyU3pKclRscDVVREY0WVZwUFoyZHBjREY2VTJwc1JXTnNTakZSTVhSQmMxRkJhVU5YUW1GaVgyOGlmUSMwIn0." +
    "eyJjX25vbmNlIjoiYWJjZDEyMyIsImlzcyI6ImV5SnJkSGtpT2lKUFMxQWlMQ0pqY25ZaU9pSkZaREkxTlRFNUlpd2llQ0k2SWxaclN6SnJUbHA1VURGNFlWcFBaMmRwY0RGNlUycHNSV05zU2pGUk1YUkJjMUZCYVVOWFFtRmlYMjhpZlEifQ." +
    "O434_IlnJOYbcIsHkVcOyKLxVvcfHvcg6tZL_gIU2TAY6qFiaPZ_w6upSzIl-I8JXYBytzR_8BfCq4P3che1Bg"

    parts := strings.Split(signedJwt, ".")

    base64UrlEncodedClaims := parts[1]

    decodedClaims, err := jwt.DecodeJWTClaims(base64UrlEncodedClaims)

    if err != nil {
        panic(err)
    }

The above code ends up making it such that callers have to know more details than they have to about jwt details. further, if they've already verified the jwt, the claims are now being decoded twice.

Changes

In order to remedy the above, this PR splits decoding and verifying into two distinct steps while still providing a single function call if desired

JWT

Approach 1

package main

import "github.com/tbd54566975/web5-go/jwt"

func main() {
    // Approach 1: decode then verify as two separate steps
    decoded, err := jwt.Decode("test")
    if err != nil {
        panic(err)
    }

   // application specific business logic

    err = decoded.Verify()
    if err != nil {
        panic(err)
    }
}

This approach requires the caller to first decode the JWT, perform whatever business logic is needed and then optionally call verify when desired

Approach 2

package main

import "github.com/tbd54566975/web5-go/jwt"

func main() {
    // Approach 2: decode & verify in 1 step and receive decoded jwt on successful verification
    decoded, err = jwt.Verify("test")
    if err != nil {
        panic(err)
    }
}

This allows to caller to call verify and then decide to perform additional logic using the claims within a JWT depending on the result of verification

JWS

the jws API surface is identical to jwt

Approach 1

package main

import "github.com/tbd54566975/web5-go/jws"

func main() {
    // Approach 1: decode then verify as two separate steps
    decoded, err := jws.Decode("test")
    if err != nil {
        panic(err)
    }

    err = decoded.Verify()
    if err != nil {
        panic(err)
    }
}

Approach 2

package main

import "github.com/tbd54566975/web5-go/jws"

func main() {
    // Approach 2: decode & verify in 1 step and receive decoded jwt on successful verification
    decoded, err = jws.Verify("test")
    if err != nil {
        panic(err)
    }
}

[KendallWeihe]

I'm curious, what are the cases where you needs access to claims before verifying? There's some higher precedence validation to do?

Actually I'm not sure we have run into that situation, @mistermoe am I forgetting something? I think this is a combination of things:

1. We needed a function to decode the JWT (for additional verification)
2. The jws.Verify() and jwt.Verify() function return values were semantically equivalent
3. Someone someday somewhere may have a situation wherein they want to inspect the JWT/JWS constituents without running a verification