builder.go

package crum

import (
	"errors"
	"net/http"
	"strings"
	"time"
	"unicode/utf8"
)

// CookieBuilder constructs a validated *http.Cookie with secure defaults.
// Zero values are not useful; always start with New(name, value).
type CookieBuilder struct {
	name      string
	value     string
	path      string
	domain    string
	expires   *time.Time
	maxAge    *int
	secure    *bool
	httpOnly  *bool
	sameSite  *http.SameSite
	partition *bool
	now       func() time.Time
	errs      []error
}

// NewCookie provides a small builder for constructing and validating *http.Cookie values with secure defaults.
//
// Defaults (unless overridden):
//   - Path: "/"                 (scopes cookie site-wide)
//   - Secure: true              (HTTPS only)
//   - HttpOnly: true            (inaccessible to JS, mitigates XSS exfiltration)
//   - SameSite: http.SameSiteLaxMode (mitigates CSRF while preserving typical flows)
//   - Session cookie: yes       (no Expires/MaxAge unless TTL/MaxAge is set)
//
// Notes
//   - RFC 6265 validation: we enforce a strict cookie-name token and forbid
//     disallowed value bytes (control chars, semicolons, commas, backslashes).
//   - SameSite=None requires Secure=true (enforced).
//   - MaxAge semantics (Go http.Cookie):
//     MaxAge < 0  => instructs deletion immediately
//     MaxAge == 0 => not present in Set-Cookie (i.e., session cookie)
//     MaxAge > 0  => persistent cookie with that lifetime in seconds
//   - Use Delete() to emit a cookie that removes the stored value on clients.
//   - The builder is not goroutine-safe; build per request.
//   - If you need non-ASCII values, URL-encode or base64-encode them first.
//
// Example (session cookie):
//
//	cb := crum.NewCookie("sid", sessionID).
//	    Domain("example.com").
//	    SameSiteLax(). // default, can be omitted
//	    MustBuild()
//
// Example (persistent login cookie, 30 days):
//
//	cb := crum.NewCookie("remember", token).
//	    TTL(30 * 24 * time.Hour).
//	    SameSiteStrict().
//	    MustBuild()
//
// Example (cross-site, third-party flow where needed):
//
//	cb := crum.NewCookie("cs", v).
//	    SameSiteNone(). // will also enforce Secure(true)
//	    TTL(24*time.Hour).
//	    MustBuild()
func NewCookie(name, value string) *CookieBuilder {
	secure := true
	httpOnly := true
	ss := http.SameSiteLaxMode
	return &CookieBuilder{
		name:     name,
		value:    value,
		path:     "/",
		secure:   &secure,
		httpOnly: &httpOnly,
		sameSite: &ss,
		now:      time.Now,
	}
}

// FromCookie constructs a new Builder prepopulated from an existing *http.Cookie.
//
// It copies all mutable fields (Name, Value, Path, Domain, Secure, HttpOnly,
// SameSite, Expires, MaxAge, Partitioned if supported). The returned Builder can
// then be modified further (e.g., Delete(), TTL(), Domain(), etc.).
//
// Useful for transforming or revoking cookies already set by your system:
//
//	newC := crum.FromCookie(c).Delete().MustBuild()
//
// The original cookie is never mutated.
func FromCookie(c *http.Cookie) *CookieBuilder {
	if c == nil {
		return NewCookie("", "")
	}

	b := &CookieBuilder{
		name:   c.Name,
		value:  c.Value,
		path:   c.Path,
		domain: c.Domain,
		now:    time.Now,
	}

	if !c.Expires.IsZero() {
		exp := c.Expires.UTC().Truncate(time.Second)
		b.expires = &exp
	}
	if c.MaxAge != 0 {
		m := c.MaxAge
		b.maxAge = &m
	}
	b.secure = &c.Secure
	b.httpOnly = &c.HttpOnly
	ss := c.SameSite
	b.sameSite = &ss
	b.partition = &c.Partitioned

	return b
}

