secure

Documentation

Overview

Package secure provides OWASP security headers middleware for celeris.

The middleware sets a comprehensive suite of HTTP security headers on every response. All non-empty header values are pre-computed into a flat slice at initialization. The hot path iterates this slice with zero allocations.

Default headers set on every response:

• X-Content-Type-Options: "nosniff"
• X-Frame-Options: "SAMEORIGIN"
• X-XSS-Protection: "0" (disables legacy XSS auditor)
• Strict-Transport-Security (HTTPS only, 2-year max-age, includeSubDomains)
• Referrer-Policy: "strict-origin-when-cross-origin"
• Cross-Origin-Opener-Policy: "same-origin"
• Cross-Origin-Resource-Policy: "same-origin"
• Cross-Origin-Embedder-Policy: "require-corp"
• X-DNS-Prefetch-Control: "off"
• X-Permitted-Cross-Domain-Policies: "none"
• Origin-Agent-Cluster: "?1"
• X-Download-Options: "noopen"

Content-Security-Policy and Permissions-Policy are only included when their respective Config fields are non-empty.

Usage

Default configuration (all OWASP-recommended headers):

server.Use(secure.New())

Custom configuration:

server.Use(secure.New(secure.Config{
    ContentSecurityPolicy: "default-src 'self'",
    HSTSMaxAge:            31536000,
    HSTSPreload:           true,
}))

Suppressing Individual Headers

Set any string field to Suppress ("-") to omit that header:

server.Use(secure.New(secure.Config{
    XFrameOptions: secure.Suppress,
}))

For HSTS, set Config.DisableHSTS to true to omit the header entirely. HSTSMaxAge defaults to 2 years (63072000 seconds) whether or not other fields are customized — there is no zero-value trap.

HSTS Preload Validation

When Config.HSTSPreload is true, validate() panics at initialization if HSTSMaxAge < 31536000 or HSTSExcludeSubdomains is true, enforcing HSTS preload list requirements.

Skipping

Use Config.Skip for dynamic skip logic or Config.SkipPaths for exact-match path exclusions. Skipped requests receive no security headers at all.

CORS Interaction

When using CORS middleware alongside secure, note that the default CrossOriginEmbedderPolicy (require-corp) and CrossOriginResourcePolicy (same-origin) block cross-origin resource loading. APIs serving cross-origin requests should set CrossOriginResourcePolicy: "cross-origin" and CrossOriginEmbedderPolicy: Suppress.

Index

• Constants
• func New(config ...Config) celeris.HandlerFunc
• type Config

Examples

• New
• New (Custom)
• New (PermissionsPolicy)

Constants

const Suppress = "-"

Suppress is a sentinel value that, when set on a header field in Config, causes that header to be omitted from the response entirely. Unlike an empty string (which is overridden by the default), Suppress explicitly opts out of a header after defaults have been applied.

Functions

func New

func New(config ...Config) celeris.HandlerFunc

New creates a security headers middleware with the given config. All non-HSTS header values are pre-computed at initialization for zero-allocation responses on the hot path. HSTS is only sent over HTTPS connections (Scheme() checks X-Forwarded-Proto internally).

validate() panics at initialization for invalid configurations (e.g., HSTSPreload with insufficient MaxAge). This is intentional: misconfigurations are caught at startup, not at request time.

Example

package main

import (
	"github.com/goceleris/celeris/middleware/secure"
)

func main() {
	// Default OWASP-recommended security headers.
	_ = secure.New()
}

Example (Custom)

package main

import (
	"github.com/goceleris/celeris/middleware/secure"
)

func main() {
	// Custom CSP and HSTS with preload.
	_ = secure.New(secure.Config{
		ContentSecurityPolicy: "default-src 'self'; script-src 'self'",
		HSTSMaxAge:            31536000,
		HSTSPreload:           true,
	})
}

Example (PermissionsPolicy)

package main

import (
	"github.com/goceleris/celeris/middleware/secure"
)

func main() {
	// Restrict browser features via Permissions-Policy.
	_ = secure.New(secure.Config{
		PermissionsPolicy: "geolocation=(), camera=(), microphone=()",
	})
}

Types

type Config

type Config struct {
	// Skip defines a function to skip this middleware for certain requests.
	Skip func(c *celeris.Context) bool `yaml:"-"`

	// SkipPaths lists paths to skip (exact match).
	SkipPaths []string `yaml:"skip_paths"`

	// XContentTypeOptions sets the X-Content-Type-Options header.
	// Default: "nosniff".
	XContentTypeOptions string `yaml:"x_content_type_options"`

	// XFrameOptions sets the X-Frame-Options header.
	// Default: "SAMEORIGIN".
	XFrameOptions string `yaml:"x_frame_options"`

	// XSSProtection sets the X-XSS-Protection header.
	// Default: "0" (disables the XSS auditor, per modern best practice).
	XSSProtection string `yaml:"xss_protection"`

	// HSTSMaxAge sets the max-age directive of Strict-Transport-Security in seconds.
	// Default: 63072000 (2 years). Use [Config].DisableHSTS to omit the header.
	HSTSMaxAge int `yaml:"hsts_max_age"`

	// DisableHSTS omits the Strict-Transport-Security header entirely.
	// Default: false (HSTS is enabled with HSTSMaxAge).
	DisableHSTS bool `yaml:"disable_hsts"`

	// HSTSExcludeSubdomains opts out of includeSubDomains in the HSTS header.
	// By default includeSubDomains is included. Set to true to remove it.
	HSTSExcludeSubdomains bool `yaml:"hsts_exclude_subdomains"`

	// HSTSPreload adds preload to the HSTS header.
	// Default: false.
	HSTSPreload bool `yaml:"hsts_preload"`

	// ContentSecurityPolicy sets the Content-Security-Policy header.
	// Default: "" (omitted).
	ContentSecurityPolicy string `yaml:"content_security_policy"`

	// CSPReportOnly uses Content-Security-Policy-Report-Only instead of
	// Content-Security-Policy when true. Default: false.
	CSPReportOnly bool `yaml:"csp_report_only"`

	// ReferrerPolicy sets the Referrer-Policy header.
	// Default: "strict-origin-when-cross-origin".
	ReferrerPolicy string `yaml:"referrer_policy"`

	// PermissionsPolicy sets the Permissions-Policy header.
	// Default: "" (omitted).
	PermissionsPolicy string `yaml:"permissions_policy"`

	// CrossOriginOpenerPolicy sets the Cross-Origin-Opener-Policy header.
	// Default: "same-origin".
	CrossOriginOpenerPolicy string `yaml:"cross_origin_opener_policy"`

	// CrossOriginResourcePolicy sets the Cross-Origin-Resource-Policy header.
	// Default: "same-origin".
	CrossOriginResourcePolicy string `yaml:"cross_origin_resource_policy"`

	// CrossOriginEmbedderPolicy sets the Cross-Origin-Embedder-Policy header.
	// Default: "require-corp".
	//
	// WARNING: "require-corp" blocks cross-origin resources (images, scripts,
	// etc.) that do not carry a Cross-Origin-Resource-Policy header or valid
	// CORS headers. If your application loads third-party assets, use
	// "credentialless" or [Suppress] to avoid breakage.
	CrossOriginEmbedderPolicy string `yaml:"cross_origin_embedder_policy"`

	// XDNSPrefetchControl sets the X-DNS-Prefetch-Control header.
	// Default: "off".
	XDNSPrefetchControl string `yaml:"x_dns_prefetch_control"`

	// XPermittedCrossDomain sets the X-Permitted-Cross-Domain-Policies header.
	// Default: "none".
	XPermittedCrossDomain string `yaml:"x_permitted_cross_domain"`

	// OriginAgentCluster sets the Origin-Agent-Cluster header.
	// Default: "?1".
	OriginAgentCluster string `yaml:"origin_agent_cluster"`

	// XDownloadOptions sets the X-Download-Options header.
	// Default: "noopen".
	XDownloadOptions string `yaml:"x_download_options"`
}

Config defines the security headers middleware configuration.