create: auth.Authentication interface

Author: zxdev

auth/atrributes.go

@@ -4,8 +4,8 @@ import (
 	"net/http"
 )
 
-// IsValid type of middleware for authKey and passKey
-// protected endpoint routing
-type IsValid interface {
+// Authentication interface for middleware using
+// authKey and passKey protected endpoint routes
+type Authentication interface {
 	IsValid(http.Handler) http.Handler
 }

auth/authkey.go

@@ -17,31 +17,32 @@ import (
 	"github.com/go-chi/chi/v5"
 )
 
-// Auth structure for authentication and credential management for
+// AuthKey structure for authentication and credential management for
 // authorized user acces to restricted content.
 //
 // The package supports path base (eg. /api/{apikey}/action) requests,
 // however the admin management routes require a header token:{apikey}
 // value be set to access the user management routes.
-type Auth struct {
+type AuthKey struct {
 	path   *string           // user:key map file location; memory only when nil
 	uMap   map[string]string // apikey->user map
 	mwUser struct{}          // middleware transport chain key
 	mu     sync.Mutex        // mutex for uMap concurrency protection
 	silent bool              // silent output after bootstrap ends
-	admin  string            // admin name
+	admin  string            // admin user name; admin
+	hKey   string            // header key name; token
 }
 
-// NewAuth configurator will initialize an *auth.Auth and populate the
+// NewAuthKey configurator will initialize an *auth.Auth and populate the
 // uMap from the disk when path is provided or will use a memory uMap when
 // nil is passed for path; configues the admin routes on a chi.Router
-func NewAuth(path *string, r *chi.Mux) *Auth {
+func NewAuthKey(path *string, r *chi.Mux) *AuthKey {
 
 	if r == nil {
 		r = chi.NewMux()
 	}
 
-	ak := new(Auth).Configure(path)
+	ak := new(AuthKey).Configure(path)
 	r.Route("/a", func(rx chi.Router) {
 		rx.Use(ak.IsAdmin)
 		rx.Get("/", ak.UserHandler())
@@ -57,7 +58,7 @@ func NewAuth(path *string, r *chi.Mux) *Auth {
 
 // generateKey defines the key generation methodology
 // used for ApiKey generation; eg. 5aee4f739eb44c2c
-func (a *Auth) generateKey() string {
+func (a *AuthKey) generateKey() string {
 
 	var b [8]byte
 	rand.Read(b[:])
@@ -66,13 +67,16 @@ func (a *Auth) generateKey() string {
 }
 
 // Silent toggle; {default:on}
-func (a *Auth) Silent() *Auth { a.silent = !a.silent; return a }
+func (a *AuthKey) Silent() *AuthKey { a.silent = !a.silent; return a }
 
 // Admin sets the admin name; {default:admin}
-func (a *Auth) Admin(admin string) *Auth { a.admin = admin; return a }
+func (a *AuthKey) Admin(name string) *AuthKey { a.admin = name; return a }
+
+// HKey sets the header key name; {default:token}
+func (a *AuthKey) HKey(key string) *AuthKey { a.hKey = key; return a }
 
 // User will set a manual user,key combination; key must 6 or more characters
-func (a *Auth) User(user, key string) *Auth {
+func (a *AuthKey) User(user, key string) *AuthKey {
 	if len(user) > 0 && len(key) > 5 {
 		a.mu.Lock()
 		a.uMap[strings.ToLower(key)] = strings.ToLower(user)
@@ -83,7 +87,7 @@ func (a *Auth) User(user, key string) *Auth {
 
 // Start automated authorization refreshing; useful on clusters which
 // share a common file or sync'd file system
-func (a *Auth) Start(ctx context.Context, refresh *time.Duration) {
+func (a *AuthKey) Start(ctx context.Context, refresh *time.Duration) {
 
 	if refresh == nil || *refresh == 0 {
 		freq := time.Hour
@@ -103,18 +107,23 @@ func (a *Auth) Start(ctx context.Context, refresh *time.Duration) {
 
 // Configure will populate uMap from disk and create a default
 // admin user when no current file exists (or path is file)
-func (a *Auth) Configure(path *string) *Auth {
+func (a *AuthKey) Configure(path *string) *AuthKey {
 
-	// set default
+	// set path default
 	if path != nil {
 		a.path = path
 	}
 
-	// set default
+	// set admin default
 	if len(a.admin) == 0 {
 		a.Admin("admin")
 	}
 
+	// set nKey default
+	if len(a.hKey) == 0 {
+		a.HKey("token")
+	}
+
 	if a.refresh() == 0 {
 		if key := a.add(a.admin); !a.silent {
 			log.Printf("auth: add %s [%s]", a.admin, key)
@@ -125,7 +134,7 @@ func (a *Auth) Configure(path *string) *Auth {
 }
 
 // refresh builds uMap from disk; user apikey
-func (a *Auth) refresh() (n int) {
+func (a *AuthKey) refresh() (n int) {
 
 	a.mu.Lock()
 	defer a.mu.Unlock()
@@ -155,7 +164,7 @@ func (a *Auth) refresh() (n int) {
 }
 
 // save uMap to disk; user apikey
-func (a *Auth) save() {
+func (a *AuthKey) save() {
 
 	if a.path != nil {
 		f, err := os.Create(*a.path)
@@ -172,7 +181,7 @@ func (a *Auth) save() {
 }
 
 // add user to uMap
-func (a *Auth) add(user string) string {
+func (a *AuthKey) add(user string) string {
 
 	user = strings.ToLower(user)
 	key := a.generateKey()
@@ -186,7 +195,7 @@ func (a *Auth) add(user string) string {
 }
 
 // delete user from uMap
-func (a *Auth) delete(user string) bool {
+func (a *AuthKey) delete(user string) bool {
 
 	user = strings.ToLower(user)
 	if user != a.admin {
@@ -206,7 +215,7 @@ func (a *Auth) delete(user string) bool {
 }
 
 // update a user apikey in uMap
-func (a *Auth) update(user string) (string, bool) {
+func (a *AuthKey) update(user string) (string, bool) {
 
 	if a.delete(user) {
 		return a.add(user), true
@@ -216,7 +225,7 @@ func (a *Auth) update(user string) (string, bool) {
 }
 
 // check the key in the uMap and returns the user and lookup status
-func (a *Auth) check(key string) (user string, ok bool) {
+func (a *AuthKey) check(key string) (user string, ok bool) {
 
 	if len(key) > 0 {
 		a.mu.Lock()
@@ -235,7 +244,7 @@ func (a *Auth) check(key string) (user string, ok bool) {
 // AddHandler will add a new user to the ApiKey.uMap authority
 //
 // .../add/{user}
-func (a *Auth) AddHandler() http.HandlerFunc {
+func (a *AuthKey) AddHandler() http.HandlerFunc {
 
 	type response struct {
 		Status int    `json:"status"`
@@ -261,7 +270,7 @@ func (a *Auth) AddHandler() http.HandlerFunc {
 // DeleteHandler removes a user from the ApiKey.uMap authority
 //
 // .../remove/{user}
-func (a *Auth) DeleteHandler() http.HandlerFunc {
+func (a *AuthKey) DeleteHandler() http.HandlerFunc {
 
 	type response struct {
 		Status  int    `json:"status"`
@@ -283,7 +292,7 @@ func (a *Auth) DeleteHandler() http.HandlerFunc {
 // UpdateHandler reloads the ApiKey.uMap from disk
 //
 // .../update/{user}
-func (a *Auth) UpdateHandler() http.HandlerFunc {
+func (a *AuthKey) UpdateHandler() http.HandlerFunc {
 
 	type response struct {
 		Status  int    `json:"status"`
@@ -316,7 +325,7 @@ func (a *Auth) UpdateHandler() http.HandlerFunc {
 // RefreshHandler reloads the ApiKey.uMap from disk
 //
 // .../refresh
-func (a *Auth) RefreshHandler() http.HandlerFunc {
+func (a *AuthKey) RefreshHandler() http.HandlerFunc {
 
 	type response struct {
 		Status  int    `json:"status,omitempty"`
@@ -337,7 +346,7 @@ func (a *Auth) RefreshHandler() http.HandlerFunc {
 // UserHandler provides the current ApiKey.uMap
 //
 // .../users
-func (a *Auth) UserHandler() http.HandlerFunc {
+func (a *AuthKey) UserHandler() http.HandlerFunc {
 
 	type user struct {
 		name, key string
@@ -358,7 +367,7 @@ func (a *Auth) UserHandler() http.HandlerFunc {
 
 		w.WriteHeader(http.StatusOK)
 		fmt.Fprintf(w, "\n%s\n", strings.Repeat("-", 40))
-		fmt.Fprintf(w, "%-20s | %s\n", "user", "apikey")
+		fmt.Fprintf(w, "%-20s | %s\n", "user", a.hKey)
 		fmt.Fprintf(w, "%s\n", strings.Repeat("-", 40))
 		for i := range users {
 			if users[i].name != a.admin {
@@ -377,26 +386,26 @@ func (a *Auth) UserHandler() http.HandlerFunc {
 
 // setUser stores the user in the r.Context middleware transport chain
 // under the type specific mwUser key
-func (a *Auth) setUser(r *http.Request, val string) *http.Request {
+func (a *AuthKey) setUser(r *http.Request, val string) *http.Request {
 	return r.WithContext(context.WithValue(r.Context(), a.mwUser, val))
 }
 
 // GetUser retreives the user from the r.Context middleware transport chain
 // using the specific mwUser key type
-func (a *Auth) GetUser(r *http.Request) string {
+func (a *AuthKey) GetUser(r *http.Request) string {
 	return r.Context().Value(a.mwUser).(string)
 }
 
 // IsValid middleware is restriced to valid users and requires
-// the http header have token:{apikey} set in the header however
-// it will failover and support /api/{akikey}/action formatting
+// the http header have [a.hKey:{apikey}] set in the header however
+// it will failover and support /api/{key}/action formatting
 // within the url string in r.URL.Path
-func (a *Auth) IsValid(next http.Handler) http.Handler {
+func (a *AuthKey) IsValid(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 
-		apikey := r.Header.Get("token")
+		apikey := r.Header.Get(a.hKey)
 		if len(apikey) == 0 { // failover to url
-			apikey = chi.URLParam(r, "apikey")
+			apikey = chi.URLParam(r, a.hKey)
 		}
 
 		if user, ok := a.check(apikey); ok {
@@ -410,14 +419,14 @@ func (a *Auth) IsValid(next http.Handler) http.Handler {
 
 }
 
-// IsAdmin middleware is restricted to admin and requries
-// that a token:{apikey} be set in the request header for access
+// IsAdmin middleware is restricted to admin and requries that
+// {a.hKey}:{apikey} be set in the request header for access
 //
-// eg. r.Header [token:{apikey}]
-func (a *Auth) IsAdmin(next http.Handler) http.Handler {
+// eg. r.Header [a.hKey:{apikey}]
+func (a *AuthKey) IsAdmin(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 
-		if user, ok := a.check(r.Header.Get("token")); ok && user == a.admin {
+		if user, ok := a.check(r.Header.Get(a.hKey)); ok && user == a.admin {
 			next.ServeHTTP(w, a.setUser(r, user))
 			return
 		}

auth/passkey.go

@@ -43,6 +43,7 @@ type PassKey struct {
 	interval time.Duration    // defaults to one-minute
 	key      [20]byte         // binary form of secret
 	tokens   [3]atomic.Uint32 // interval tokens
+	hKey     string           // header key name; token
 }
 
 // NewPassKey configurator used the provided secret or generates a
@@ -55,6 +56,10 @@ func NewPassKey(secret interface{}) *PassKey {
 	return new(PassKey).Configure(secret)
 }
 
+// HKey sets the header key name; {default:token}
+func (pk *PassKey) HKey(key string) *PassKey { pk.hKey = key; return pk }
+
+// User will
 // Configure applies the provided secret or generates a new one
 // and generates a new token set based off the current pk.interval
 //
@@ -63,6 +68,11 @@ func NewPassKey(secret interface{}) *PassKey {
 //	eg. AW6TJVTYMAYJXLWFW2WWJ6D3Q5B2AY25
 func (pk *PassKey) Configure(secret interface{}) *PassKey {
 
+	// set default hKey
+	if len(pk.hKey) == 0 {
+		pk.HKey("token")
+	}
+
 	// apply provided secret or generate a new one
 	switch a := secret.(type) {
 	case string:
@@ -191,7 +201,7 @@ func (pk *PassKey) token() {
 func (pk *PassKey) IsValid(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 
-		passkey := r.Header.Get("token")
+		passkey := r.Header.Get((pk.hKey))
 		if len(passkey) > 0 {
 			tok, _ := strconv.Atoi(passkey)
 			if pk.Validate(uint32(tok)) {

example/main.go

@@ -40,7 +40,7 @@ func main() {
 			fmt.Fprintln(os.Stdout, pk.Secret()) // to stdout
 		}
 		private(pk, router)
-		grace.Manager(pk)
+		grace.Manager(pk) // pk.Start; roll timer
 
 		// demonstration for a client passkey configuration
 		// for authentication with a passkey remote server
@@ -51,10 +51,11 @@ func main() {
 	case len(param.AuthKey) > 0:
 
 		param.AuthKey = env.Dir(paths.Srv, "conf", param.AuthKey)
-		ak := auth.NewAuth(&param.AuthKey, router) // .Silent() .User("bob","I'mBobI'mBobI'mBob")
+		ak := auth.NewAuthKey(&param.AuthKey, router) // .Silent() .User("bob","I'mBobI'mBobI'mBob")
 		private(ak, router)
 
 	default:
+
 		log.Println("alert: no auth system configured")
 		return
 	}
@@ -66,17 +67,14 @@ func main() {
 		WriteTimeout:      time.Second * 30,
 	}))
 
-	// wait for bootstraps to complete
-	grace.Done()
-
-	// wait for a shutdown signal
-	grace.Wait()
+	grace.Done() // wait for bootstraps to complete
+	grace.Wait() // wait for a shutdown signal
 
 }
 
 // private route; sample auth.IsValid protected routes so that
 // is it agnositic to authKey or passKey validation
-func private(auth auth.IsValid, router *chi.Mux) {
+func private(auth auth.Authentication, router *chi.Mux) {
 
 	router.Route("/demo", func(rx chi.Router) {
 		rx.Use(auth.IsValid)

readme.md

@@ -42,7 +42,6 @@ See the ```example``` folder for the following working sample that integrates bo
 	var param params
 	paths := env.NewEnv(&param, &srv)
 	grace := env.NewGraceful()
-	defer grace.Wait()
 
 	// handlers; default public
 	router := server.Public(server.Heartbeat, nil, nil)
@@ -52,7 +51,7 @@ See the ```example``` folder for the following working sample that integrates bo
 	case len(param.Secret) > 0:
 
 		pk := auth.NewPassKey(param.Secret)
-		if pk == nil { // 
+		if pk == nil { 
 			pk = auth.NewPassKey(nil)
 			log.Println("tokens:", pk.Tokens())  // token set
 			log.Println("passkey:", pk.Secret()) // to stderr
@@ -64,7 +63,7 @@ See the ```example``` folder for the following working sample that integrates bo
 	case len(param.AuthKey) > 0:
 
 		param.AuthKey = env.Dir(paths.Srv, "conf", param.AuthKey)
-		ak := auth.NewAuth(&param.AuthKey, router) // .Silent() .User("bob","I'mBobI'mBobI'mBob")
+		ak := auth.NewAuthKey(&param.AuthKey, router) // .Silent() .User("bob","I'mBobI'mBobI'mBob")
 		private(ak, router)
 
 	default:
@@ -79,8 +78,8 @@ See the ```example``` folder for the following working sample that integrates bo
 		ReadTimeout:       time.Second * 10,
 		WriteTimeout:      time.Second * 30,
 	}))
-
 	grace.Done()
+	grace.Wait()
 
 ```