magiclink

Documentation

Index

• Constants
• Variables
• func BestSigningMethod(key any) jwt.SigningMethod
• type Config
  • func (c Config) Valid() error
• type CreateParams
  • func (p CreateParams) Valid() error
• type CreateResponse
• type ErrorHandler
• type ErrorHandlerFunc
  • func (f ErrorHandlerFunc) Handle(args ErrorHandlerParams)
• type ErrorHandlerParams
• type JWKSParams
• type MagicLink
  • func NewMagicLink(setupCtx context.Context, config Config) (MagicLink, error)
  • func (m MagicLink) HandleMagicLink(ctx context.Context, secret string) (jwtB64 string, response ReadResult, err error)
  • func (m MagicLink) JWKSHandler() http.Handler
  • func (m MagicLink) JWKSet() jwkset.Storage
  • func (m MagicLink) MagicLinkHandler() http.Handler
  • func (m MagicLink) NewLink(ctx context.Context, args CreateParams) (CreateResponse, error)
• type ReCAPTCHAV3Config
  • func (r ReCAPTCHAV3Config) DefaultsAndValidate() (ReCAPTCHAV3Config, error)
• type ReCAPTCHAV3Redirector
  • func (r ReCAPTCHAV3Redirector) Redirect(args RedirectorParams)
• type ReCAPTCHAV3TemplateData
  • func (r ReCAPTCHAV3TemplateData) DefaultsAndValidate() (ReCAPTCHAV3TemplateData, error)
• type ReadResult
• type Redirector
  • func NewReCAPTCHAV3Redirector(config ReCAPTCHAV3Config) Redirector
• type RedirectorParams
• type Storage
  • func NewMemoryStorage() Storage

Constants

const (
	// DefaultRedirectQueryKey is the default URL query parameter to contain the JWT in after a magic link has been
	// clicked.
	DefaultRedirectQueryKey = "jwt"
	// DefaultSecretQueryKey is the default URL query parameter to contain the secret for a magic link.
	DefaultSecretQueryKey = "secret"
)

const (
	// ReCAPTCHAV3QueryButtonBypassKey is the URL query parameter key for bypassing the reCAPTCHA v3 test.
	ReCAPTCHAV3QueryButtonBypassKey = "button-bypass"
	// ReCAPTCHAV3QueryButtonBypassValue is the URL query parameter value for bypassing the reCAPTCHA v3 test.
	ReCAPTCHAV3QueryButtonBypassValue = "true"
)

const DefaultJWKSCacheRefresh = 5 * time.Minute

DefaultJWKSCacheRefresh is the default time to wait before refreshing the JWKS cache.

Variables

var (
	// ErrJWKSEmpty is a possible error for an ErrorHandler implementation to handle.
	ErrJWKSEmpty = errors.New("JWK Set is empty")
	// ErrJWKSJSON is a possible error for an ErrorHandler implementation to handle.
	ErrJWKSJSON = errors.New("failed to get JWK Set as JSON")
	// ErrJWKSReadGivenKID is a possible error for an ErrorHandler implementation to handle.
	ErrJWKSReadGivenKID = errors.New("failed to read JWK with given key ID")
	// ErrJWKSSnapshot is a possible error for an ErrorHandler implementation to handle.
	ErrJWKSSnapshot = errors.New("failed to snapshot JWK Set")
	// ErrJWTSign is a possible error for an ErrorHandler implementation to handle.
	ErrJWTSign = errors.New("failed to sign JWT")
	// ErrLinkNotFound is a possible error for an ErrorHandler implementation to handle.
	ErrLinkNotFound = errors.New("link not found")
	// ErrMagicLinkMissingSecret is a possible error for an ErrorHandler implementation to handle.
	ErrMagicLinkMissingSecret = errors.New("visited magic link endpoint without a secret")
	// ErrMagicLinkRead is a possible error for an ErrorHandler implementation to handle.
	ErrMagicLinkRead = errors.New("failed to read the magic link from storage")
)

Errors that ErrorHandler needs to handle.

Functions

func BestSigningMethod

func BestSigningMethod(key any) jwt.SigningMethod

BestSigningMethod returns the best signing method for the given key.

Types

type Config

