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 (determined by Context.Scheme).

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.