init

Author: zekroTJA

.github/workflows/tests.yml

@@ -0,0 +1,28 @@
+name: Unit Tests
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - "*"
+    paths-ignore:
+      - "**.md"
+  pull_request:
+    branches:
+      - "*"
+    paths-ignore:
+      - "**.md"
+
+jobs:
+  tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: ^1.18
+      - name: Check out code
+        uses: actions/checkout@v2
+      - name: Run Tests
+        run: go test -v -timeout 30s -covermode atomic ./...

.gitignore

@@ -0,0 +1,17 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+.env

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Ringo Hoffmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,37 @@
+# jwt
+
+This is a very simplistic implementation of JWT using hashing algorithms like `HS256` or `HS512` and taking advantage of Go 1.18 generic type parameters for parsing claim objects.
+
+This package is very much inspired and influenced by [robbert229's JWT implementation](https://github.com/robbert229/jwt). [Here](https://github.com/robbert229/jwt/blob/master/LICENSE) you can find the projects License.
+
+## Usage
+
+```go
+const signingSecret = "3U5o3Z#XqfLpr3pjGknwWa^u6)CCo&&G"
+
+algorithm := jwt.NewHmacSha512([]byte(signingSecret))
+handler := jwt.NewHandler[Claims](algorithm)
+
+claims := new(Claims)
+claims.UserID = "221905671296253953"
+claims.Iss = "jwt example"
+claims.SetIat()
+claims.SetExpDuration(15 * time.Minute)
+claims.SetNbfTime(time.Now())
+
+token, err := handler.EncodeAndSign(*claims)
+if err != nil {
+	log.Fatalf("Token generation failed: %s", err.Error())
+}
+
+log.Printf("Token generated: %s", token)
+
+recoveredClaims, err := handler.DecodeAndValidate(token)
+if err != nil {
+	log.Fatalf("Token validation failed: %s", err.Error())
+}
+
+log.Printf("Recovered claims: %+v", recoveredClaims)
+```
+
+Go to [examples](examples) to see the full example.

algorithms.go

@@ -0,0 +1,60 @@
+package jwt
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"crypto/sha512"
+	"hash"
+)
+
+// IAlgorithm describes a hash algorithm used to
+// generate hash sums from given data.
+type IAlgorithm interface {
+	// Name returns the name of the algorithm.
+	// The name must be all uppercase.
+	Name() string
+	// Sum takes any data and returns the hashed
+	// sum of the given data.
+	Sum(data []byte) ([]byte, error)
+}
+
+type Algorithm struct {
+	name   string
+	hasher hash.Hash
+}
+
+func (t Algorithm) Name() string {
+	return t.name
+}
+
+func (t Algorithm) Sum(data []byte) ([]byte, error) {
+	_, err := t.hasher.Write([]byte(data))
+	if err != nil {
+		return nil, err
+	}
+
+	sum := t.hasher.Sum(nil)
+	t.hasher.Reset()
+
+	return sum, nil
+}
+
+// NewAlgorithmWithKey returns a new algorithm using the
+// given hash implementation with the given name and
+// a key used to sign the hash with.
+func NewAlgorithmWithKey(name string, hasher func() hash.Hash, key []byte) Algorithm {
+	return Algorithm{
+		name:   name,
+		hasher: hmac.New(hasher, key),
+	}
+}
+
+// NewHmacSha256 returns a new algorithm using HS256.
+func NewHmacSha256(key []byte) Algorithm {
+	return NewAlgorithmWithKey("HS256", sha256.New, key)
+}
+
+// NewHmacSha512 returns a new algorithm using HS512.
+func NewHmacSha512(key []byte) Algorithm {
+	return NewAlgorithmWithKey("HS512", sha512.New, key)
+}

claims.go

