HTTP cookie parsing and management
README.md

nox-cookie #

Warning. This is a work-in-progress experimental fork of ocaml-cookeio. Do not use it in production; use ocaml-cookeio instead.

Parse, validate and store HTTP cookies in OCaml, following RFC 6265.

An HTTP client that keeps a session stores the cookies a server sets, sends back only those whose domain, path and Secure flag match each request, and forgets them when they expire. The Set-Cookie headers a server emits must be ones browsers accept. nox-cookie does both. It parses and writes Cookie and Set-Cookie headers with every attribute, including SameSite from the RFC 6265bis draft and the Partitioned attribute of CHIPS (Cookies Having Independent Partitioned State). A browser stores a Partitioned third-party cookie separately for each top-level site that embeds it, so the cookie cannot follow a user from one site to another. The parser rejects a Domain attribute that is a public suffix such as co.uk. The jar applies the matching and ordering rules of RFC 6265 Section 5.4. A jar can be saved and loaded in the Mozilla cookie file format.

nox-cookie is a fork of Anil Madhavapeddy's ocaml-cookeio. RFC-TODO.md lists where it still departs from RFC 6265: the jar enforces no storage limit and evicts no cookie.

Packages #

  • nox-cookie (module Cookie) parses, validates and writes cookies and the Cookie and Set-Cookie headers.
  • nox-cookie.jar (module Cookie_jar) stores cookies with domain and path matching, tracks the cookies a server still has to send (the delta), and reads and writes Mozilla cookie files. It uses Eio for the clock and files.

Install #

opam install nox-cookie

If opam cannot find the package, add the overlay repository first:

opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
opam update
opam install nox-cookie

Usage #

Parsing Headers #

Cookie.of_set_cookie_header takes the request host, the request path and whether the request used HTTPS. A cookie with no Path attribute takes the default-path of the request path (RFC 6265 Section 5.1.4):

# let now () = Ptime.epoch
val now : unit -> Ptime.t = <fun>
# let cookie =
    Cookie.of_set_cookie_header ~now ~domain:"example.com"
      ~path:"/docs/index.html" ~is_secure:true
      "session=abc123; Secure; HttpOnly; SameSite=Strict"
    |> Result.get_ok
val cookie : Cookie.t = <abstr>
# Cookie.path cookie
- : string = "/docs"
# Cookie.set_cookie_header cookie
- : string = "session=abc123; Path=/docs; Secure; HttpOnly; SameSite=Strict"

A Secure cookie received over plain HTTP is refused:

# Cookie.of_set_cookie_header ~now ~domain:"example.com" ~path:"/"
    ~is_secure:false "session=abc123; Secure"
  |> Result.map Cookie.name
- : (string, string) result =
Error "Secure cookie received over an insecure connection"

Cookie.of_request_header parses the Cookie header a server receives:

# Cookie.of_request_header ~now ~domain:"example.com" ~path:"/"
    "session=abc123; theme=dark"
  |> Result.map (List.map Cookie.name)
- : (string list, string) result = Ok ["session"; "theme"]

Serializing Headers #

let render_request (cookies : Cookie.t list) = Cookie.request_header cookies
let render_response (cookie : Cookie.t) = Cookie.set_cookie_header cookie

Creating Cookies #

let session_cookie ~now =
  Cookie.v ~domain:"example.com" ~path:"/" ~name:"session" ~value:"abc123"
    ~secure:true ~http_only:true ~same_site:`Strict ~creation_time:(now ())
    ~last_access:(now ()) ()
let api_cookies ~clock (cookie : Cookie.t) =
  let jar = Cookie_jar.v () in
  Cookie_jar.add_cookie jar cookie;
  let matching =
    Cookie_jar.cookies jar ~clock ~domain:"example.com" ~path:"/api"
      ~is_secure:true
  in
  Cookie.request_header matching

Delta Tracking #

let log_pending (jar : Cookie_jar.t) =
  Cookie_jar.delta jar
  |> List.iter (fun c -> Fmt.pr "%s@." (Cookie.set_cookie_header c))

Persistence #

A jar is saved in, and loaded from, the Mozilla cookie file format:

let save_jar ~path (jar : Cookie_jar.t) = Cookie_jar.save path jar
let load_jar ~clock ~path = Cookie_jar.load ~clock path

Validation #

Cookie.Validate checks names, values and attributes against the syntax RFC 6265 Section 4.1 requires of a server:

# Cookie.Validate.cookie_name "session";;
- : (string, string) result = Ok "session"

# Cookie.Validate.cookie_value "abc;123";;
- : (string, string) result =
Error
 "Cookie value \"abc;123\" contains invalid characters: semicolon (0x3B). RFC 6265 cookie values may only contain printable ASCII excluding double-quote, comma, semicolon, and backslash"

# Cookie.Validate.domain_value "example.com";;
- : (string, string) result = Ok "example.com"

License #

ISC. See LICENSE.md.