// UnsafeValue allows setting an already-encoded value (e.g., URL/Base64).
// Values must be ASCII; control chars, semicolons, commas, and backslashes are rejected.
// Prefer encoding sensitive data before calling New/UnsafeValue.
func (b *CookieBuilder) UnsafeValue(v string) *CookieBuilder {
	b.value = v
	return b
}

// Path sets the cookie path. Empty becomes "/".
func (b *CookieBuilder) Path(p string) *CookieBuilder {
	if strings.TrimSpace(p) == "" {
		p = "/"
	}
	b.path = p
	return b
}

// Domain sets the cookie domain. The leading dot is normalized away.
func (b *CookieBuilder) Domain(d string) *CookieBuilder {
	d = strings.TrimPrefix(strings.TrimSpace(d), ".")
	b.domain = d
	return b
}

// Expires sets an absolute expiration time (also implies persistence).
// Prefer TTL() for relative lifetimes.
func (b *CookieBuilder) Expires(t time.Time) *CookieBuilder {
	tt := t.UTC().Truncate(time.Second)
	b.expires = &tt
	// If MaxAge isn't already set, infer it from now() to produce consistent MaxAge/Expires.
	if b.maxAge == nil {
		sec := int(tt.Sub(b.now()).Seconds())
		b.maxAge = &sec
	}
	return b
}

// TTL sets a relative lifetime. Sets both Expires and MaxAge coherently.
// TTL <= 0 results in a deletion cookie (MaxAge=-1, Expires in the past).
func (b *CookieBuilder) TTL(d time.Duration) *CookieBuilder {
	if d <= 0 {
		return b.Delete()
	}
	sec := int(d.Seconds())
	exp := b.now().Add(d).UTC().Truncate(time.Second)
	b.maxAge = &sec
	b.expires = &exp
	return b
}

// MaxAgeSeconds sets MaxAge directly. Use with care; prefer TTL() for coherence.
// MaxAge < 0 marks a deletion cookie; 0 yields a session cookie.
func (b *CookieBuilder) MaxAgeSeconds(s int) *CookieBuilder {
	b.maxAge = &s
	// If positive and Expires not set, synthesize Expires for wider client support:
	if s > 0 && b.expires == nil {
		exp := b.now().Add(time.Duration(s) * time.Second).UTC().Truncate(time.Second)
		b.expires = &exp
	}
	// If zero, leave Expires unset (session cookie). If negative, set past Expires in Delete().
	if s < 0 {
		past := b.now().Add(-365 * 24 * time.Hour).UTC()
		b.expires = &past
	}
	return b
}

// Session makes the cookie a session cookie (clears persistent attributes).
func (b *CookieBuilder) Session() *CookieBuilder {
	b.maxAge = nil
	b.expires = nil
	return b
}

// Delete configures the cookie to remove itself from clients.
func (b *CookieBuilder) Delete() *CookieBuilder {
	m := -1
	past := b.now().Add(-365 * 24 * time.Hour).UTC()
	b.maxAge = &m
	b.expires = &past
	// For deletion, also clear value by convention (servers differ; value may be ignored on delete).
	b.value = ""
	return b
}

// Secure toggles the Secure attribute (default true).
func (b *CookieBuilder) Secure(on bool) *CookieBuilder {
	b.secure = &on
	return b
}

// HttpOnly toggles the HttpOnly attribute (default true).
func (b *CookieBuilder) HttpOnly(on bool) *CookieBuilder {
	b.httpOnly = &on
	return b
}

// SameSiteStrict sets SameSite=Strict.
func (b *CookieBuilder) SameSiteStrict() *CookieBuilder {
	ss := http.SameSiteStrictMode
	b.sameSite = &ss
	return b
}

// SameSiteLax sets SameSite=Lax (default).
func (b *CookieBuilder) SameSiteLax() *CookieBuilder {
	ss := http.SameSiteLaxMode
	b.sameSite = &ss
	return b
}

// SameSiteNone sets SameSite=None and enforces Secure=true.
func (b *CookieBuilder) SameSiteNone() *CookieBuilder {
	ss := http.SameSiteNoneMode
	b.sameSite = &ss
	// Enforce Secure per modern browsers; do not silently allow insecure None.
	if b.secure == nil || !*b.secure {
		on := true
		b.secure = &on
	}
	return b
}

