auth

Documentation

Overview

Package auth provides authentication strategies for ShellGate.

Index

• Constants
• func GenerateToken(length int) (string, error)
• func SetupOTP(configDir, accountName string) (*otp.Key, error)
• type Authenticator
• type NoneAuth
  • func (n *NoneAuth) Middleware(next http.Handler) http.Handler
  • func (n *NoneAuth) Name() string
  • func (n *NoneAuth) Validate(r *http.Request) (bool, error)
• type OTPAuth
  • func NewOTPAuth(configDir string, loginPageHTML []byte) (*OTPAuth, error)
  • func (o *OTPAuth) Middleware(next http.Handler) http.Handler
  • func (o *OTPAuth) Name() string
  • func (o *OTPAuth) Validate(r *http.Request) (bool, error)
• type OneTimeToken
• type OneTimeTokenStore
  • func NewOneTimeTokenStore() *OneTimeTokenStore
  • func (s *OneTimeTokenStore) Cleanup()
  • func (s *OneTimeTokenStore) Count() int
  • func (s *OneTimeTokenStore) Generate(ttl time.Duration) (string, error)
  • func (s *OneTimeTokenStore) Revoke(token string)
  • func (s *OneTimeTokenStore) RevokeAll()
  • func (s *OneTimeTokenStore) Stop()
  • func (s *OneTimeTokenStore) Validate(token string) bool
• type PasswordAuth
  • func NewPasswordAuth(password string, loginPageHTML []byte) (*PasswordAuth, error)
  • func (p *PasswordAuth) Middleware(next http.Handler) http.Handler
  • func (p *PasswordAuth) Name() string
  • func (p *PasswordAuth) Validate(r *http.Request) (bool, error)
• type TokenAuth
  • func NewTokenAuth(token string) (*TokenAuth, error)
  • func (t *TokenAuth) Middleware(next http.Handler) http.Handler
  • func (t *TokenAuth) Name() string
  • func (t *TokenAuth) SetOneTimeStore(store *OneTimeTokenStore)
  • func (t *TokenAuth) Token() string
  • func (t *TokenAuth) Validate(r *http.Request) (bool, error)

Constants

const (
	// OTPIssuer is the issuer name displayed in authenticator apps.
	OTPIssuer = "ShellGate"

	// OTPSecretFile is the filename for storing the TOTP secret.
	OTPSecretFile = "otp.key"
)

const (
	// SessionCookieName is the name of the authentication cookie.
	SessionCookieName = "shellgate_session"

	// SessionMaxAge is the maximum age of a session cookie (24 hours).
	SessionMaxAge = 24 * time.Hour

	// MaxLoginAttempts is the maximum login attempts per IP per minute.
	MaxLoginAttempts = 5
)

const (
	// TokenSessionCookie is the cookie name for token-based session persistence.
	TokenSessionCookie = "shellgate_token_session"
)

Functions

func GenerateToken

func GenerateToken(length int) (string, error)

GenerateToken generates a cryptographically secure random hex token.

func SetupOTP

func SetupOTP(configDir, accountName string) (*otp.Key, error)

SetupOTP generates a new TOTP secret and stores it in the config directory. Returns the OTP key for display (URI + secret).

Types

type Authenticator

type Authenticator interface {
	// Name returns the human-readable name of the auth strategy.
	Name() string

	// Middleware wraps an HTTP handler with authentication checks.
	Middleware(next http.Handler) http.Handler

	// Validate checks if the request is authenticated.
	Validate(r *http.Request) (bool, error)
}

Authenticator defines the interface for authentication strategies.

type NoneAuth

type NoneAuth struct{}

NoneAuth is a no-op authenticator that allows all requests. Only enabled with --auth none --i-know-what-im-doing.

func (*NoneAuth) Middleware

func (n *NoneAuth) Middleware(next http.Handler) http.Handler

Middleware returns the handler unchanged.

func (*NoneAuth) Name

func (n *NoneAuth) Name() string

Name returns the authenticator name.

func (*NoneAuth) Validate

func (n *NoneAuth) Validate(r *http.Request) (bool, error)

Validate always returns true.

type OTPAuth

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

