lib.Options

Configuration options for initializing the Anubis middleware

Overview

The lib.Options struct contains configuration parameters for initializing an Anubis server instance. These options control middleware behavior, security settings, cookie configuration, and integration with upstream services.

Type Definition

type Options struct {
    Next                     http.Handler
    Policy                   *policy.ParsedConfig
    Target                   string
    TargetHost               string
    TargetSNI                string
    TargetInsecureSkipVerify bool
    CookieDynamicDomain      bool
    CookieDomain             string
    CookieExpiration         time.Duration
    CookiePartitioned        bool
    BasePrefix               string
    WebmasterEmail           string
    RedirectDomains          []string
    ED25519PrivateKey        ed25519.PrivateKey
    HS512Secret              []byte
    StripBasePrefix          bool
    OpenGraph                config.OpenGraph
    ServeRobotsTXT           bool
    CookieSecure             bool
    CookieSameSite           http.SameSite
    Logger                   *slog.Logger
    LogLevel                 string
    PublicUrl                string
    JWTRestrictionHeader     string
    DifficultyInJWT          bool
}

Fields

Next · http.Handler

HTTP handler to call after successful bot protection validation. This is typically your application’s main handler.

Policy · *policy.ParsedConfig · required

Parsed bot policy configuration containing bot rules, thresholds, and challenge settings.

Target · string

Target URL for reverse proxy mode. When set, Anubis acts as a reverse proxy to this upstream server.

TargetHost · string

Override the Host header when proxying requests to the target.

TargetSNI · string

SNI (Server Name Indication) value to use when connecting to the target over TLS.

TargetInsecureSkipVerify · bool · default: "false"

Skip TLS certificate verification when connecting to the target. Only use in development environments.

CookieDynamicDomain · bool · default: "false"

Enable dynamic cookie domain based on the request hostname.

CookieDomain · string

Domain attribute for authentication cookies. If empty, cookies are scoped to the current domain.

CookieExpiration · time.Duration · default: "24h"

Duration until authentication cookies expire.

CookiePartitioned · bool · default: "false"

Enable partitioned cookies (CHIPS) for improved privacy in third-party contexts.

BasePrefix · string · default: "/"

URL path prefix for all Anubis endpoints. Useful when mounting Anubis under a specific path.

WebmasterEmail · string

Contact email address displayed to users who are blocked or challenged.

RedirectDomains · []string

List of allowed domains for redirect validation to prevent open redirect vulnerabilities.

ED25519PrivateKey · ed25519.PrivateKey

Ed25519 private key for signing JWTs. Auto-generated if both this and HS512Secret are nil.

HS512Secret · []byte

HMAC-SHA512 secret for signing JWTs. Used instead of ED25519PrivateKey when set.

StripBasePrefix · bool · default: "false"

Remove the BasePrefix from requests before proxying to the target.

OpenGraph · config.OpenGraph

OpenGraph tag configuration for customizing social media previews.

ServeRobotsTXT · bool · default: "false"

Serve a robots.txt file at /robots.txt and /.well-known/robots.txt.

CookieSecure · bool · default: "true"

Set the Secure flag on authentication cookies, requiring HTTPS.

CookieSameSite · http.SameSite · default: "http.SameSiteLaxMode"

SameSite attribute for authentication cookies. Valid values: http.SameSiteDefaultMode, http.SameSiteLaxMode, http.SameSiteStrictMode, http.SameSiteNoneMode.

Logger · *slog.Logger

Structured logger instance. If nil, a default logger is created with subsystem=“anubis”.

LogLevel · string · default: "info"

Logging level. Valid values: debug, info, warn, error.

PublicUrl · string

Public-facing URL of the Anubis service. Used for generating absolute URLs in responses.

JWTRestrictionHeader · string

HTTP header name to check for JWT-based restrictions. When set, enables header-based authentication.

DifficultyInJWT · bool · default: "false"

Include challenge difficulty in JWT claims for verification.

Related Types

• config.OpenGraph - OpenGraph configuration
• policy.ParsedConfig - Parsed policy configuration

Example

import (
    "crypto/ed25519"
    "log/slog"
    "net/http"
    "time"

    "github.com/TecharoHQ/anubis/lib"
)

func main() {
    policy, err := lib.LoadPoliciesOrDefault(ctx, "policy.yaml", 20, "info")
    if err != nil {
        panic(err)
    }

    opts := lib.Options{
        Next:             yourAppHandler,
        Policy:           policy,
        CookieExpiration: 24 * time.Hour,
        CookieSecure:     true,
        CookieSameSite:   http.SameSiteLaxMode,
        Logger:           slog.Default(),
        LogLevel:         "info",
        ServeRobotsTXT:   true,
    }

    server, err := lib.New(opts)
    if err != nil {
        panic(err)
    }

    http.ListenAndServe(":8080", server)
}