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"
- X-DNS-Prefetch-Control: "off"
- X-Permitted-Cross-Domain-Policies: "none"
- Origin-Agent-Cluster: "?1"
Cross-Origin-Embedder-Policy and X-Download-Options are opt-in (off by default). Content-Security-Policy and Permissions-Policy are only emitted when their Config fields are non-empty.
Use New to create the middleware. Pass a Config to override defaults. Set any string field to Suppress ("-") to omit that individual header. Use Config.DisableHSTS to omit Strict-Transport-Security entirely. Use Config.Skip or Config.SkipPaths to bypass the middleware per request.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/middleware-security
Index ¶
Examples ¶
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.
Variables ¶
This section is empty.
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()
}
Output:
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,
})
}
Output:
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=()",
})
}
Output:
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: "" (NOT emitted — opt-in).
//
// COEP is off by default because "require-corp" blocks cross-origin
// resources (images, scripts, etc.) that lack a Cross-Origin-Resource-Policy
// or valid CORS headers — enabling it by default silently breaks many sites,
// so like helmet we leave it opt-in. Set "require-corp" or "credentialless"
// to enable.
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: "" (NOT emitted — opt-in). This header only affected legacy
// Internet Explorer downloads and is obsolete on modern browsers; set
// "noopen" to restore it.
XDownloadOptions string `yaml:"x_download_options"`
}
Config defines the security headers middleware configuration.
Source Files