Skip to content

Introduce SameSiteLevel string literal union type #583

Description

@colincasey

Part of #581.

Motivation

RFC 6265bis-22 §5.2 defines exactly three valid SameSite values: Strict, Lax, and None. Currently Cookie.sameSite is typed as string | undefined, meaning any arbitrary string compiles. The codebase already has internal matching logic in checkSameSiteContext that maps these values.

Current usage

class Cookie {
  sameSite: string | undefined  // accepts any string
}

interface SetCookieOptions {
  sameSiteContext?: 'strict' | 'lax' | 'none' | undefined  // already uses literal union here
}

Note: SetCookieOptions.sameSiteContext already uses the correct literal union — only Cookie.sameSite is overly permissive.

Type design

This is a string literal union, not a branded/nominal type, since the valid values are a small, fixed set:

export type SameSiteLevel = 'strict' | 'lax' | 'none';

API strategy

Public API change (narrowing — justified)

Property Current type New type Breaking?
Cookie.sameSite string | undefined SameSiteLevel | undefined Technically yes — but any consumer passing a value other than the three valid strings was already incorrect per the RFC
CreateCookieOptions.sameSite string | undefined SameSiteLevel | undefined Same rationale

Rationale for public change

  • The three values are exhaustively defined by the RFC
  • SetCookieOptions.sameSiteContext already uses this exact union — the types are inconsistent today
  • This is a type correction rather than a behavioral change — no runtime behavior changes
  • Consumers passing valid values are unaffected; consumers passing invalid values get a compile error pointing them to a real bug

Internal changes

  • checkSameSiteContext() can accept and return SameSiteLevel directly instead of parsing from string
  • Cookie parsing logic maps raw header values to SameSiteLevel | undefined at parse time

Metadata

Metadata

Assignees

No one assigned

    Labels

    6265bisOfficially proposed changes to RFC 6265

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions