webext

README

displayName

A collection of website middleware to extend basic tasks for gofiber.

Note: this module assumes you are using gofiber/v2

Installation

go get github.com/AspieSoft/webext

# dependencies
go get github.com/gofiber/fiber/v2

Usage

package main

import (
  "github.com/AspieSoft/webext"
  "github.com/gofiber/fiber/v2"
)

func main(){
  app := fiber.New()

  origins := []string{
    "localhost",
    "example.com",
  }

  proxies := []string{
    "127.0.0.1",
    "192.168.0.1",
  }

  // enforce specific domain and ip origins
  app.Use(webext.VerifyOrigin(origins, proxies, func(c *fiber.Ctx, err error) error {
    c.SendStatus(403)
    return c.SendString(err.Error())
  }))

  // auto redirect http to https
  app.Use(webext.RedirectSSL(8080, 8443))

  // do anything with gofiber
  app.Get("/", func(c *fiber.Ctx) error {
    return c.SendString("Hello, World!")
  })

  // listen to both http and https ports and
  // auto generate a self signed ssl certificate
  // (will also auto renew every year)
  webext.ListenAutoTLS(app, 8080, 8443, "db/ssl/auto_ssl", proxies)

  // by using self signed certs, you can use a proxy like cloudflare and
  // not have to worry about verifying a certificate athority like lets encrypt
}

Documentation

Index

• Variables
• func DelCron(name string)
• func GenRsaKey(crtPath string, keyPath string) error
• func GenRsaKeyIfNeeded(crtPath string, keyPath string) error
• func HasCron(name string) bool
• func ListenAutoTLS(app *fiber.App, httpPort, sslPort uint16, certPath string, proxy ...[]string) error
• func NewCron(interval time.Duration, cb func() bool) error
• func PrintMsg(color string, msg string, size int, end bool)
• func RedirectSSL(httpPort, sslPort uint16) func(c *fiber.Ctx) error
• func SetCron(name string, interval time.Duration, cb func() bool)
• func TryPerm(perm rfs.FileMode, nonrootPerm rfs.FileMode) rfs.FileMode
• func VerifyLogin() func(c *fiber.Ctx) error
• func VerifyOrigin(origin []string, proxy []string, ...) func(c *fiber.Ctx) error
• type FormAuth
• type StatusError

Variables

var FormCreateLoginSession func(uuid string) (token string, exp time.Time, err StatusError) = func(uuid string) (string, time.Time, StatusError) {

	return string(crypt.RandBytes(256)), time.Now().Add(-24 * time.Hour), StatusError{500, "Create Session Method Needs Setup"}
}

FormCreateLoginSession is a method you can override. It is necessary to create this function if you intend to use the VerifyLogin middleware.

This method runs after the login has been successfully verified.

You need to generate a unique random token and

• store it in your database
• return the same token as the first argument of this function

The second argument should return when that token should expire. The token will be sent to the user as a login_session cookie. It is also highly recommended you store the expiration of the token in your database.

If you cannot add the login session for any reason, return StatusError as the last argument with a status code and an error message. For no error, just return an empty StatusError.

var FormRemoveLoginSession func(token string) = func(token string) {

}

FormRemoveLoginSession is a method you can override. It is necessary to create this function if you intend to use the VerifyLogin middleware.

This method is called when a user logs out.

You need to remove the login_session token from your database. The cookie will automatically be cleared.

It is highly recommended you do Not keep the now invalid token in your database for security. If the user logged out, we do not want to keep any unused tokens for a hacker to try and abuse.

var FormVerifyLogin func(username string, password string) (uuid string, auth2 FormAuth, verified bool) = func(username string, password string) (string, FormAuth, bool) {

	return "", FormAuth{Enabled: false}, false
}

FormVerifyLogin is a method you can override. It is necessary to create this function if you intend to use the VerifyLogin middleware.

This method should check your database and verify if a username and password is valid.

@return

@auth2: Returns a FormAuth struct which is used to determine what 2 step authentication methods the user can accept. It should also include `Enabled: true|false` to specify if a user has 2auth enabled or disabled.

@verified: Should return true if the username and password are correct and valid. Return false to reject the login and return an `Invalid Username or Password` error.

Notice: The 2auth method is still in development, and is not currently available. It is recommended for the first argument, you should simply pass `FormmAuth{Enabled: false}`.

var FormVerifyLoginSession func(token string) (uuid string, verified bool) = func(token string) (string, bool) {

	return "", false
}

FormVerifyLoginSession is a method you can override. It is necessary to create this function if you intend to use the VerifyLogin middleware.

