Crypto and Security

// Package token issues opaque session tokens for the shelf service.
package token

import "crypto/rand"

// New returns a new random session token.
func New() string { return rand.Text() }

package token

import (
	"testing"
	"testing/cryptotest"
)

func TestNewIsDeterministicUnderSetGlobalRandom(t *testing.T) {
	cryptotest.SetGlobalRandom(t, 1)
	first := New()
	t.Log("first token:", first)

	cryptotest.SetGlobalRandom(t, 1)
	if got := New(); got != first {
		t.Fatalf("same seed gave %q, want %q", got, first)
	}
	cryptotest.SetGlobalRandom(t, 2)
	if got := New(); got == first {
		t.Fatalf("different seed gave the same token %q", got)
	}
}

=== RUN   TestNewIsDeterministicUnderSetGlobalRandom
    token_test.go:11: first token: KGY7P5J3OYLTEOSH3FIOFZIUSB
--- PASS: TestNewIsDeterministicUnderSetGlobalRandom (0.00s)
PASS
ok  	example.com/shelf/e06	0.078s

package main

import (
	"crypto/hkdf"
	"crypto/sha256"
	"fmt"
)

func main() {
	key, err := hkdf.Key(sha256.New(), []byte("secret"), nil, "ctx", 32)
	fmt.Println(key, err)
}

# example.com/shelf/e19
e19/main.go:10:23: in call to hkdf.Key, type hash.Hash of sha256.New() does not match func() Hash (cannot infer Hash)

package main

