Improve code comments, including security consideration (#107)

* improve code comments, including security consideration

* Add link to URL with details about security vulnerabilities.

* Update token.go

Co-authored-by: Christian Banse <oxisto@aybaze.com>

* Update token.go

Co-authored-by: Christian Banse <oxisto@aybaze.com>

* update code comments

Co-authored-by: Christian Banse <oxisto@aybaze.com>

parser.go

@@ -36,9 +36,8 @@ func NewParser(options ...ParserOption) *Parser {
 	return p
 }
 
-// Parse parses, validates, and returns a token.
+// Parse parses, validates, verifies the signature and returns the parsed token.
 // keyFunc will receive the parsed token and should return the key for validating.
-// If everything is kosher, err will be nil
 func (p *Parser) Parse(tokenString string, keyFunc Keyfunc) (*Token, error) {
 	return p.ParseWithClaims(tokenString, MapClaims{}, keyFunc)
 }

token.go

@@ -29,11 +29,12 @@ type Token struct {
 	Valid     bool                   // Is the token valid?  Populated when you Parse/Verify a token
 }
 
-// New creates a new Token.  Takes a signing method
+// New creates a new Token with the specified signing method and an empty map of claims.
 func New(method SigningMethod) *Token {
 	return NewWithClaims(method, MapClaims{})
 }
 
+// NewWithClaims creates a new Token with the specified signing method and claims.
 func NewWithClaims(method SigningMethod, claims Claims) *Token {
 	return &Token{
 		Header: map[string]interface{}{
@@ -45,7 +46,8 @@ func NewWithClaims(method SigningMethod, claims Claims) *Token {
 	}
 }
 
-// SignedString retrieves the complete, signed token
+// SignedString creates and returns a complete, signed JWT.
+// The token is signed using the SigningMethod specified in the token.
 func (t *Token) SignedString(key interface{}) (string, error) {
 	var sig, sstr string
 	var err error
@@ -82,9 +84,13 @@ func (t *Token) SigningString() (string, error) {
 	return strings.Join(parts, "."), nil
 }
 
-// Parse parses, validates, and returns a token.
+// Parse parses, validates, verifies the signature and returns the parsed token.
-// keyFunc will receive the parsed token and should return the key for validating.
+// keyFunc will receive the parsed token and should return the cryptographic key
-// If everything is kosher, err will be nil
+// for verifying the signature.
+// The caller is strongly encouraged to set the WithValidMethods option to
+// validate the 'alg' claim in the token matches the expected algorithm.
+// For more details about the importance of validating the 'alg' claim,
+// see https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
 func Parse(tokenString string, keyFunc Keyfunc, options ...ParserOption) (*Token, error) {
 	return NewParser(options...).Parse(tokenString, keyFunc)
 }