jwt

README

jwt

Table of Contents

• Table of Contents
• Usage
  • Signing
  • Verifying
• Directory Structure
  • Rationale

Usage

Signing

package main

import (
	"fmt"
	"github.com/decentralized-identity/web5-go/didjwk"
    "github.com/decentralized-identity/web5-go/jwt"
)

func main() {	
	did, err := didjwk.Create()
	if err != nil {
		panic(err)
	}

	claims := jwt.Claims{
		Issuer: did.URI,
		Misc:   map[string]interface{}{"c_nonce": "abcd123"},
	}

	jwt, err := jwt.Sign(claims, did)
	if err != nil {
		panic(err)
	}
}

Verifying

package main

import (
	"fmt"
	"github.com/decentralized-identity/web5-go/dids"
    "github.com/decentralized-identity/web5-go/jwt"
)

func main() {
    someJWT := "SOME_JWT"
	ok, err := jwt.Verify(signedJWT)
	if err != nil {
		panic(err)
	}

    if (!ok) {
        fmt.Printf("dookie JWT")
    }
}

specifying a specific category of key to use relative to the did provided can be done in the same way shown with jws.Sign

Directory Structure

jwt
├── jwt.go
└── jwt_test.go

Rationale

same as jws.

Documentation

Index

• func Sign(claims Claims, did did.BearerDID, opts ...SignOpt) (string, error)
• type Claims
  • func (c Claims) MarshalJSON() ([]byte, error)
  • func (c *Claims) UnmarshalJSON(b []byte) error
• type Decoded
  • func Decode(jwt string) (Decoded, error)
  • func Verify(jwt string) (Decoded, error)
  • func (jwt Decoded) Verify() error
• type Header
• type SignOpt
  • func Purpose(p string) SignOpt
  • func Type(t string) SignOpt

Functions

func Sign

func Sign(claims Claims, did did.BearerDID, opts ...SignOpt) (string, error)

Sign signs the provided JWT Claims with the provided BearerDID. The Purpose option can be provided to specify that a key from a given DID Document Verification Relationship should be used (e.g. authentication). defaults to using assertionMethod

Note

claims.Issuer will be overridden to the value of did.URI within this function

Types

type Claims

type Claims struct {
	// The "iss" (issuer) claim identifies the principal that issued the
	// JWT.
	//
	// Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1
	Issuer string `json:"iss,omitempty"`
	// The "sub" (subject) claim identifies the principal that is the
	// subject of the JWT.
	//
	// Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2
	Subject string `json:"sub,omitempty"`

	// The "aud" (audience) claim identifies the recipients that the JWT is
	// intended for.
	//
	// Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3
	Audience string `json:"aud,omitempty"`

	// The "exp" (expiration time) claim identifies the expiration time on
	// or after which the JWT must not be accepted for processing.
	//
	// Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4
	Expiration int64 `json:"exp,omitempty"`

	// The "nbf" (not before) claim identifies the time before which the JWT
	// must not be accepted for processing.
	//
	// Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5
	NotBefore int64 `json:"nbf,omitempty"`

	// The "iat" (issued at) claim identifies the time at which the JWT was
	// issued.
	//
	// Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6
	IssuedAt int64 `json:"iat,omitempty"`

	// The "jti" (JWT ID) claim provides a unique identifier for the JWT.
	//
	// Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7
	JTI string `json:"jti,omitempty"`

	Misc map[string]any `json:"-"`
}

Claims represents JWT (JSON Web Token) Claims

Spec: https://datatracker.ietf.org/doc/html/rfc7519#section-4

func (Claims) MarshalJSON

func (c Claims) MarshalJSON() ([]byte, error)

MarshalJSON overrides default json.Marshal behavior to include misc claims as flattened properties of the top-level object

func (*Claims) UnmarshalJSON

func (c *Claims) UnmarshalJSON(b []byte) error

UnmarshalJSON overrides default json.Unmarshal behavior to place flattened Misc claims into Misc

type Decoded

type Decoded struct {
	Header    Header
	Claims    Claims
	Signature []byte
	Parts     []string
	SignerDID did.DID
}

Decoded represents a JWT Decoded into it's relevant parts

func Decode

func Decode(jwt string) (Decoded, error)

Decode decodes the 3-part base64url encoded jwt into it's relevant parts

func Verify

func Verify(jwt string) (Decoded, error)

Verify verifies a JWT (JSON Web Token) as per the spec https://datatracker.ietf.org/doc/html/rfc7519 Successful verification means that the JWT has not expired and the signature's integrity is intact Decoded JWT is returned if verification is successful

func (Decoded) Verify

func (jwt Decoded) Verify() error

Verify verifies a JWT (JSON Web Token)

type Header

type Header = jws.Header

Header are JWS Headers. type aliasing because this could cause confusion for non-neckbeards

type SignOpt

type SignOpt func(opts *signOpts)

SignOpt is a type returned by all individual Sign Options.

func Purpose

func Purpose(p string) SignOpt

Purpose is an option that can be provided to Sign to specify that a key from a given DID Document Verification Relationship should be used (e.g. authentication) Purpose is an option that can be passed to github.com/decentralized-identity/web5-go/jws.Sign. It is used to select the appropriate key to sign with

func Type

func Type(t string) SignOpt

Type is an option that can be used to set the typ header of the JWT