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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions