security

Documentation

Index

• Variables
• type CachedTokenStore
  • func NewCachedStore(store TokenStore, capacity int) CachedTokenStore
• type Gatekeeper
  • func NewGatekeeper(secret Secret, store TokenStore) (g *Gatekeeper, err error)
  • func (g *Gatekeeper) AddPolicies(...) (err error)
  • func (g *Gatekeeper) AddPolicy(role string, perm Permission, prio int64, cond ...any) (err error)
  • func (g *Gatekeeper) CreateToken(ctx context.Context, payload ...[]byte) (t Token, err error)
  • func (g *Gatekeeper) GetPolicy(roles []string, perm Permission) (cond unsafe.Pointer, err error)
  • func (g *Gatekeeper) IteratePermissions(inPolicy ...bool) iter.Seq[Permission]
  • func (g *Gatekeeper) IteratePolicies() iter.Seq2[PolicyKey, Policy]
  • func (g *Gatekeeper) RegisterPermission(perm Permission, typ reflect.Type) (err error)
  • func (g *Gatekeeper) RemovePolicy(role string, perm Permission)
  • func (g *Gatekeeper) ValidateToken(ctx context.Context, t Token) (user User, err error)
• type Permission
  • func (p Permission) Action() string
  • func (p Permission) HasAction() bool
  • func (p Permission) HasResource() bool
  • func (p Permission) Resource() string
  • func (p *Permission) SetAction(action string)
  • func (p *Permission) SetResource(resource string)
  • func (p Permission) String() string
• type Policy
• type PolicyKey
• type Secret
  • func GenerateSecret() (s Secret, err error)
  • func SecretFromString(str string) (s Secret, err error)
  • func (s Secret) AppendBinary(b []byte) ([]byte, error)
  • func (s Secret) AppendText(b []byte) ([]byte, error)
  • func (s *Secret) FromString(str string) error
  • func (t Secret) MarshalBinary() (data []byte, err error)
  • func (s Secret) MarshalText() (text []byte, err error)
  • func (s Secret) String() string
  • func (s *Secret) UnmarshalBinary(data []byte) error
  • func (s *Secret) UnmarshalText(text []byte) (err error)
• type Token
  • func (t Token) AppendBinary(b []byte) ([]byte, error)
  • func (t Token) AppendText(b []byte) ([]byte, error)
  • func (t *Token) FromString(str string) error
  • func (t Token) Id() identifier.ID
  • func (t Token) MarshalBinary() (data []byte, err error)
  • func (t Token) MarshalText() (text []byte, err error)
  • func (t Token) Payload() [24]byte
  • func (t Token) String() string
  • func (t *Token) UnmarshalBinary(data []byte) error
  • func (t *Token) UnmarshalText(text []byte) (err error)
• type TokenStore
  • func DummyStore(roles ...string) TokenStore
• type User

Examples

• Gatekeeper
• Secret

Variables

var (
	ErrInvalidAuthToken = errors.NewError("INVALID_TOKEN", "Invalid authentication token", 401)
	ErrAccessDenied     = errors.NewFrozenError("ACCESS_DENIED", "Access denied", 403)
)

Types

type CachedTokenStore

type CachedTokenStore interface {
	TokenStore
	ClearCache()
}

func NewCachedStore

func NewCachedStore(store TokenStore, capacity int) CachedTokenStore

A cached store is used to reduce the preasure on the underlying store, and decrease any latency.

type Gatekeeper

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

Example

s, err := GenerateSecret()

if err != nil {
	panic(err)
}

g, err := NewGatekeeper(s, dummyStore{})

if err != nil {
	panic(err)
}

tok, err := g.CreateToken(context.Background(), nil)

if err != nil {
	panic(err)
}

fmt.Println(tok)
fmt.Println(g.ValidateToken(context.Background(), tok))
fmt.Println(tok.Payload())

Output:

TODO

func NewGatekeeper

func NewGatekeeper(secret Secret, store TokenStore) (g *Gatekeeper, err error)

func (*Gatekeeper) AddPolicies

func (g *Gatekeeper) AddPolicies(cb func(add func(role string, perm Permission, prio int64, condJson []byte) error) error) (err error)

Add many policies in bulk. See AddPolicy.

func (*Gatekeeper) AddPolicy

func (g *Gatekeeper) AddPolicy(role string, perm Permission, prio int64, cond ...any) (err error)

Adds a policy. Policies must be added AFTER registering all routes. A policy MIGHT contain either a pointer to condition, or a JSON encoded condition as []byte, that will be loaded into a route's policy. Any non-matching fields will be ignored. A policy's role + perm combination MUST be unique, or otherwise overwritten by the latter. An error will be returned if the permission doesn't exist on any route.

func (*Gatekeeper) CreateToken

func (g *Gatekeeper) CreateToken(ctx context.Context, payload ...[]byte) (t Token, err error)

Create a token with an optional payload (e.g. a user ID) that will be stored in the token. The payload cannot exceed 24 bytes, and will be padded with random bytes.