import (
	"crypto/hkdf"
	"crypto/pbkdf2"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func main() {
	// PBKDF2-HMAC-SHA-256 with a fixed (example-only) salt so the output is
	// reproducible. Real salts are random per password.
	salt := []byte("0123456789abcdef")
	dk, err := pbkdf2.Key(sha256.New, "correct horse battery staple", salt, 600_000, 32)
	if err != nil {
		panic(err)
	}
	fmt.Println("pbkdf2", hex.EncodeToString(dk))

	// HKDF: derive independent subkeys from one high-entropy secret.
	secret := []byte("example-master-secret-not-real-0123456789")
	enc, err := hkdf.Key(sha256.New, secret, []byte("salt-1"), "shelf encryption", 32)
	if err != nil {
		panic(err)
	}
	mac, err := hkdf.Key(sha256.New, secret, []byte("salt-1"), "shelf mac", 32)
	if err != nil {
		panic(err)
	}
	fmt.Println("enc", hex.EncodeToString(enc))
	fmt.Println("mac", hex.EncodeToString(mac))

	// The two steps separately (RFC 5869).
	prk, _ := hkdf.Extract(sha256.New, secret, []byte("salt-1"))
	okm, _ := hkdf.Expand(sha256.New, prk, "shelf encryption", 32)
	fmt.Println("same", hex.EncodeToString(okm) == hex.EncodeToString(enc))

	// Invalid use is an error, not a panic.
	_, err = hkdf.Key(sha256.New, secret, nil, "x", 255*32+1)
	fmt.Println(err)
}

pbkdf2 6c4a646aad10d067add5fb79d9078a16da83d50f81670a8e7593b249e6d94936
enc 86761ba1d290c459260ffce5fcda0ee6d6df8855be65d602c2bdfe416ecc3537
mac e4d111f013114d0654e8579c52dea1df48571e2be0a047c625c43e8b651a18bf
same true
hkdf: requested key length too large

// Not run: needs golang.org/x/crypto, which is not available in this environment.
package auth

import (
	"crypto/rand"
	"crypto/subtle"
	"encoding/base64"
	"fmt"
	"strings"

	"golang.org/x/crypto/argon2"
)

const (
	memoryKiB = 19 * 1024 // OWASP minimum for time=2, threads=1
	passes    = 2
	threads   = 1
	keyLen    = 32
)

// Hash returns a self-describing string: parameters, salt and hash.
func Hash(password string) (string, error) {
	salt := make([]byte, 16)
	rand.Read(salt)
	key := argon2.IDKey([]byte(password), salt, passes, memoryKiB, threads, keyLen)
	return fmt.Sprintf("argon2id:%d:%d:%d:%s:%s", memoryKiB, passes, threads,
		base64.RawStdEncoding.EncodeToString(salt), base64.RawStdEncoding.EncodeToString(key)), nil
}

// Verify recomputes the hash with the stored parameters and compares in constant time.
func Verify(password, encoded string) bool {
	var m, t, p uint32
	parts := strings.Split(encoded, ":")
	if len(parts) != 6 || parts[0] != "argon2id" {
		return false
	}
	if _, err := fmt.Sscanf(strings.Join(parts[1:4], " "), "%d %d %d", &m, &t, &p); err != nil {
		return false
	}
	salt, err1 := base64.RawStdEncoding.DecodeString(parts[4])
	want, err2 := base64.RawStdEncoding.DecodeString(parts[5])
	if err1 != nil || err2 != nil {
		return false
	}
	got := argon2.IDKey([]byte(password), salt, t, m, uint8(p), uint32(len(want)))
	return subtle.ConstantTimeCompare(got, want) == 1
}

package main

import (
	"bytes"
	"crypto/mlkem"
	"crypto/sha256"
	"fmt"
)

func main() {
	// Receiver: generate a key pair and publish the encapsulation key.
	dk, err := mlkem.GenerateKey768()
	if err != nil {
		panic(err)
	}
	ek := dk.EncapsulationKey()
	pub := ek.Bytes()

	// Sender: parse the public key, derive a shared key and a ciphertext.
	peer, err := mlkem.NewEncapsulationKey768(pub)
	if err != nil {
		panic(err)
	}
	sharedA, ciphertext := peer.Encapsulate()

	// Receiver: recover the same shared key from the ciphertext.
	sharedB, err := dk.Decapsulate(ciphertext)
	if err != nil {
		panic(err)
	}
	fmt.Println(len(pub), len(ciphertext), len(sharedA), mlkem.SharedKeySize)
	fmt.Println(bytes.Equal(sharedA, sharedB))

	// A key is fully determined by its 64-byte seed, so it can be stored
	// compactly and rebuilt (the seed is the secret; keep it safe).
	seed := bytes.Repeat([]byte{0x2a}, mlkem.SeedSize)
	k1, _ := mlkem.NewDecapsulationKey768(seed)
	k2, _ := mlkem.NewDecapsulationKey768(seed)
	fmt.Printf("%x\n", sha256.Sum256(k1.EncapsulationKey().Bytes()))
	fmt.Println(bytes.Equal(k1.Bytes(), k2.Bytes()), len(k1.Bytes()))

	// ML-KEM decapsulation never fails on a well-sized ciphertext
	// (implicit rejection), but a wrong-sized one is an error.
	_, err = dk.Decapsulate(ciphertext[:10])
	fmt.Println(err)
	junk := make([]byte, len(ciphertext))
	wrong, err := dk.Decapsulate(junk)
	fmt.Println(err, bytes.Equal(wrong, sharedA))
}

1184 1088 32 32
true
61478b1d7a03527d8a2fa89ff7de964779a8d8a83492060282da375068dec694
true 64
mlkem: invalid ciphertext length
<nil> false

package main

import (
	"crypto/ecdh"
	"crypto/hpke"
	"fmt"
)

func main() {
	// Suite: hybrid post-quantum KEM + HKDF-SHA256 + ChaCha20-Poly1305.
	kem, kdf, aead := hpke.MLKEM768X25519(), hpke.HKDFSHA256(), hpke.ChaCha20Poly1305()
	fmt.Printf("kem=0x%04x kdf=0x%04x aead=0x%04x\n", kem.ID(), kdf.ID(), aead.ID())

	// The recipient owns the private key and publishes the public key.
	priv, err := kem.GenerateKey()
	if err != nil {
		panic(err)
	}
	pub := priv.PublicKey()
	fmt.Println("public key bytes:", len(pub.Bytes()))

	// One-shot API: the result is enc || ciphertext.
	info := []byte("shelf export v1")
	sealed, err := hpke.Seal(pub, kdf, aead, info, []byte("overdue list"))
	if err != nil {
		panic(err)
	}
	plain, err := hpke.Open(priv, kdf, aead, info, sealed)
	fmt.Printf("%d bytes sealed, opened %q, err=%v\n", len(sealed), plain, err)

	// A different info string derives different keys, so Open fails.
	_, err = hpke.Open(priv, kdf, aead, []byte("other app"), sealed)
	fmt.Println("wrong info:", err != nil)

	// Streaming API: one encapsulation, many messages with associated data.
	enc, sender, err := hpke.NewSender(pub, kdf, aead, info)
	if err != nil {
		panic(err)
	}
	recipient, err := hpke.NewRecipient(enc, priv, kdf, aead, info)
	if err != nil {
		panic(err)
	}
	for _, m := range []string{"first", "second"} {
		ct, err := sender.Seal([]byte("loan-42"), []byte(m))
		if err != nil {
			panic(err)
		}
		pt, err := recipient.Open([]byte("loan-42"), ct)
		fmt.Printf("%s %v\n", pt, err)
	}

	// Both ends can derive the same exported secret.
	a, _ := sender.Export("shelf/token", 16)
	b, _ := recipient.Export("shelf/token", 16)
	fmt.Println(string(a) == string(b), len(a))

	// The classic DHKEM from RFC 9180 is also available.
	fmt.Printf("dhkem x25519 id=0x%04x\n", hpke.DHKEM(ecdh.X25519()).ID())
}

kem=0x647a kdf=0x0001 aead=0x0003
public key bytes: 1216
1148 bytes sealed, opened "overdue list", err=<nil>
wrong info: true
first <nil>
second <nil>
true 16
dhkem x25519 id=0x0020

package main

import (
	"bytes"
	"crypto/ed25519"
	"crypto/mldsa"
	"crypto/sha256"
	"fmt"
)

func main() {
	msg := []byte("catalogue snapshot 2026-10-18")

	// ML-DSA (FIPS 204, Go 1.27). MLDSA44 is the parameter set the
	// documentation recommends for most applications.
	sk, err := mldsa.GenerateKey(mldsa.MLDSA44())
	if err != nil {
		panic(err)
	}
	pk := sk.PublicKey()
	sig, err := sk.Sign(nil, msg, nil) // hedged signing; the reader is ignored
	if err != nil {
		panic(err)
	}
	fmt.Println(len(sk.Bytes()), len(pk.Bytes()), len(sig), mldsa.MLDSA44().SignatureSize())
	fmt.Println("verify:", mldsa.Verify(pk, msg, sig, nil))
	fmt.Println("tampered:", mldsa.Verify(pk, []byte("catalogue snapshot 2099"), sig, nil))

	// A context string separates signatures made for different purposes.
	ctx := &mldsa.Options{Context: "shelf/snapshot"}
	sig2, _ := sk.Sign(nil, msg, ctx)
	fmt.Println("wrong context:", mldsa.Verify(pk, msg, sig2, nil))
	fmt.Println("right context:", mldsa.Verify(pk, msg, sig2, ctx))

	// The private key is a 32-byte seed: rebuild it, and with
	// SignDeterministic get a reproducible signature.
	seed := bytes.Repeat([]byte{7}, mldsa.PrivateKeySize)
	k, _ := mldsa.NewPrivateKey(mldsa.MLDSA44(), seed)
	d1, _ := k.SignDeterministic(msg, nil)
	d2, _ := k.SignDeterministic(msg, nil)
	fmt.Printf("%x\n", sha256.Sum256(k.PublicKey().Bytes()))
	fmt.Printf("%x\n", sha256.Sum256(d1))
	fmt.Println(bytes.Equal(d1, d2))

	// Ed25519 for comparison: classical, tiny and deterministic.
	edSeed := bytes.Repeat([]byte{9}, ed25519.SeedSize)
	edKey := ed25519.NewKeyFromSeed(edSeed)
	edSig := ed25519.Sign(edKey, msg)
	fmt.Println(len(edKey.Public().(ed25519.PublicKey)), len(edSig), ed25519.Verify(edKey.Public().(ed25519.PublicKey), msg, edSig))
	fmt.Printf("%x\n", sha256.Sum256(edSig))
}

32 1312 2420 2420
verify: <nil>
tampered: mldsa: invalid signature
wrong context: mldsa: invalid signature
right context: <nil>
86c769d3b468de487eb9a09f242f7fa0b997a07ef4ded49627e7bf9539f28b62
a2ba7afa7ca79e5d14ed31654d35b9de88e592994c1bc822fc6f25e4f20c9ef2
true
32 64 true
bbc109d8712b631ded3b00c6fe652aa9b5d0ddbc2fa0b3f7b48c90e632dbdf44

package main

import (
	"crypto/tls"
	"crypto/x509"
	"log"
	"net/http"
	"os"
	"time"
)

// serve starts shelfd with a hardened TLS configuration.
// certFile and keyFile come from the deployment, never from source code.
func serve(addr, certFile, keyFile, clientCAFile string) error {
	cfg := &tls.Config{
		MinVersion: tls.VersionTLS13, // only when every client supports it
	}

	if clientCAFile != "" { // optional mutual TLS
		pem, err := os.ReadFile(clientCAFile)
		if err != nil {
			return err
		}
		pool := x509.NewCertPool()
		if !pool.AppendCertsFromPEM(pem) {
			log.Fatal("no certificates in client CA file")
		}
		cfg.ClientCAs = pool
		cfg.ClientAuth = tls.RequireAndVerifyClientCert
	}

	srv := &http.Server{
		Addr:              addr,
		TLSConfig:         cfg,
		ReadHeaderTimeout: 5 * time.Second,
	}
	return srv.ListenAndServeTLS(certFile, keyFile)
}

func main() {
	log.Fatal(serve(":8443", os.Getenv("SHELFD_CERT"), os.Getenv("SHELFD_KEY"), os.Getenv("SHELFD_CLIENT_CA")))
}

2026/10/18 02:22:10 open /nonexistent: no such file or directory

# install a pinned version (not run)
go install golang.org/x/vuln/cmd/govulncheck@v1.9.0

# source mode: from the module root, same package patterns as the go command
govulncheck ./...

# more detail
govulncheck -show verbose ./...      # progress messages and extra findings
govulncheck -show traces ./...       # full call stacks
govulncheck -tags integration -test ./...   # include build tags and test files

# binary mode: scan an already built executable
govulncheck -mode binary $HOME/go/bin/shelfd

# machine-readable output for CI and dashboards
govulncheck -format json ./...       # streaming JSON
govulncheck -format sarif ./... > govulncheck.sarif
govulncheck -format openvex ./...

module example.com/shelf

go 1.27

tool golang.org/x/vuln/cmd/govulncheck

require golang.org/x/vuln v1.9.0

# adds the tool line and the requirement (not run)
go get -tool golang.org/x/vuln/cmd/govulncheck@v1.9.0
# runs the pinned version
go tool govulncheck ./...

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"strings"
)

