golib/auth/expresscookie/README.md

expresscookie

A general-purpose package for signing and verifying secure cookies in all web applications. Its format is also compatible with the Node.js npm package cookie-signature, as used by Express session middleware.

Standard HMAC-SHA256 signature:

secret:       example-secret-16
string:       Hello, World!
payload:      SGVsbG8sIFdvcmxkIQ==
signed value: s:SGVsbG8sIFdvcmxkIQ==.F/bW1t2GXhUIqykISYbB+FMA3lLquegPU4jYjVLsnXs
cookie value: s%3ASGVsbG8sIFdvcmxkIQ%3D%3D.F%2FbW1t2GXhUIqykISYbB%2BFMA3lLquegPU4jYjVLsnXs

Usage

go get github.com/therootcompany/golib/auth/expresscookie@latest

Initialize the secret once during application setup:

secret, err := expresscookie.NewSecret([]byte(os.Getenv("COOKIE_SECRET")))

Payload: Encode payloads before signing (e.g., base64, JSON). The package signs raw bytes as supplied, but the behavior of non-encoded plain strings is undefined — in particular, raw payloads containing characters such as spaces may not interoperate with Node.js, which uses encodeURIComponent rather than query-string escaping. With zero-valued options, the cookie has zero-valued HTTP attributes except for the security defaults applied by Sign. These convenience defaults may change.

http.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
	cookie, err := r.Cookie("session")
	if err != nil {
		return
	}
	signed, err := expresscookie.Parse(cookie.Value)
	if err != nil {
		return
	}
	payload, err := signed.Verify(secret)
	if err != nil {
		http.Error(w, "invalid session", http.StatusUnauthorized)
		return
	}
	_, _ = w.Write(payload)
})

Sign and send a cookie:

payload := base64.StdEncoding.AppendEncode(nil, []byte(`{"user":"123"}`))
cookie, err := expresscookie.New("session", payload, http.Cookie{
	Expires: time.Now().Add(time.Hour),
})
if err != nil {
	return
}
signed := cookie.Sign(secret)
http.SetCookie(w, &signed.Cookie)

DecodeHexSecret decodes and validates an APP_SECRET-style hexadecimal key.

License

Authored in 2026 by AJ ONeal.

expresscookie is made available under the terms of any of the following licenses, at your option:

1. CC0 1.0 Universal
2. MIT License
3. Apache License 2.0

SPDX-License-Identifier: CC0-1.0 OR MIT OR Apache-2.0