This method should check your database for a session token verifying if the users login_session cookie is valid and not expired.

var GetPCID func(c *fiber.Ctx) string = func(c *fiber.Ctx) string {
	id := sha512.Sum512([]byte(c.Context().RemoteAddr().String() + "@" + string(c.Context().UserAgent())))
	return string(id[:])
}

GetPCID is a method you can override.

This method should return a unique identifier of the users ip and browser, and the result needs to be connsistantly the same even between sessions.

This ID is used as a secondary way to verify if a session token is valid, and the goal is to verify that the token is being used by the same machine it was generated for. This can help protect users from cookie injection. A hacker would have to know all the info about the user this string returns.

This string should only be stored server side, and never sent to the client.

By default, this returns a hash of the users IP Address (RemoteAddr) and UserAgent.

var IsRoot bool = os.Geteuid() == 0

IsRoot returns true if the EUID is 0

(i.e. if you ran your app with sudo)

var PWD string

PWD is initialized to the parent working directory of your app

var RenderPage func(c *fiber.Ctx, url string, status int, args map[string]any) error = func(c *fiber.Ctx, url string, status int, args map[string]any) error {

	return nil
}

RenderPage is a method you can override.

It is used to handle page rendering. You can decide how you want to handle pages and errors here. You can also setup a templating engine of your choice with this method.

Functions

func DelCron

func DelCron(name string)

DelCron removes a named cron job

func GenRsaKey

func GenRsaKey(crtPath string, keyPath string) error

GenRsaKey generates a new ssl certificate and key pair

• expires: 3 years
• rsa: 4096
• x509
• sha256
• recommended renewal: once a year

func GenRsaKeyIfNeeded

func GenRsaKeyIfNeeded(crtPath string, keyPath string) error

GenRsaKeyIfNeeded auto detects if the certificates generated by the GenRsaKey method are either

• not synchronized by date modified
• are possibly expired (assuming a 1 year renewal)

If it detects this is true, it will automatically regenerate a new certificate

func HasCron

func HasCron(name string) bool

HasCron checks if a named cron job exists

func ListenAutoTLS

func ListenAutoTLS(app *fiber.App, httpPort, sslPort uint16, certPath string, proxy ...[]string) error

ListenAutoTLS will automatically generate a self signed tls certificate if needed and listen to both http and https ports

@httpPort: 80, @sslPort: 443

@certPath: file path to store ssl certificates to (this will generate a my/path.crt and my/path.key file)

@proxy: optional, if only one proxy is specified, the app will only listen to that ip address

func NewCron

func NewCron(interval time.Duration, cb func() bool) error

NewCron adds a new, unnamed cron job to the queue

minimum interval: 1 minute

in the callback, return true to keep the job running, and return false to end the job

func PrintMsg

func PrintMsg(color string, msg string, size int, end bool)

PrintMsg prints to console and auto inserts spaces

func RedirectSSL

func RedirectSSL(httpPort, sslPort uint16) func(c *fiber.Ctx) error

RedirectSSL can be added to `app.Use` to auto redirect http to https

@httpPort: 80, @sslPort: 443

func SetCron

func SetCron(name string, interval time.Duration, cb func() bool)

SetCron adds or overwrites a named cron job

func TryPerm

func TryPerm(perm rfs.FileMode, nonrootPerm rfs.FileMode) rfs.FileMode

TryPerm attempts to set a directory permission to @perm only if it can access that directory

if it fails due to permission restrictions, and if IsRoot returns false, it will instead return @nonrootPerm as a fallback

func VerifyLogin

func VerifyLogin() func(c *fiber.Ctx) error

VerifyLogin will verify if a user is loggedin or present them with a login form on GET requests.

Note: POST requests will return a 401 error if the user is not loggedin.

Notice: This method is still in development and is experimental. Use at your own risk.

func VerifyOrigin

func VerifyOrigin(origin []string, proxy []string, handleErr ...func(c *fiber.Ctx, err error) error) func(c *fiber.Ctx) error

VerifyOrigin can be added to `app.Use` to enforce that all connections are coming through a specified domain and proxy ip

@origin: list of valid domains

@proxy: list of valid ip proxies

@handleErr: optional, allows you to define a function for handling invalid origins, instead of returning the default http error

Types

type FormAuth

type FormAuth struct {
	Enabled bool

	Email string
}

FormAuth is used to return possible options for 2 step authentication.

@Enabled: True if a user has enabled 2 step authentication. False to skip 2auth.

@Email: The email address of the user to send an authentication code to.

type StatusError

type StatusError struct {
	Status int
	Msg    string
}