type Config struct {
	ErrorHandler     ErrorHandler
	JWKS             JWKSParams
	CustomRedirector Redirector
	ServiceURL       *url.URL
	SecretQueryKey   string
	Store            Storage
}

Config contains the required assets to create a MagicLink service.

func (Config) Valid

func (c Config) Valid() error

Valid confirms the Config is valid.

type CreateParams

type CreateParams struct {
	// Expires is the time the magic link will expire. Use of this field is REQUIRED for all use cases.
	Expires time.Time

	// JWTClaims is a data structure that can marshal to JSON as the JWT Claims. Make sure to embed AND populate
	// jwt.RegisteredClaims if your use case supports standard claims. If you shadow the .Valid() method of the
	// interface, be sure to call .RegisteredClaims.Valid() in your implementation. If you are using a non-memory
	// Storage implementation, be sure the data structure is the proper Go type after being read. Use of this field is
	// OPTIONAL and RECOMMENDED for most use cases.
	JWTClaims jwt.Claims

	// JWTKeyID is the key ID of the key used to sign the JWT. If this is empty, the first key in the JWK Set will be
	// used. If no key with the key ID is present when the magic link is visited, the service will produce a HTTP 500
	// error. Use of this field is OPTIONAL.
	JWTKeyID *string

	// JWTSigningMethod is a string that can be passed to jwt.GetSigningMethod to get the appropriate jwt.SigningMethod
	// to sign the JWT with. Do not populate this field unless you know what you are doing. By default, the most secure
	// method will be used. If a key type other than ECDSA, EdDSA, or RSA is used, then the most secure HMAC signing
	// method will be chosen by default. Use of this field is OPTIONAL and NOT RECOMMENDED for most use cases.
	JWTSigningMethod string

	// RedirectQueryKey is the URL query key used in the redirect. It will contain the JWT. If this is empty, "jwt" will
	// be used. Use of this field is OPTIONAL.
	RedirectQueryKey string

	// RedirectURL is the URL to redirect to after the JWT is verified. Use of this field is REQUIRED for all use cases.
	RedirectURL *url.URL
}

CreateParams are the parameters for creating a magic link.

func (CreateParams) Valid

func (p CreateParams) Valid() error

Valid confirms the CreateParams are valid.

type CreateResponse

type CreateResponse struct {
	MagicLink *url.URL
	Secret    string
}

CreateResponse is the response after a magic link has been created.

type ErrorHandler

type ErrorHandler interface {
	// Handle consumes an error and writes a response to the given writer. The set of possible errors to check by
	// unwrapping with errors.Is is documented above the interface's source code.
	Handle(args ErrorHandlerParams)
}

ErrorHandler handles errors that occur in MagicLink's HTTP handlers.

type ErrorHandlerFunc

type ErrorHandlerFunc func(args ErrorHandlerParams)

ErrorHandlerFunc is a function that implements the ErrorHandler interface.

func (ErrorHandlerFunc) Handle

func (f ErrorHandlerFunc) Handle(args ErrorHandlerParams)

Handle implements the ErrorHandler interface.

type ErrorHandlerParams

type ErrorHandlerParams struct {
	Err                   error
	Request               *http.Request
	SuggestedResponseCode int
	Writer                http.ResponseWriter
}

ErrorHandlerParams are the parameters passed to an ErrorHandler when an error occurs.

type JWKSParams

type JWKSParams struct {
	CacheRefresh time.Duration
	Store        jwkset.Storage
}

JWKSParams are the parameters for the MagicLink service's JWK Set.

type MagicLink

type MagicLink struct {
	Store Storage
	// contains filtered or unexported fields
}

MagicLink holds the necessary assets for the magic link service.

func NewMagicLink

func NewMagicLink(setupCtx context.Context, config Config) (MagicLink, error)

NewMagicLink creates a new MagicLink. The given setupCtx is only used during the creation of the MagicLink.

func (MagicLink) HandleMagicLink

func (m MagicLink) HandleMagicLink(ctx context.Context, secret string) (jwtB64 string, response ReadResult, err error)

HandleMagicLink is a method that accepts a magic link secret, then returns the signed JWT.

func (MagicLink) JWKSHandler

func (m MagicLink) JWKSHandler() http.Handler

JWKSHandler is an HTTP handler that responds to requests with the JWK Set as JSON.

