cookiebasedsessions

README

I really don't like the API of any JWT library. Truly it's a battle of which API stinks least.

However, I don't know enough about cryptography to build my own. This library exists as a way to wrap golang-jwt/jwt in some sugar to make the API slightly less awful.

Documentation

Index

• Constants
• func CookieSameSite(ss string) http.SameSite
• func NewCookie(opts CookieParams) *http.Cookie
• func NewSimpleCookie(name, value string) *http.Cookie
• type Claims
• type CookieFactory
  • func NewCookieFactory(opts CookieParams) CookieFactory
  • func (f CookieFactory) ExpireCookie(c *http.Cookie) *http.Cookie
  • func (f CookieFactory) GetCookie(r *http.Request, name string) (*http.Cookie, error)
  • func (f CookieFactory) GetOpts() CookieParams
  • func (f CookieFactory) NewCookie(name, value string) *http.Cookie
  • func (f CookieFactory) SetCookie(w http.ResponseWriter, c *http.Cookie)
• type CookieMaker
• type CookieParams
• type RegisteredClaims
• type Serializer
• type Session
  • func NewSession() *Session
  • func (s *Session) Active(now time.Time) bool
  • func (s *Session) IsExpired(now time.Time) bool
  • func (s *Session) IsValid() bool
  • func (s *Session) TTL(t time.Duration)
• type SessionHandler
  • func NewSessionHandler(name string, factory CookieFactory, serializer Serializer) *SessionHandler
  • func (h *SessionHandler) DeleteSession(w http.ResponseWriter) error
  • func (h *SessionHandler) GetSession(r *http.Request, checkOnly bool) (*Session, error)
  • func (h *SessionHandler) SaveSession(w http.ResponseWriter, session *Session) error
• type TokenSigner
  • func NewSigner(m int, key interface{}) *TokenSigner
  • func (s *TokenSigner) Serialize(claims Claims) (string, error)
  • func (s *TokenSigner) Unserialize(json string, dest Claims) error

Constants

const (
	HS256 = iota
	HS384
	HS512
	ES256
	ES384
	ES512
	EdDSA
	RS256
	RS384
	RS512
	PS256
	PS384
	PS512
)

These represent the method of signing the JWT.

Functions

func CookieSameSite

func CookieSameSite(ss string) http.SameSite

CookieSameSite takes a string value and return an http.SameSite

func NewCookie

func NewCookie(opts CookieParams) *http.Cookie

NewCookie creates a new Cookie. Keep in mind that using a non-secure cookie will not overwrite a secure cookie

func NewSimpleCookie

func NewSimpleCookie(name, value string) *http.Cookie

NewSimpleCookie creates a secure, HTTP-only cookie for the TLD that expires in 30 min.

Types

type Claims

type Claims = jwt.Claims

Claims is an alias that avoids asking implimntors to import the parent JWT lib.

type CookieFactory

type CookieFactory struct {
	Opts CookieParams
}

Factory is a set of params used to create cookies.

func NewCookieFactory

func NewCookieFactory(opts CookieParams) CookieFactory

NewCookieFactory creates a new Factory with the given options.

func (CookieFactory) ExpireCookie

func (f CookieFactory) ExpireCookie(c *http.Cookie) *http.Cookie

ExpireCookie returns the http cookie having set it's expiration. This cookie must still be sent to the browser.

func (CookieFactory) GetCookie

func (f CookieFactory) GetCookie(r *http.Request, name string) (*http.Cookie, error)

GetCookie returns the http cookie of the given name.

func (CookieFactory) GetOpts

func (f CookieFactory) GetOpts() CookieParams

GetOpts allows visibility to the underlying options of a Cookie.

func (CookieFactory) NewCookie

func (f CookieFactory) NewCookie(name, value string) *http.Cookie

NewCookie creates a cookie with the given name and value and CookieFactory's options.

func (CookieFactory) SetCookie

func (f CookieFactory) SetCookie(w http.ResponseWriter, c *http.Cookie)

SetCookie essentially "saves" the cookie by adding it to the request.

type CookieMaker

type CookieMaker interface {
	GetCookie(r *http.Request, name string) (*http.Cookie, error)
	ExpireCookie(c *http.Cookie) *http.Cookie
	NewCookie(name, value string) *http.Cookie
	SetCookie(w http.ResponseWriter, c *http.Cookie)
	GetOpts() CookieParams
}

CookieFactory is an interface for our Cookie Factory

type CookieParams

type CookieParams struct {
	Name     string
	Value    string
	TTL      int
	Path     string
	Domain   string
	IsSecure bool
	HTTPOnly bool
	SameSite http.SameSite
}

CookieParams represents the various bits of information that make up a cookie.

type RegisteredClaims

type RegisteredClaims = jwt.RegisteredClaims

RegisteredClaims is an alias that avoids asking implimntors to import the parent JWT lib.

type Serializer

type Serializer interface {
	Serialize(claims Claims) (string, error)
	Unserialize(jwt string, dest Claims) error
}

Serializer is some API sugar to simplify making and reading JWTs.

type Session

type Session struct {
	RegisteredClaims
}

Session wraps the set of claims in a couple of sugary methods

func NewSession

func NewSession() *Session

NewSession creates a new local session JWT

func (*Session) Active

func (s *Session) Active(now time.Time) bool

Active checks to see if the claims' `nbf` field is less than the given time

func (*Session) IsExpired

func (s *Session) IsExpired(now time.Time) bool

IsExpired checks to see if the claims' `exp` field is less than the given time

func (*Session) IsValid

func (s *Session) IsValid() bool

IsValid implements Claimer and validates the current claim `NotActive` & `IsExpired` against time.Now()

func (*Session) TTL

func (s *Session) TTL(t time.Duration)

TTL is sugar for pushing the expiration date ahead by the given duration

type SessionHandler

type SessionHandler struct {
	// contains filtered or unexported fields
}

SessionHandler manages an http session cookie of a given name

func NewSessionHandler

func NewSessionHandler(
	name string,
	factory CookieFactory,
	serializer Serializer,
) *SessionHandler

NewSessionHandler returns a session handler tied to a given name and equipped to sign the token and set the cookie

func (*SessionHandler) DeleteSession

func (h *SessionHandler) DeleteSession(w http.ResponseWriter) error

DeleteSession replaces the session with one that is expired and sets the cookie to expired

func (*SessionHandler) GetSession

func (h *SessionHandler) GetSession(r *http.Request, checkOnly bool) (*Session, error)

GetSession retrieves the named session from the http request

func (*SessionHandler) SaveSession

func (h *SessionHandler) SaveSession(w http.ResponseWriter, session *Session) error

SaveSession sets the named session in the http request

type TokenSigner

type TokenSigner struct {
	Method jwt.SigningMethod
	Key    interface{}
}

TokenSigner combines signing and serializing a JWT by holding the signing method and implementing the Serializer interface.

func NewSigner

func NewSigner(m int, key interface{}) *TokenSigner

NewSigner returns a TokenSigner assigned the given method

func (*TokenSigner) Serialize

func (s *TokenSigner) Serialize(claims Claims) (string, error)

Serialize takes a set of Claims and returns a signed & encoded JWT.

func (*TokenSigner) Unserialize

func (s *TokenSigner) Unserialize(json string, dest Claims) error

Unserialize takes a signed & encoded JWT and sets the claims within the destination.