@@ -0,0 +1,97 @@
+package jwt
+
+import "time"
+
+// IValidateExp describes an implementation to check the
+// claims 'exp' value against the given current time.
+type IValidateExp interface {
+	ValidateExp(now time.Time) bool
+}
+
+// IValidateNbf describes an implementation to check the
+// claims 'nbf' value against the given current time.
+type IValidateNbf interface {
+	ValidateNbf(now time.Time) bool
+}
+
+// PublicClaims contains general public clains as
+// specified in RFC7519, Section 4.1.
+//
+// This struct also implements IValidateExp and
+// IValidateNbf to validate the timings of the
+// claims.
+//
+// You can simply extend these claims by your custom
+// ones by setting the PublicClaims as an anonymous
+// field in your claims model.
+// Example:
+//   type MyClains struct {
+//     PublicClaims
+//
+//     UserID string `json:"uid"`
+//   }
+//
+//   claims := new(MyClains)
+//   claims.UserID = "123"
+//   claims.SetExpDuration(15 * time.Minute)
+//
+// Reference:
+// https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1
+type PublicClaims struct {
+	Iss string `json:"iss,omitempty"` // Issuer
+	Sub string `json:"sub,omitempty"` // Subject
+	Aud string `json:"aud,omitempty"` // Audience
+	Exp int64  `json:"exp,omitempty"` // UNIX Expiration Time
+	Nbf int64  `json:"nbf,omitempty"` // UNIX Not Before Time
+	Iat int64  `json:"iat,omitempty"` // UNIX Issued At Time
+	Jti string `json:"jti,omitempty"` // JWT ID
+}
+
+func (t PublicClaims) ValidateExp(now time.Time) bool {
+	if t.Exp == 0 {
+		return true
+	}
+
+	return now.Before(time.Unix(t.Exp, 0))
+}
+
+func (t PublicClaims) ValidateNbf(now time.Time) bool {
+	if t.Nbf == 0 {
+		return true
+	}
+
+	return now.After(time.Unix(t.Nbf, 0))
+}
+
+// SetExpTime sets 'exp' to the given time.
+func (t *PublicClaims) SetExpTime(tm time.Time) {
+	t.Exp = tm.Unix()
+}
+
+// SetExpDuration sets 'exp' to the time in the given duration.
+func (t *PublicClaims) SetExpDuration(duration time.Duration) {
+	t.SetExpTime(time.Now().Add(duration))
+}
+
+// SetNbfTime sets 'nbf' to the given time.
+func (t *PublicClaims) SetNbfTime(tm time.Time) {
+	t.Nbf = tm.Unix()
+}
+
+// SetNbfDuration sets 'nbf' to the time in the given duration.
+func (t *PublicClaims) SetNbfDuration(duration time.Duration) {
+	t.SetNbfTime(time.Now().Add(duration))
+}
+
+// SetIat sets 'iat' to the current time.
+//
+// You can also pass a custom time to be set.
+func (t *PublicClaims) SetIat(tm ...time.Time) {
+	var st time.Time
+	if len(tm) != 0 {
+		st = tm[0]
+	} else {
+		st = time.Now()
+	}
+	t.Iat = st.Unix()
+}

claims_test.go

@@ -0,0 +1,46 @@
+package jwt
+
+import (
+	"testing"
+	"time"
+)
+
+func TestValidateExp(t *testing.T) {
+	var claims PublicClaims
+	now := time.Now()
+
+	claims.Exp = 0
+	if !claims.ValidateExp(now) {
+		t.Fatal("ValidateExp returned false when empty")
+	}
+
+	claims.Exp = now.Add(1 * time.Minute).Unix()
+	if !claims.ValidateExp(now) {
+		t.Fatal("ValidateExp returned false")
+	}
+
+	claims.Exp = now.Add(-1 * time.Minute).Unix()
+	if claims.ValidateExp(now) {
+		t.Fatal("ValidateExp returned true")
+	}
+}
+
+func TestValidateNbf(t *testing.T) {
+	var claims PublicClaims
+	now := time.Now()
+
+	claims.Nbf = 0
+	if !claims.ValidateNbf(now) {
+		t.Fatal("ValidateNbf returned false when empty")
+	}
+
+	claims.Nbf = now.Add(1 * time.Minute).Unix()
+	if claims.ValidateNbf(now) {
+		t.Fatal("ValidateNbf returned true")
+	}
+
+	claims.Nbf = now.Add(-1 * time.Minute).Unix()
+	if !claims.ValidateNbf(now) {
+		t.Fatal("ValidateNbf returned false")
+	}
+}

encoding.go

@@ -0,0 +1,22 @@
+package jwt
+
+import (
+	"encoding/base64"
+	"encoding/json"
+)
+
+func b64JsonEncode(payload any) (string, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", err
+	}
+	return base64.RawURLEncoding.EncodeToString(data), nil
+}
+
+func b64JsonDecode(data string, v any) error {
+	raw, err := base64.RawStdEncoding.DecodeString(data)
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(raw, v)
+}

errors.go

@@ -0,0 +1,10 @@
+package jwt
+
+import "errors"
+
+var (
+	ErrInvalidTokenFormat = errors.New("invalid token format")
+	ErrInvalidSignature   = errors.New("invalid signature")
+	ErrTokenExpired       = errors.New("token has expired (invalid exp)")
+	ErrNotValidYet        = errors.New("token is not valid yet (invalid nbf)")
+)

example/example.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"log"
+	"time"
+
+	"github.com/zekrotja/jwt"
+)
+
+type Claims struct {
+	jwt.PublicClaims
+
+	UserID string `json:"uid"`
+}
+
+func main() {
+	const signingSecret = "3U5o3Z#XqfLpr3pjGknwWa^u6)CCo&&G"
+
+	algorithm := jwt.NewHmacSha512([]byte(signingSecret))
+	handler := jwt.NewHandler[Claims](algorithm)
+
+	claims := new(Claims)
+	claims.UserID = "221905671296253953"
+	claims.Iss = "jwt example"
+	claims.SetIat()
+	claims.SetExpDuration(15 * time.Minute)
+	claims.SetNbfTime(time.Now())
+
+	token, err := handler.EncodeAndSign(*claims)
+	if err != nil {
+		log.Fatalf("Token generation failed: %s", err.Error())
+	}
+
+	log.Printf("Token generated: %s", token)
+
+	recoveredClaims, err := handler.DecodeAndValidate(token)
+	if err != nil {
+		log.Fatalf("Token validation failed: %s", err.Error())
+	}
+
+	log.Printf("Recovered claims: %+v", recoveredClaims)
+}

go.mod

@@ -0,0 +1,3 @@
+module github.com/zekrotja/jwt
+
+go 1.18