func main() {
	base, err := os.MkdirTemp("", "shelf-covers-*")
	if err != nil {
		panic(err)
	}
	defer os.RemoveAll(base)

	uploads := filepath.Join(base, "uploads")
	if err := os.Mkdir(uploads, 0o755); err != nil {
		panic(err)
	}
	// A secret outside the upload directory, and a symlink pointing at it.
	if err := os.WriteFile(filepath.Join(base, "secret.txt"), []byte("not for clients"), 0o600); err != nil {
		panic(err)
	}
	if err := os.Symlink("../secret.txt", filepath.Join(uploads, "link.txt")); err != nil {
		panic(err)
	}

	root, err := os.OpenRoot(uploads)
	if err != nil {
		panic(err)
	}
	defer root.Close()

	if err := root.WriteFile("cover-1.txt", []byte("front cover"), 0o644); err != nil {
		panic(err)
	}
	data, err := root.ReadFile("cover-1.txt")
	fmt.Printf("%s %v\n", data, err)

	// Escapes are rejected, whether by ".." or by a symlink.
	for _, name := range []string{"../secret.txt", "link.txt", "/etc/passwd", "a/../../secret.txt"} {
		_, err := root.ReadFile(name)
		fmt.Printf("%-20s %s\n", name, short(err, base))
	}

	// Compare with the unsafe pattern: Join + Open follows ".." out of the tree.
	leaked, err := os.ReadFile(filepath.Join(uploads, "../secret.txt"))
	fmt.Printf("unsafe join: %s %v\n", leaked, err)

	// Validate first when you only have a name: filepath.IsLocal.
	for _, name := range []string{"cover-1.txt", "../secret.txt", "/abs", ""} {
		fmt.Printf("IsLocal(%q) = %v\n", name, filepath.IsLocal(name))
	}

	// A Root can be used where an fs.FS is expected.
	fsys := root.FS()
	_, err = fsys.Open("../secret.txt")
	fmt.Println("fs.FS:", short(err, base))
}