OTPAuth implements TOTP-based two-factor authentication.

func NewOTPAuth

func NewOTPAuth(configDir string, loginPageHTML []byte) (*OTPAuth, error)

NewOTPAuth creates a new OTP authenticator with the secret loaded from the config directory.

func (*OTPAuth) Middleware

func (o *OTPAuth) Middleware(next http.Handler) http.Handler

Middleware wraps the handler with OTP authentication.

func (*OTPAuth) Name

func (o *OTPAuth) Name() string

Name returns the authenticator name.

func (*OTPAuth) Validate

func (o *OTPAuth) Validate(r *http.Request) (bool, error)

Validate checks if the request has a valid OTP session cookie.

type OneTimeToken

type OneTimeToken struct {
	Token     string
	ExpiresAt time.Time
	Used      bool
}

OneTimeToken represents a single-use authentication token with expiry.

type OneTimeTokenStore

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

OneTimeTokenStore manages single-use tokens for one-time access links.

func NewOneTimeTokenStore

func NewOneTimeTokenStore() *OneTimeTokenStore

NewOneTimeTokenStore creates a new one-time token store with periodic cleanup.

func (*OneTimeTokenStore) Cleanup

func (s *OneTimeTokenStore) Cleanup()

Cleanup removes expired tokens.

func (*OneTimeTokenStore) Count

func (s *OneTimeTokenStore) Count() int

Count returns the number of active (non-expired, non-used) tokens.

func (*OneTimeTokenStore) Generate

func (s *OneTimeTokenStore) Generate(ttl time.Duration) (string, error)

Generate creates a new one-time token with the given TTL. Returns the token string (32-byte hex-encoded = 64 chars).

func (*OneTimeTokenStore) Revoke

func (s *OneTimeTokenStore) Revoke(token string)

Revoke removes a specific token.

func (*OneTimeTokenStore) RevokeAll

func (s *OneTimeTokenStore) RevokeAll()

RevokeAll removes all tokens.

func (*OneTimeTokenStore) Stop

func (s *OneTimeTokenStore) Stop()

Stop stops the cleanup goroutine.

func (*OneTimeTokenStore) Validate

func (s *OneTimeTokenStore) Validate(token string) bool

Validate checks if a token is valid and consumes it on first use. Returns true only once per token.

type PasswordAuth

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

PasswordAuth implements password-based authentication with session cookies.

func NewPasswordAuth

func NewPasswordAuth(password string, loginPageHTML []byte) (*PasswordAuth, error)

NewPasswordAuth creates a new password authenticator.

func (*PasswordAuth) Middleware

func (p *PasswordAuth) Middleware(next http.Handler) http.Handler

Middleware wraps the handler with password authentication.

func (*PasswordAuth) Name

func (p *PasswordAuth) Name() string

Name returns the authenticator name.

func (*PasswordAuth) Validate

func (p *PasswordAuth) Validate(r *http.Request) (bool, error)

Validate checks if the request has a valid session cookie.

type TokenAuth

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

TokenAuth implements bearer token authentication. On first valid auth (via header or query param), a session cookie is set so that subsequent requests (CSS, JS, WebSocket) pass through.

func NewTokenAuth

func NewTokenAuth(token string) (*TokenAuth, error)

NewTokenAuth creates a new token authenticator with the given token. If token is empty, a secure random token is generated.

func (*TokenAuth) Middleware

func (t *TokenAuth) Middleware(next http.Handler) http.Handler

Middleware wraps the handler with token authentication.

func (*TokenAuth) Name

func (t *TokenAuth) Name() string

Name returns the authenticator name.

func (*TokenAuth) SetOneTimeStore

func (t *TokenAuth) SetOneTimeStore(store *OneTimeTokenStore)

SetOneTimeStore sets the one-time token store for validating single-use tokens.

func (*TokenAuth) Token

func (t *TokenAuth) Token() string

Token returns the current token string.

func (*TokenAuth) Validate

func (t *TokenAuth) Validate(r *http.Request) (bool, error)

Validate checks the request for a valid bearer token. Tokens can be provided via:

• Authorization: Bearer <token> header
• ?token=<token> query parameter

Also checks one-time tokens if a store is configured.