func (*Gatekeeper) GetPolicy

func (g *Gatekeeper) GetPolicy(roles []string, perm Permission) (cond unsafe.Pointer, err error)

Any policy matching the route's permission, and one of the user's roles, will be loaded in ascending priority order.

func (*Gatekeeper) IteratePermissions

func (g *Gatekeeper) IteratePermissions(inPolicy ...bool) iter.Seq[Permission]

Iterates all registered permissions. Set inPolicy to iterate permissions either used in policies or not. Default is to iterate all regardless it's used in a policy or not.

func (*Gatekeeper) IteratePolicies

func (g *Gatekeeper) IteratePolicies() iter.Seq2[PolicyKey, Policy]

Iterates all added policies.

func (*Gatekeeper) RegisterPermission

func (g *Gatekeeper) RegisterPermission(perm Permission, typ reflect.Type) (err error)

Registers a permission. This should NOT be called manually, as it's called automatically when registering routes.

func (*Gatekeeper) RemovePolicy

func (g *Gatekeeper) RemovePolicy(role string, perm Permission)

Removes any previously added policy for the role and permission. Does nothing if it never existed.

func (*Gatekeeper) ValidateToken

func (g *Gatekeeper) ValidateToken(ctx context.Context, t Token) (user User, err error)

type Permission

type Permission string

func (Permission) Action

func (p Permission) Action() string

func (Permission) HasAction

func (p Permission) HasAction() bool

func (Permission) HasResource

func (p Permission) HasResource() bool

func (Permission) Resource

func (p Permission) Resource() string

func (*Permission) SetAction

func (p *Permission) SetAction(action string)

func (*Permission) SetResource

func (p *Permission) SetResource(resource string)

func (Permission) String

func (p Permission) String() string

type Policy

type Policy struct {
	Prio int64
	Cond []byte
}

type PolicyKey

type PolicyKey struct {
	Role string
	Perm Permission
}

type Secret

type Secret [secretLen]byte

Example

s, err := GenerateSecret()

if err != nil {
	panic(err)
}

fmt.Println(s)

Output:

TODO

func GenerateSecret

func GenerateSecret() (s Secret, err error)

func SecretFromString

func SecretFromString(str string) (s Secret, err error)

func (Secret) AppendBinary

func (s Secret) AppendBinary(b []byte) ([]byte, error)

func (Secret) AppendText

func (s Secret) AppendText(b []byte) ([]byte, error)

func (*Secret) FromString

func (s *Secret) FromString(str string) error

func (Secret) MarshalBinary

func (t Secret) MarshalBinary() (data []byte, err error)

func (Secret) MarshalText

func (s Secret) MarshalText() (text []byte, err error)

func (Secret) String

func (s Secret) String() string

func (*Secret) UnmarshalBinary

func (s *Secret) UnmarshalBinary(data []byte) error

func (*Secret) UnmarshalText

func (s *Secret) UnmarshalText(text []byte) (err error)

type Token

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

func (Token) AppendBinary

func (t Token) AppendBinary(b []byte) ([]byte, error)

func (Token) AppendText

func (t Token) AppendText(b []byte) ([]byte, error)

func (*Token) FromString

func (t *Token) FromString(str string) error

func (Token) Id

func (t Token) Id() identifier.ID

func (Token) MarshalBinary

func (t Token) MarshalBinary() (data []byte, err error)

func (Token) MarshalText

func (t Token) MarshalText() (text []byte, err error)

func (Token) Payload

func (t Token) Payload() [24]byte

The payload can be any additional data you have stored, e.g. a user ID.

func (Token) String

func (t Token) String() string

func (*Token) UnmarshalBinary

func (t *Token) UnmarshalBinary(data []byte) error

func (*Token) UnmarshalText

func (t *Token) UnmarshalText(text []byte) (err error)

type TokenStore

type TokenStore interface {

	// Validates a token, looks it up in the underlying token store, and returns its corresponding user.
	// A user can have 0+ roles. If the token doesn't exist in store and/or has been revoked, it MUST
	// return an error. The ctx MIGHT be a *papi.RequestCtx.
	Lookup(ctx context.Context, tok Token) (user User, err error)

	// Inserts a newly created token into the store. This should NOT be called manually, as it's called
	// automatically after a token is created. The store should NOT save the whole token, only its ID, any
	// relation to its corresponding user, and any additional data that that might help later recovation.
	// The ctx MIGHT be a *papi.RequestCtx.
	Insert(ctx context.Context, tok Token) error

	// Deletes a token permanently. Any failure MUST return an error. A deleted token must NOT be able to
	// be looked up later. The ctx MIGHT be a *papi.RequestCtx.
	Delete(ctx context.Context, tokId identifier.ID) error
}

func DummyStore

func DummyStore(roles ...string) TokenStore

Used for testing.

type User

type User interface {
	UserRoles() []string
}

A user representation. The representation SHOULD be brief and only contain values that are necessary to comply with policies, e.g. user ID, tenant ID, roles, etc.