func short(err error, base string) string {
	if err == nil {
		return "<nil>"
	}
	return strings.ReplaceAll(err.Error(), base, "$BASE")
}

front cover <nil>
../secret.txt        openat ../secret.txt: path escapes from parent
link.txt             openat link.txt: path escapes from parent
/etc/passwd          openat /etc/passwd: path escapes from parent
a/../../secret.txt   openat a/../../secret.txt: no such file or directory
unsafe join: not for clients <nil>
IsLocal("cover-1.txt") = true
IsLocal("../secret.txt") = false
IsLocal("/abs") = false
IsLocal("") = false
fs.FS: open ../secret.txt: invalid argument

package main

import (
	"fmt"
	htmltemplate "html/template"
	"os"
	texttemplate "text/template"
)

type Book struct {
	Title string
	URL   string
}

func main() {
	b := Book{
		Title: `<script>alert("x")</script> & Co`,
		URL:   "javascript:alert(1)",
	}

	const page = `<p title="{{.Title}}">{{.Title}}</p>
<a href="{{.URL}}">link</a>
<a href="/search?q={{.Title}}">search</a>
<script>var title = {{.Title}};</script>
`
	fmt.Println("--- text/template (no escaping)")
	texttemplate.Must(texttemplate.New("t").Parse(page)).Execute(os.Stdout, b)

	fmt.Println("--- html/template (context-aware)")
	htmltemplate.Must(htmltemplate.New("h").Parse(page)).Execute(os.Stdout, b)

	// Wrapping untrusted text in htmltemplate.HTML turns the escaping OFF.
	fmt.Println("--- htmltemplate.HTML bypasses escaping")
	htmltemplate.Must(htmltemplate.New("x").Parse("<div>{{.}}</div>\n")).Execute(os.Stdout, htmltemplate.HTML(b.Title))
}