// WithClock injects a custom clock for testing (e.g., a fixed time).
func (b *CookieBuilder) WithClock(now func() time.Time) *CookieBuilder {
	if now != nil {
		b.now = now
	}
	return b
}

// Partitioned enables the Partitioned attribute.
func (b *CookieBuilder) Partitioned(on bool) *CookieBuilder {
	b.partition = &on
	return b
}

// Build returns a validated *http.Cookie or an error.
// It never panics; all constraints are returned as a single error via errors.Join.
func (b *CookieBuilder) Build() (*http.Cookie, error) {
	b.errs = b.errs[:0]

	if err := validateName(b.name); err != nil {
		b.errs = append(b.errs, err)
	}
	if err := validateValue(b.value); err != nil {
		b.errs = append(b.errs, err)
	}

	if b.domain != "" && !isASCII(b.domain) {
		b.errs = append(b.errs, errors.New("cookie domain must be ASCII"))
	}
	if strings.ContainsAny(b.domain, " \t\r\n") {
		b.errs = append(b.errs, errors.New("cookie domain must not contain whitespace"))
	}

	if b.sameSite != nil && *b.sameSite == http.SameSiteNoneMode {
		if b.secure == nil || !*b.secure {
			b.errs = append(b.errs, errors.New("SameSite=None requires Secure=true"))
		}
	}

	if b.path == "" {
		b.path = "/"
	}

	c := &http.Cookie{
		Name:     b.name,
		Value:    b.value,
		Path:     b.path,
		Domain:   b.domain,
		Secure:   derefOr(b.secure, true),
		HttpOnly: derefOr(b.httpOnly, true),
		SameSite: derefOr(b.sameSite, http.SameSiteLaxMode),
	}

	// Apply Expires/MaxAge as configured.
	if b.expires != nil {
		c.Expires = *b.expires
	}
	if b.maxAge != nil {
		c.MaxAge = *b.maxAge
	}

	if b.partition != nil {
		c.Partitioned = *b.partition
	}

	if len(b.errs) > 0 {
		return nil, errors.Join(b.errs...)
	}
	return c, nil
}

// MustBuild is like Build but panics if validation fails.
// Useful in init-time configuration or tests where failing fast is desired.
func (b *CookieBuilder) MustBuild() *http.Cookie {
	c, err := b.Build()
	if err != nil {
		panic(err)
	}
	return c
}

func derefOr[T any](in *T, def T) T {
	if in == nil {
		return def
	}
	return *in
}

func validateName(n string) error {
	if n == "" {
		return errors.New("cookie name must not be empty")
	}
	// RFC 6265 "token": 1*<any CHAR except CTLs or separators or whitespace or DEL>
	// We enforce a conservative set: ASCII alnum and - _ . ~
	for i := 0; i < len(n); i++ {
		ch := n[i]
		if (ch >= 'a' && ch <= 'z') ||
			(ch >= 'A' && ch <= 'Z') ||
			(ch >= '0' && ch <= '9') ||
			ch == '-' || ch == '_' || ch == '.' || ch == '~' {
			continue
		}
		return errors.New("cookie name contains invalid characters (allowed: A-Z a-z 0-9 - _ . ~)")
	}
	return nil
}

func validateValue(v string) error {
	// RFC 6265 cookie-octet excludes CTLs, DQUOTE, COMMA, SEMICOLON, BACKSLASH, and non-ASCII.
	if !isASCII(v) {
		return errors.New("cookie value must be ASCII; encode it (e.g., URL-encode or base64)")
	}
	if strings.ContainsAny(v, "\";,\\\n\r\t") {
		return errors.New("cookie value contains forbidden characters (\") (;) (,) (\\) or control chars")
	}
	return nil
}

func isASCII(s string) bool {
	return utf8.ValidString(s) && !strings.ContainsFunc(s, func(r rune) bool { return r > 0x7F })
}