README
¶
Secure Headers
arkoren.dev/core/http/middleware/secureheaders sets standard HTTP security headers for Arkoren handlers.
On an existing r router, restrict page resources to the same origin:
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.ContentSecurityPolicy("default-src 'self'; frame-ancestors 'none'")
}))
Without a callback, Middleware() uses its recommended security headers but
omits HSTS. Enable HSTS deliberately with StrictTransportSecurity only after
establishing your deployment's HTTPS policy; see the
Secure Headers guide.
Documentation
¶
Overview ¶
Package secureheaders provides HTTP security response-header middleware. Defaults prevent framing and content sniffing, limit referrer disclosure, and disable the legacy XSS auditor. The default Content Security Policy only forbids framing; applications must tailor resource-loading restrictions. HSTS is omitted by default because persistent HTTPS policy belongs to the deployment. Enable it deliberately with Builder.StrictTransportSecurity.
Example:
r := router.New() r.Use(secureheaders.Middleware())
Index ¶
- func Middleware(configure ...BuilderFunc) router.Middleware
- type Builder
- func (headers *Builder) ContentSecurityPolicy(value string) *Builder
- func (headers *Builder) ContentTypeOptions(value string) *Builder
- func (headers *Builder) FrameOptions(value string) *Builder
- func (headers *Builder) PermissionsPolicy(value string) *Builder
- func (headers *Builder) ReferrerPolicy(value string) *Builder
- func (headers *Builder) StrictTransportSecurity(value string) *Builder
- func (headers *Builder) XSSProtection(value string) *Builder
- type BuilderFunc
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Middleware ¶
func Middleware(configure ...BuilderFunc) router.Middleware
Middleware returns middleware that sets HTTP security response headers from the configuration. Headers with empty values are skipped. Recommended framing, content-type, referrer, and legacy XSS headers are enabled by default; HSTS requires explicit StrictTransportSecurity policy. Skipping a header does not remove a value set by another handler or proxy.
Example:
r := router.New() r.Use(secureheaders.Middleware())
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder configures Middleware before publication. Callbacks run directly once, synchronously in order on one fresh draft; nil entries panic. Retaining the draft cannot change published settings. Methods return the same draft. Construction starts with recommended security headers, except HSTS, which is opt-in through StrictTransportSecurity. Explicit empty values omit their headers and are never replaced by later default normalization.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.FrameOptions("")
}))
func (*Builder) ContentSecurityPolicy ¶
ContentSecurityPolicy controls the Content-Security-Policy header, which mitigates XSS and data-injection attacks. The default only forbids framing, matching FrameOptions; extend it for your application or set it to an empty string to omit it.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.ContentSecurityPolicy("")
}))
func (*Builder) ContentTypeOptions ¶
ContentTypeOptions controls the X-Content-Type-Options header, which prevents MIME-type sniffing.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.ContentTypeOptions("")
}))
func (*Builder) FrameOptions ¶
FrameOptions controls the X-Frame-Options header, which protects against clickjacking by restricting iframe embedding.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.FrameOptions("")
}))
func (*Builder) PermissionsPolicy ¶
PermissionsPolicy controls the Permissions-Policy header, which restricts browser feature access (camera, mic, etc.). Set it to an empty string to omit it.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.PermissionsPolicy("")
}))
func (*Builder) ReferrerPolicy ¶
ReferrerPolicy controls the Referrer-Policy header, which limits referrer information sent with requests.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.ReferrerPolicy("")
}))
func (*Builder) StrictTransportSecurity ¶
StrictTransportSecurity controls the Strict-Transport-Security header (HSTS), which forces HTTPS for subsequent requests. It is sent only on HTTPS requests, including those a proxy marks with "X-Forwarded-Proto: https". HSTS is omitted by default; applications must deliberately enable it after establishing their HTTPS deployment policy. An empty value omits the header but does not clear a browser's cached policy. Add includeSubDomains only when every subdomain serves HTTPS, and preload only after reviewing browser preload requirements and removal constraints.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.StrictTransportSecurity("max-age=86400")
}))
func (*Builder) XSSProtection ¶
XSSProtection controls the X-XSS-Protection header. The default value "0" disables the legacy XSS auditor, which is the current OWASP recommendation. The auditor has been removed from modern browsers and can introduce XSS vulnerabilities when enabled.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(secureheaders.Middleware(func(headers *secureheaders.Builder) {
headers.XSSProtection("")
}))
type BuilderFunc ¶
type BuilderFunc = func(*Builder)
BuilderFunc edits the construction draft shared by Middleware's callbacks. Callbacks run synchronously in order; a supplied nil callback panics, while expanding a nil or empty callback slice makes no edits. Construction begins with recommended headers and no HSTS; explicit empty values stay omitted.
Example:
configure := secureheaders.BuilderFunc(func(headers *secureheaders.Builder) {
headers.FrameOptions("")
})
routes := router.New()
routes.Use(secureheaders.Middleware(configure))
Example ¶
ExampleBuilderFunc demonstrates that explicit empty settings stay omitted and do not turn off other recommended defaults or opt into persistent HSTS.
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"arkoren.dev/core/http/middleware/secureheaders"
"arkoren.dev/core/http/router"
)
func main() {
configure := secureheaders.BuilderFunc(func(headers *secureheaders.Builder) {
headers.FrameOptions("")
})
routes := router.New()
routes.Use(secureheaders.Middleware(configure))
recorder := httptest.NewRecorder()
routes.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "https://service.example/", nil))
fmt.Printf("%q %q %q\n", recorder.Header().Get("X-Frame-Options"),
recorder.Header().Get("Strict-Transport-Security"), recorder.Header().Get("X-Content-Type-Options"))
}
Output: "" "" "nosniff"
Source Files