func (MagicLink) JWKSet

func (m MagicLink) JWKSet() jwkset.Storage

JWKSet is a getter method to return the underlying JWK Set.

func (MagicLink) MagicLinkHandler

func (m MagicLink) MagicLinkHandler() http.Handler

MagicLinkHandler is an HTTP handler that accepts HTTP requests with magic link secrets, then redirects to the given URL with the JWT as a query parameter.

func (MagicLink) NewLink

func (m MagicLink) NewLink(ctx context.Context, args CreateParams) (CreateResponse, error)

NewLink creates a magic link with the given parameters.

type ReCAPTCHAV3Config

type ReCAPTCHAV3Config struct {
	APKPackageName []string                `json:"apkPackageName"`
	Action         []string                `json:"action"`
	Hostname       []string                `json:"hostname"`
	MinScore       float64                 `json:"minScore"`
	SecretKey      string                  `json:"secretKey"`
	TemplateData   ReCAPTCHAV3TemplateData `json:"templateData"`

	Verifier recaptcha.VerifierV3 `json:"-"`
}

ReCAPTCHAV3Config is the configuration for Google's reCAPTCHA v3.

func (ReCAPTCHAV3Config) DefaultsAndValidate

func (r ReCAPTCHAV3Config) DefaultsAndValidate() (ReCAPTCHAV3Config, error)

type ReCAPTCHAV3Redirector

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

ReCAPTCHAV3Redirector is a Redirector that uses Google's reCAPTCHA v3 to verify the user.

func (ReCAPTCHAV3Redirector) Redirect

func (r ReCAPTCHAV3Redirector) Redirect(args RedirectorParams)

type ReCAPTCHAV3TemplateData

type ReCAPTCHAV3TemplateData struct {
	ButtonBypass bool          `json:"buttonBypass"`
	ButtonText   string        `json:"buttonText"`
	CSS          template.CSS  `json:"css"`
	Code         string        `json:"code"`
	HTMLTitle    string        `json:"htmlTitle"`
	Instruction  string        `json:"instruction"`
	SiteKey      template.HTML `json:"siteKey"`
	Title        string        `json:"title"`

	FormAction string `json:"-"`
}

ReCAPTCHAV3TemplateData is the configuration for the HTML template for Google's reCAPTCHA v3.

func (ReCAPTCHAV3TemplateData) DefaultsAndValidate

func (r ReCAPTCHAV3TemplateData) DefaultsAndValidate() (ReCAPTCHAV3TemplateData, error)

DefaultsAndValidate implements the jsontype.Config interface.

type ReadResult

type ReadResult struct {
	// CreateParams are the parameters used to create the magic link.
	CreateParams CreateParams
	// Visited is the first time the magic link was visited. This is nil if the magic link has not been visited.
	Visited *time.Time
}

ReadResult is the result after a magic link has been read.

type Redirector

type Redirector interface {
	Redirect(args RedirectorParams)
}

Redirector is a custom implementation of redirecting a user to a magic link target.

func NewReCAPTCHAV3Redirector

func NewReCAPTCHAV3Redirector(config ReCAPTCHAV3Config) Redirector

NewReCAPTCHAV3Redirector creates a new ReCAPTCHAV3Redirector with the given config.

type RedirectorParams

type RedirectorParams struct {
	ReadAndExpireLink func(ctx context.Context, secret string) (jwtB64 string, response ReadResult, err error)
	Request           *http.Request
	Secret            string
	Writer            http.ResponseWriter
}

RedirectorParams are passed to a Redirector when performing a redirect.

type Storage

type Storage interface {
	// MagicLinkCreate creates a secret for the given parameters and stores the pair. The secret is returned to the
	// caller.
	MagicLinkCreate(ctx context.Context, params CreateParams) (secret string, err error)
	// MagicLinkRead finds the creation parameters for the given secret. ErrLinkNotFound is returned if the secret is
	// not found or was deleted/expired. This will automatically expire the link.
	MagicLinkRead(ctx context.Context, secret string) (ReadResult, error)
}

Storage represents the underlying storage for the MagicLink service.

func NewMemoryStorage

func NewMemoryStorage() Storage

NewMemoryStorage creates an in-memory implementation of the MagicLink Storage.