--- text/template (no escaping)
<p title="<script>alert("x")</script> & Co"><script>alert("x")</script> & Co</p>
<a href="javascript:alert(1)">link</a>
<a href="/search?q=<script>alert("x")</script> & Co">search</a>
<script>var title = <script>alert("x")</script> & Co;</script>
--- html/template (context-aware)
<p title="&lt;script&gt;alert(&#34;x&#34;)&lt;/script&gt; &amp; Co">&lt;script&gt;alert(&#34;x&#34;)&lt;/script&gt; &amp; Co</p>
<a href="#ZgotmplZ">link</a>
<a href="/search?q=%3cscript%3ealert%28%22x%22%29%3c%2fscript%3e%20%26%20Co">search</a>
<script>var title = "\u003cscript\u003ealert(\"x\")\u003c/script\u003e \u0026 Co";</script>
--- htmltemplate.HTML bypasses escaping
<div><script>alert("x")</script> & Co</div>

package store

import (
	"context"
	"database/sql"
	"fmt"
)

// Vulnerable: the title is pasted into the SQL text.
func FindUnsafe(ctx context.Context, db *sql.DB, title string) (*sql.Rows, error) {
	q := fmt.Sprintf("SELECT isbn, title FROM books WHERE title = '%s'", title)
	return db.QueryContext(ctx, q)
}

// Safe: the driver sends the value separately from the statement.
func Find(ctx context.Context, db *sql.DB, title string) (*sql.Rows, error) {
	return db.QueryContext(ctx, "SELECT isbn, title FROM books WHERE title = $1", title)
}

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"strings"
	"time"
)

func newServer(addr string) *http.Server {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /loans", func(w http.ResponseWriter, r *http.Request) {
		r.Body = http.MaxBytesReader(w, r.Body, 64) // cap the body at 64 bytes
		if _, err := io.Copy(io.Discard, r.Body); err != nil {
			http.Error(w, "body too large", http.StatusRequestEntityTooLarge)
			return
		}
		w.WriteHeader(http.StatusCreated)
	})

	// Go 1.25: reject cross-origin browser requests that change state.
	cop := http.NewCrossOriginProtection()

	return &http.Server{
		Addr:              addr,
		Handler:           securityHeaders(cop.Handler(mux)),
		ReadHeaderTimeout: 5 * time.Second,
		ReadTimeout:       10 * time.Second,
		WriteTimeout:      10 * time.Second,
		IdleTimeout:       60 * time.Second,
		MaxHeaderBytes:    16 << 10,
	}
}

func securityHeaders(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		h := w.Header()
		h.Set("X-Content-Type-Options", "nosniff")
		h.Set("Content-Security-Policy", "default-src 'none'")
		h.Set("Referrer-Policy", "no-referrer")
		next.ServeHTTP(w, r)
	})
}

func main() {
	s := newServer(":0")
	ts := httptest.NewServer(s.Handler)
	defer ts.Close()

	post := func(body string, hdr map[string]string) {
		req, _ := http.NewRequest("POST", ts.URL+"/loans", strings.NewReader(body))
		for k, v := range hdr {
			req.Header.Set(k, v)
		}
		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			panic(err)
		}
		b, _ := io.ReadAll(resp.Body)
		resp.Body.Close()
		fmt.Printf("%d %q nosniff=%s\n", resp.StatusCode, strings.TrimSpace(string(b)), resp.Header.Get("X-Content-Type-Options"))
	}
	post("small", nil)
	post(strings.Repeat("x", 200), nil)
	post("small", map[string]string{"Sec-Fetch-Site": "cross-site"})
	post("small", map[string]string{"Sec-Fetch-Site": "same-origin"})
}

201 "" nosniff=nosniff
413 "body too large" nosniff=nosniff
403 "cross-origin request detected from Sec-Fetch-Site header" nosniff=nosniff
201 "" nosniff=nosniff

package main

import (
	"errors"
	"fmt"
	"log/slog"
	"os"
)

// Secret hides its value from logs, fmt and JSON output.
type Secret string

func (Secret) String() string               { return "[REDACTED]" }
func (Secret) GoString() string             { return "[REDACTED]" }
func (Secret) MarshalText() ([]byte, error) { return []byte("[REDACTED]"), nil }
func (Secret) LogValue() slog.Value         { return slog.StringValue("[REDACTED]") }

type Config struct {
	DSN   string // contains a password: never log it
	Token Secret
}

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey && len(groups) == 0 {
				return slog.Attr{} // deterministic output for the example
			}
			return a
		},
	}))

	cfg := Config{DSN: "postgres://shelf:example-password@db.internal/shelf", Token: "example-token-not-real"}

	logger.Info("starting", "token", cfg.Token)
	logger.Info("config", slog.Any("cfg", cfg))
	fmt.Printf("%v %+v %#v %s\n", cfg.Token, cfg, cfg, cfg.Token)

	// Do not put credentials into errors either: name the host, not the DSN.
	cause := errors.New("connection refused")
	bad := fmt.Errorf("connect to %s: %w", cfg.DSN, cause)
	good := fmt.Errorf("connect to db.internal: %w", cause)
	logger.Error("db", "bad", bad)
	logger.Error("db", "good", good)
}

level=INFO msg=starting token=[REDACTED]
level=INFO msg=config cfg="{DSN:postgres://shelf:example-password@db.internal/shelf Token:[REDACTED]}"
[REDACTED] {DSN:postgres://shelf:example-password@db.internal/shelf Token:[REDACTED]} main.Config{DSN:"postgres://shelf:example-password@db.internal/shelf", Token:[REDACTED]} [REDACTED]
level=ERROR msg=db bad="connect to postgres://shelf:example-password@db.internal/shelf: connection refused"
level=ERROR msg=db good="connect to db.internal: connection refused"