comparing a54c60c8e080cdd03888c25d22fddd52b7979381 and main on anil.recoil.org/ocaml-cookeio

+17 -2

.gitignore

···

       1
       1
       -
       _build

     

       2
       2
       -
       .*.swp

     

       1
       1
       +
       # OCaml build artifacts

     

       2
       2
       +
       _build/

     

       3
       3
       +
       *.install

     

       4
       4
       +
       *.merlin

     

       5
       5
       +
       

     

       6
       6
       +
       # Third-party sources (fetch locally with opam source)

     

       7
       7
       +
       third_party/

     

       8
       8
       +
       

     

       9
       9
       +
       # Editor and OS files

     

       10
       10
       +
       .DS_Store

     

       11
       11
       +
       *.swp

     

       12
       12
       +
       *~

     

       13
       13
       +
       .vscode/

     

       14
       14
       +
       .idea/

     

       15
       15
       +
       

     

       16
       16
       +
       # Opam local switch

     

       17
       17
       +
       _opam/

+1 -1

.ocamlformat

···

       1
       1
       -
       version=0.27.0

     

       1
       1
       +
       version=0.28.1

+53

.tangled/workflows/build.yml

···

       1
       1
       +
       when:

     

       2
       2
       +
         - event: ["push", "pull_request"]

     

       3
       3
       +
           branch: ["main"]

     

       4
       4
       +
       

     

       5
       5
       +
       engine: nixery

     

       6
       6
       +
       

     

       7
       7
       +
       dependencies:

     

       8
       8
       +
         nixpkgs:

     

       9
       9
       +
           - shell

     

       10
       10
       +
           - stdenv

     

       11
       11
       +
           - findutils

     

       12
       12
       +
           - binutils

     

       13
       13
       +
           - libunwind

     

       14
       14
       +
           - ncurses

     

       15
       15
       +
           - opam

     

       16
       16
       +
           - git

     

       17
       17
       +
           - gawk

     

       18
       18
       +
           - gnupatch

     

       19
       19
       +
           - gnum4

     

       20
       20
       +
           - gnumake

     

       21
       21
       +
           - gnutar

     

       22
       22
       +
           - gnused

     

       23
       23
       +
           - gnugrep

     

       24
       24
       +
           - diffutils

     

       25
       25
       +
           - gzip

     

       26
       26
       +
           - bzip2

     

       27
       27
       +
           - gcc

     

       28
       28
       +
           - ocaml

     

       29
       29
       +
           - pkg-config

     

       30
       30
       +
       

     

       31
       31
       +
       steps:

     

       32
       32
       +
         - name: opam

     

       33
       33
       +
           command: |

     

       34
       34
       +
              opam init --disable-sandboxing -a -y

     

       35
       35
       +
         - name: repo

     

       36
       36
       +
           command: |

     

       37
       37
       +
              opam repo add aoah https://tangled.org/anil.recoil.org/aoah-opam-repo.git

     

       38
       38
       +
         - name: switch

     

       39
       39
       +
           command: |

     

       40
       40
       +
              opam install . --confirm-level=unsafe-yes --deps-only

     

       41
       41
       +
         - name: build

     

       42
       42
       +
           command: |

     

       43
       43
       +
              opam exec -- dune build -p cookeio

     

       44
       44
       +
         - name: switch-test

     

       45
       45
       +
           command: |

     

       46
       46
       +
              opam install . --confirm-level=unsafe-yes --deps-only --with-test

     

       47
       47
       +
         - name: test

     

       48
       48
       +
           command: |

     

       49
       49
       +
              opam exec -- dune runtest --verbose

     

       50
       50
       +
         - name: doc

     

       51
       51
       +
           command: |

     

       52
       52
       +
              opam install -y odoc

     

       53
       53
       +
              opam exec -- dune build @doc

+16 -18

LICENSE.md

···

       1
       1
       -
       (*

     

       2
       2
       -
        * ISC License

     

       3
       3
       -
        * 

     

       4
       4
       -
        * Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>

     

       5
       5
       -
        *

     

       6
       6
       -
        * Permission to use, copy, modify, and distribute this software for any

     

       7
       7
       -
        * purpose with or without fee is hereby granted, provided that the above

     

       8
       8
       -
        * copyright notice and this permission notice appear in all copies.

     

       9
       9
       -
        *

     

       10
       10
       -
        * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES

     

       11
       11
       -
        * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

     

       12
       12
       -
        * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR

     

       13
       13
       -
        * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

     

       14
       14
       -
        * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

     

       15
       15
       -
        * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

     

       16
       16
       -
        * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

     

       17
       17
       -
        *

     

       18
       18
       -
        *)

     

       1
       1
       +
       

     

       2
       2
       +
       ISC License

     

       3
       3
       +
       

     

       4
       4
       +
       Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>

     

       5
       5
       +
       

     

       6
       6
       +
       Permission to use, copy, modify, and distribute this software for any

     

       7
       7
       +
       purpose with or without fee is hereby granted, provided that the above

     

       8
       8
       +
       copyright notice and this permission notice appear in all copies.

     

       9
       9
       +
       

     

       10
       10
       +
       THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES

     

       11
       11
       +
       WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

     

       12
       12
       +
       MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR

     

       13
       13
       +
       ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

     

       14
       14
       +
       WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

     

       15
       15
       +
       ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

     

       16
       16
       +
       OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

+173

RFC-TODO.md

···

       1
       1
       +
       # RFC 6265 Compliance TODO

     

       2
       2
       +
       

     

       3
       3
       +
       This document tracks deviations from [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265) (HTTP State Management Mechanism) and missing features in ocaml-cookeio.

     

       4
       4
       +
       

     

       5
       5
       +
       ## High Priority

     

       6
       6
       +
       

     

       7
       7
       +
       ### 1. Public Suffix Validation (Section 5.3, Step 5)

     

       8
       8
       +
       

     

       9
       9
       +
       **Status:** ✅ IMPLEMENTED

     

       10
       10
       +
       

     

       11
       11
       +
       The RFC requires rejecting cookies with domains that are "public suffixes" (e.g., `.com`, `.co.uk`) to prevent domain-wide cookie attacks.

     

       12
       12
       +
       

     

       13
       13
       +
       **Implementation:**

     

       14
       14
       +
       - Uses the `publicsuffix` library which embeds the Mozilla Public Suffix List at build time

     

       15
       15
       +
       - Validates Domain attribute in `of_set_cookie_header` before creating the cookie

     

       16
       16
       +
       - Rejects cookies where Domain is a public suffix (e.g., `.com`, `.co.uk`, `.github.io`)

     

       17
       17
       +
       - Allows cookies where the request host exactly matches the public suffix domain

     

       18
       18
       +
       - IP addresses bypass PSL validation (per RFC 6265 Section 5.1.3)

     

       19
       19
       +
       - Cookies without Domain attribute (host-only) are always allowed

     

       20
       20
       +
       

     

       21
       21
       +
       **Security impact:** Prevents attackers from setting domain-wide cookies that would affect all sites under a TLD.

     

       22
       22
       +
       

     

       23
       23
       +
       ---

     

       24
       24
       +
       

     

       25
       25
       +
       ## Medium Priority

     

       26
       26
       +
       

     

       27
       27
       +
       ### 2. IP Address Domain Matching (Section 5.1.3)

     

       28
       28
       +
       

     

       29
       29
       +
       **Status:** ✅ IMPLEMENTED

     

       30
       30
       +
       

     

       31
       31
       +
       The RFC specifies that domain suffix matching should only apply to host names, not IP addresses.

     

       32
       32
       +
       

     

       33
       33
       +
       **Implementation:**

     

       34
       34
       +
       - Uses the `ipaddr` library to detect IPv4 and IPv6 addresses

     

       35
       35
       +
       - IP addresses require exact match only (no suffix matching)

     

       36
       36
       +
       - Hostnames continue to support subdomain matching when `host_only = false`

     

       37
       37
       +
       

     

       38
       38
       +
       ---

     

       39
       39
       +
       

     

       40
       40
       +
       ### 3. Expires Header Date Format (Section 4.1.1)

     

       41
       41
       +
       

     

       42
       42
       +
       **Status:** Wrong format

     

       43
       43
       +
       

     

       44
       44
       +
       **Current behavior:** Outputs RFC3339 format (`2021-06-09T10:18:14+00:00`)

     

       45
       45
       +
       

     

       46
       46
       +
       **RFC requirement:** Use `rfc1123-date` format (`Wed, 09 Jun 2021 10:18:14 GMT`)

     

       47
       47
       +
       

     

       48
       48
       +
       **Location:** `cookeio.ml:447-448`

     

       49
       49
       +
       

     

       50
       50
       +
       **Fix:** Implement RFC1123 date formatting for Set-Cookie header output.

     

       51
       51
       +
       

     

       52
       52
       +
       ---

     

       53
       53
       +
       

     

       54
       54
       +
       ### 4. Cookie Ordering in Header (Section 5.4, Step 2)

     

       55
       55
       +
       

     

       56
       56
       +
       **Status:** ✅ IMPLEMENTED

     

       57
       57
       +
       

     

       58
       58
       +
       When generating Cookie headers, cookies are sorted:

     

       59
       59
       +
       1. Cookies with longer paths listed first

     

       60
       60
       +
       2. Among equal-length paths, earlier creation-times listed first

     

       61
       61
       +
       

     

       62
       62
       +
       **Implementation:** `get_cookies` function in `cookeio_jar.ml` uses `compare_cookie_order` to sort cookies before returning them.

     

       63
       63
       +
       

     

       64
       64
       +
       ---

     

       65
       65
       +
       

     

       66
       66
       +
       ### 5. Creation Time Preservation (Section 5.3, Step 11.3)

     

       67
       67
       +
       

     

       68
       68
       +
       **Status:** ✅ IMPLEMENTED

     

       69
       69
       +
       

     

       70
       70
       +
       When replacing an existing cookie (same name/domain/path), the creation-time of the old cookie is preserved.

     

       71
       71
       +
       

     

       72
       72
       +
       **Implementation:** `add_cookie` and `add_original` functions in `cookeio_jar.ml` use `preserve_creation_time` to retain the original creation time when updating an existing cookie.

     

       73
       73
       +
       

     

       74
       74
       +
       ---

     

       75
       75
       +
       

     

       76
       76
       +
       ### 6. Default Path Computation (Section 5.1.4)

     

       77
       77
       +
       

     

       78
       78
       +
       **Status:** Not implemented (caller responsibility)

     

       79
       79
       +
       

     

       80
       80
       +
       The RFC specifies an algorithm for computing default path when Path attribute is absent:

     

       81
       81
       +
       1. If uri-path is empty or doesn't start with `/`, return `/`

     

       82
       82
       +
       2. If uri-path contains only one `/`, return `/`

     

       83
       83
       +
       3. Return characters up to (but not including) the rightmost `/`

     

       84
       84
       +
       

     

       85
       85
       +
       **Suggestion:** Add `default_path : string -> string` helper function.

     

       86
       86
       +
       

     

       87
       87
       +
       ---

     

       88
       88
       +
       

     

       89
       89
       +
       ## Low Priority

     

       90
       90
       +
       

     

       91
       91
       +
       ### 7. Storage Limits (Section 6.1)

     

       92
       92
       +
       

     

       93
       93
       +
       **Status:** Not implemented

     

       94
       94
       +
       

     

       95
       95
       +
       RFC recommends minimum capabilities:

     

       96
       96
       +
       - At least 4096 bytes per cookie

     

       97
       97
       +
       - At least 50 cookies per domain

     

       98
       98
       +
       - At least 3000 cookies total

     

       99
       99
       +
       

     

       100
       100
       +
       **Suggestion:** Add configurable limits with RFC-recommended defaults.

     

       101
       101
       +
       

     

       102
       102
       +
       ---

     

       103
       103
       +
       

     

       104
       104
       +
       ### 8. Excess Cookie Eviction (Section 5.3)

     

       105
       105
       +
       

     

       106
       106
       +
       **Status:** Not implemented

     

       107
       107
       +
       

     

       108
       108
       +
       When storage limits are exceeded, evict in priority order:

     

       109
       109
       +
       1. Expired cookies

     

       110
       110
       +
       2. Cookies sharing domain with many others

     

       111
       111
       +
       3. All cookies

     

       112
       112
       +
       

     

       113
       113
       +
       Tiebreaker: earliest `last-access-time` first (LRU).

     

       114
       114
       +
       

     

       115
       115
       +
       ---

     

       116
       116
       +
       

     

       117
       117
       +
       ### 9. Two-Digit Year Parsing (Section 5.1.1)

     

       118
       118
       +
       

     

       119
       119
       +
       **Status:** Minor deviation

     

       120
       120
       +
       

     

       121
       121
       +
       **RFC specification:**

     

       122
       122
       +
       - Years 70-99 → add 1900

     

       123
       123
       +
       - Years 0-69 → add 2000

     

       124
       124
       +
       

     

       125
       125
       +
       **Current code** (`cookeio.ml:128-130`):

     

       126
       126
       +
       ```ocaml

     

       127
       127
       +
       if year >= 0 && year <= 68 then year + 2000

     

       128
       128
       +
       else if year >= 69 && year <= 99 then year + 1900

     

       129
       129
       +
       ```

     

       130
       130
       +
       

     

       131
       131
       +
       **Issue:** Year 69 is treated as 1969, but RFC says 70-99 get 1900, implying 69 should get 2000.

     

       132
       132
       +
       

     

       133
       133
       +
       ---

     

       134
       134
       +
       

     

       135
       135
       +
       ## Compliant Features

     

       136
       136
       +
       

     

       137
       137
       +
       The following RFC requirements are correctly implemented:

     

       138
       138
       +
       

     

       139
       139
       +
       - [x] Case-insensitive attribute name matching (Section 5.2)

     

       140
       140
       +
       - [x] Leading dot removal from Domain attribute (Section 5.2.3)

     

       141
       141
       +
       - [x] Max-Age takes precedence over Expires (Section 5.3, Step 3)

     

       142
       142
       +
       - [x] Secure flag handling (Section 5.2.5)

     

       143
       143
       +
       - [x] HttpOnly flag handling (Section 5.2.6)

     

       144
       144
       +
       - [x] Cookie date parsing with multiple format support (Section 5.1.1)

     

       145
       145
       +
       - [x] Session vs persistent cookie distinction (Section 5.3)

     

       146
       146
       +
       - [x] Last-access-time updates on retrieval (Section 5.4, Step 3)

     

       147
       147
       +
       - [x] Host-only flag for domain matching (Section 5.3, Step 6)

     

       148
       148
       +
       - [x] Path matching algorithm (Section 5.1.4)

     

       149
       149
       +
       - [x] IP address domain matching - exact match only (Section 5.1.3)

     

       150
       150
       +
       - [x] Cookie ordering in headers - longer paths first, then by creation time (Section 5.4, Step 2)

     

       151
       151
       +
       - [x] Creation time preservation when replacing cookies (Section 5.3, Step 11.3)

     

       152
       152
       +
       - [x] Public suffix validation - rejects cookies for TLDs like .com (Section 5.3, Step 5)

     

       153
       153
       +
       

     

       154
       154
       +
       ---

     

       155
       155
       +
       

     

       156
       156
       +
       ## Extensions Beyond RFC 6265

     

       157
       157
       +
       

     

       158
       158
       +
       These features are implemented but not part of RFC 6265:

     

       159
       159
       +
       

     

       160
       160
       +
       | Feature | Specification |

     

       161
       161
       +
       |---------|---------------|

     

       162
       162
       +
       | SameSite | RFC 6265bis (draft) |

     

       163
       163
       +
       | Partitioned | CHIPS proposal |

     

       164
       164
       +
       | Mozilla format | De facto standard |

     

       165
       165
       +
       

     

       166
       166
       +
       ---

     

       167
       167
       +
       

     

       168
       168
       +
       ## References

     

       169
       169
       +
       

     

       170
       170
       +
       - [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265) - HTTP State Management Mechanism

     

       171
       171
       +
       - [RFC 6265bis](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis) - Updated cookie spec (draft)

     

       172
       172
       +
       - [Public Suffix List](https://publicsuffix.org/) - Mozilla's public suffix database

     

       173
       173
       +
       - [CHIPS](https://developer.chrome.com/docs/privacy-sandbox/chips/) - Cookies Having Independent Partitioned State

+18

bin/cookeiocat.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
         Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.

     

       3
       3
       +
         SPDX-License-Identifier: ISC

     

       4
       4
       +
        ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       let () =

     

       7
       7
       +
         Eio_main.run @@ fun env ->

     

       8
       8
       +
         let args = Sys.argv in

     

       9
       9
       +
         if Array.length args < 2 then (

     

       10
       10
       +
           Printf.eprintf "Usage: %s <cookies.txt>\n" args.(0);

     

       11
       11
       +
           exit 1

     

       12
       12
       +
         );

     

       13
       13
       +
         let file_path = args.(1) in

     

       14
       14
       +
         let fs = Eio.Stdenv.fs env in

     

       15
       15
       +
         let clock = Eio.Stdenv.clock env in

     

       16
       16
       +
         let path = Eio.Path.(fs / file_path) in

     

       17
       17
       +
         let jar = Cookeio_jar.load ~clock path in

     

       18
       18
       +
         Format.printf "%a@." Cookeio_jar.pp jar

bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name cookeiocat)

     

       3
       3
       +
        (public_name cookeiocat)

     

       4
       4
       +
        (libraries cookeio cookeio.jar eio_main ptime))

+11 -8

cookeio.opam

···

       1
       1
        
       # This file is generated by dune, edit dune-project instead

     

       2
       2
        
       opam-version: "2.0"

     

       3
       3
       -
       synopsis: "Cookie parsing and management library using Eio"

     

       3
       3
       +
       synopsis: "Cookie parsing and management library"

     

       4
       4
        
       description:

     

       5
       5
       -
         "Cookeio provides cookie management functionality for OCaml applications, including parsing Set-Cookie headers, managing cookie jars, and supporting the Mozilla cookies.txt format for persistence."

     

       6
       6
       -
       maintainer: ["Anil Madhavapeddy"]

     

       5
       5
       +
         "Cookeio provides cookie parsing and serialization for OCaml applications. It handles parsing Set-Cookie and Cookie headers with full support for all cookie attributes."

     

       6
       6
       +
       maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]

     

       7
       7
        
       authors: ["Anil Madhavapeddy"]

     

       8
       8
        
       license: "ISC"

     

       9
       9
       -
       homepage: "https://github.com/avsm/cookeio"

     

       10
       10
       -
       bug-reports: "https://github.com/avsm/cookeio/issues"

     

       9
       9
       +
       homepage: "https://tangled.sh/@anil.recoil.org/ocaml-cookeio"

     

       10
       10
       +
       doc: "https://tangled.sh/@anil.recoil.org/ocaml-cookeio"

     

       11
       11
       +
       bug-reports: "https://tangled.sh/@anil.recoil.org/ocaml-cookeio/issues"

     

       11
       12
        
       depends: [

     

       13
       13
       +
         "dune" {>= "3.18"}

     

       12
       14
        
         "ocaml" {>= "5.2.0"}

     

       13
       13
       -
         "dune" {>= "3.19"}

     

       14
       14
       -
         "eio" {>= "1.0"}

     

       15
       15
        
         "logs" {>= "0.9.0"}

     

       16
       16
        
         "ptime" {>= "1.1.0"}

     

       17
       17
       +
         "ipaddr" {>= "5.6.0"}

     

       18
       18
       +
         "domain-name" {>= "0.4.0"}

     

       19
       19
       +
         "publicsuffix"

     

       20
       20
       +
         "eio_main"

     

       17
       21
        
         "alcotest" {with-test}

     

       18
       22
        
         "odoc" {with-doc}

     

       19
       23
        
       ]

     
···

       31
       35
        
           "@doc" {with-doc}

     

       32
       36
        
         ]

     

       33
       37
        
       ]

     

       34
       34
       -
       dev-repo: "git+https://github.com/avsm/cookeio.git"

     

       35
       38
        
       x-maintenance-intent: ["(latest)"]

+15 -10

dune-project

···

       1
       1
       -
       (lang dune 3.19)

     

       1
       1
       +
       (lang dune 3.18)

     

       2
       2
        
       

     

       3
       3
        
       (name cookeio)

     

       4
       4
        
       

     

       5
       5
        
       (generate_opam_files true)

     

       6
       6
        
       

     

       7
       7
       -
       (source (github avsm/cookeio))

     

       8
       8
       -
       

     

       7
       7
       +
       (license ISC)

     

       9
       8
        
       (authors "Anil Madhavapeddy")

     

       10
       10
       -
       (maintainers "Anil Madhavapeddy")

     

       11
       11
       -
       (license ISC)

     

       9
       9
       +
       (homepage "https://tangled.sh/@anil.recoil.org/ocaml-cookeio")

     

       10
       10
       +
       (maintainers "Anil Madhavapeddy <anil@recoil.org>")

     

       11
       11
       +
       (bug_reports "https://tangled.sh/@anil.recoil.org/ocaml-cookeio/issues")

     

       12
       12
       +
       (documentation "https://tangled.sh/@anil.recoil.org/ocaml-cookeio")

     

       13
       13
       +
       (maintenance_intent "(latest)")

     

       12
       14
        
       

     

       13
       15
        
       (package

     

       14
       16
        
        (name cookeio)

     

       15
       15
       -
        (synopsis "Cookie parsing and management library using Eio")

     

       16
       16
       -
        (description "Cookeio provides cookie management functionality for OCaml applications, including parsing Set-Cookie headers, managing cookie jars, and supporting the Mozilla cookies.txt format for persistence.")

     

       17
       17
       +
        (synopsis "Cookie parsing and management library")

     

       18
       18
       +
        (description "Cookeio provides cookie parsing and serialization for OCaml applications. It handles parsing Set-Cookie and Cookie headers with full support for all cookie attributes.")

     

       17
       19
        
        (depends

     

       18
       20
        
         (ocaml (>= 5.2.0))

     

       19
       19
       -
         dune

     

       20
       20
       -
         (eio (>= 1.0))

     

       21
       21
        
         (logs (>= 0.9.0))

     

       22
       22
        
         (ptime (>= 1.1.0))

     

       23
       23
       -
         (alcotest :with-test)))

     

       23
       23
       +
         (ipaddr (>= 5.6.0))

     

       24
       24
       +
         (domain-name (>= 0.4.0))

     

       25
       25
       +
         publicsuffix

     

       26
       26
       +
         eio_main

     

       27
       27
       +
         (alcotest :with-test)

     

       28
       28
       +
         (odoc :with-doc)))

-424

lib/cookeio.ml

···

       1
       1
       -
       let src = Logs.Src.create "cookeio" ~doc:"Cookie management"

     

       2
       2
       -
       

     

       3
       3
       -
       module Log = (val Logs.src_log src : Logs.LOG)

     

       4
       4
       -
       

     

       5
       5
       -
       type same_site = [ `Strict | `Lax | `None ]

     

       6
       6
       -
       (** Cookie same-site policy *)

     

       7
       7
       -
       

     

       8
       8
       -
       type t = {

     

       9
       9
       -
         domain : string;

     

       10
       10
       -
         path : string;

     

       11
       11
       -
         name : string;

     

       12
       12
       -
         value : string;

     

       13
       13
       -
         secure : bool;

     

       14
       14
       -
         http_only : bool;

     

       15
       15
       -
         expires : Ptime.t option;

     

       16
       16
       -
         same_site : same_site option;

     

       17
       17
       -
         creation_time : Ptime.t;

     

       18
       18
       -
         last_access : Ptime.t;

     

       19
       19
       -
       }

     

       20
       20
       -
       (** HTTP Cookie *)

     

       21
       21
       -
       

     

       22
       22
       -
       type jar = { mutable cookies : t list; mutex : Eio.Mutex.t }

     

       23
       23
       -
       (** Cookie jar for storing and managing cookies *)

     

       24
       24
       -
       

     

       25
       25
       -
       (** {1 Cookie Accessors} *)

     

       26
       26
       -
       

     

       27
       27
       -
       let domain cookie = cookie.domain

     

       28
       28
       -
       let path cookie = cookie.path

     

       29
       29
       -
       let name cookie = cookie.name

     

       30
       30
       -
       let value cookie = cookie.value

     

       31
       31
       -
       let secure cookie = cookie.secure

     

       32
       32
       -
       let http_only cookie = cookie.http_only

     

       33
       33
       -
       let expires cookie = cookie.expires

     

       34
       34
       -
       let same_site cookie = cookie.same_site

     

       35
       35
       -
       let creation_time cookie = cookie.creation_time

     

       36
       36
       -
       let last_access cookie = cookie.last_access

     

       37
       37
       -
       

     

       38
       38
       -
       let make ~domain ~path ~name ~value ?(secure = false) ?(http_only = false)

     

       39
       39
       -
           ?expires ?same_site ~creation_time ~last_access () =

     

       40
       40
       -
         { domain; path; name; value; secure; http_only; expires; same_site; creation_time; last_access }

     

       41
       41
       -
       

     

       42
       42
       -
       (** {1 Cookie Jar Creation} *)

     

       43
       43
       -
       

     

       44
       44
       -
       let create () =

     

       45
       45
       -
         Log.debug (fun m -> m "Creating new empty cookie jar");

     

       46
       46
       -
         { cookies = []; mutex = Eio.Mutex.create () }

     

       47
       47
       -
       

     

       48
       48
       -
       (** {1 Cookie Matching Helpers} *)

     

       49
       49
       -
       

     

       50
       50
       -
       let domain_matches cookie_domain request_domain =

     

       51
       51
       -
         (* Cookie domain .example.com matches example.com and sub.example.com *)

     

       52
       52
       -
         if String.starts_with ~prefix:"." cookie_domain then

     

       53
       53
       -
           let domain_suffix = String.sub cookie_domain 1 (String.length cookie_domain - 1) in

     

       54
       54
       -
           request_domain = domain_suffix

     

       55
       55
       -
           || String.ends_with ~suffix:("." ^ domain_suffix) request_domain

     

       56
       56
       -
         else cookie_domain = request_domain

     

       57
       57
       -
       

     

       58
       58
       -
       let path_matches cookie_path request_path =

     

       59
       59
       -
         (* Cookie path /foo matches /foo, /foo/, /foo/bar *)

     

       60
       60
       -
         String.starts_with ~prefix:cookie_path request_path

     

       61
       61
       -
       

     

       62
       62
       -
       let is_expired cookie clock =

     

       63
       63
       -
         match cookie.expires with

     

       64
       64
       -
         | None -> false (* Session cookie *)

     

       65
       65
       -
         | Some exp_time ->

     

       66
       66
       -
             let now =

     

       67
       67
       -
               Ptime.of_float_s (Eio.Time.now clock)

     

       68
       68
       -
               |> Option.value ~default:Ptime.epoch

     

       69
       69
       -
             in

     

       70
       70
       -
             Ptime.compare now exp_time > 0

     

       71
       71
       -
       

     

       72
       72
       -
       (** {1 Cookie Parsing} *)

     

       73
       73
       -
       

     

       74
       74
       -
       (** Accumulated attributes from parsing Set-Cookie header *)

     

       75
       75
       -
       type cookie_attributes = {

     

       76
       76
       -
         mutable domain : string option;

     

       77
       77
       -
         mutable path : string option;

     

       78
       78
       -
         mutable secure : bool;

     

       79
       79
       -
         mutable http_only : bool;

     

       80
       80
       -
         mutable expires : Ptime.t option;

     

       81
       81
       -
         mutable same_site : same_site option;

     

       82
       82
       -
       }

     

       83
       83
       -
       

     

       84
       84
       -
       (** Create empty attribute accumulator *)

     

       85
       85
       -
       let empty_attributes () =

     

       86
       86
       -
         {

     

       87
       87
       -
           domain = None;

     

       88
       88
       -
           path = None;

     

       89
       89
       -
           secure = false;

     

       90
       90
       -
           http_only = false;

     

       91
       91
       -
           expires = None;

     

       92
       92
       -
           same_site = None;

     

       93
       93
       -
         }

     

       94
       94
       -
       

     

       95
       95
       -
       (** Parse a single attribute and update the accumulator in-place *)

     

       96
       96
       -
       let parse_attribute clock attrs attr_name attr_value =

     

       97
       97
       -
         let attr_lower = String.lowercase_ascii attr_name in

     

       98
       98
       -
         match attr_lower with

     

       99
       99
       -
         | "domain" -> attrs.domain <- Some attr_value

     

       100
       100
       -
         | "path" -> attrs.path <- Some attr_value

     

       101
       101
       -
         | "expires" -> (

     

       102
       102
       -
             match Ptime.of_rfc3339 attr_value with

     

       103
       103
       -
             | Ok (time, _, _) -> attrs.expires <- Some time

     

       104
       104
       -
             | Error (`RFC3339 (_, err)) ->

     

       105
       105
       -
                 Log.warn (fun m ->

     

       106
       106
       -
                     m "Failed to parse expires attribute '%s': %a" attr_value

     

       107
       107
       -
                       Ptime.pp_rfc3339_error err))

     

       108
       108
       -
         | "max-age" -> (

     

       109
       109
       -
             match int_of_string_opt attr_value with

     

       110
       110
       -
             | Some seconds ->

     

       111
       111
       -
                 let now = Eio.Time.now clock in

     

       112
       112
       -
                 let expires = Ptime.of_float_s (now +. float_of_int seconds) in

     

       113
       113
       -
                 attrs.expires <- expires

     

       114
       114
       -
             | None ->

     

       115
       115
       -
                 Log.warn (fun m -> m "Failed to parse max-age attribute '%s'" attr_value))

     

       116
       116
       -
         | "secure" -> attrs.secure <- true

     

       117
       117
       -
         | "httponly" -> attrs.http_only <- true

     

       118
       118
       -
         | "samesite" -> (

     

       119
       119
       -
             match String.lowercase_ascii attr_value with

     

       120
       120
       -
             | "strict" -> attrs.same_site <- Some `Strict

     

       121
       121
       -
             | "lax" -> attrs.same_site <- Some `Lax

     

       122
       122
       -
             | "none" -> attrs.same_site <- Some `None

     

       123
       123
       -
             | _ ->

     

       124
       124
       -
                 Log.warn (fun m -> m "Invalid samesite value '%s', ignoring" attr_value))

     

       125
       125
       -
         | _ ->

     

       126
       126
       -
             Log.debug (fun m -> m "Unknown cookie attribute '%s', ignoring" attr_name)

     

       127
       127
       -
       

     

       128
       128
       -
       (** Validate cookie attributes and log warnings for invalid combinations *)

     

       129
       129
       -
       let validate_attributes attrs =

     

       130
       130
       -
         (* SameSite=None requires Secure flag *)

     

       131
       131
       -
         match attrs.same_site with

     

       132
       132
       -
         | Some `None when not attrs.secure ->

     

       133
       133
       -
             Log.warn (fun m ->

     

       134
       134
       -
                 m

     

       135
       135
       -
                   "Cookie has SameSite=None but Secure flag is not set; this violates \

     

       136
       136
       -
                    RFC requirements");

     

       137
       137
       -
             false

     

       138
       138
       -
         | _ -> true

     

       139
       139
       -
       

     

       140
       140
       -
       (** Build final cookie from name/value and accumulated attributes *)

     

       141
       141
       -
       let build_cookie ~request_domain ~request_path ~name ~value attrs ~now =

     

       142
       142
       -
         let domain = Option.value attrs.domain ~default:request_domain in

     

       143
       143
       -
         let path = Option.value attrs.path ~default:request_path in

     

       144
       144
       -
         make ~domain ~path ~name ~value ~secure:attrs.secure ~http_only:attrs.http_only

     

       145
       145
       -
           ?expires:attrs.expires ?same_site:attrs.same_site ~creation_time:now

     

       146
       146
       -
           ~last_access:now ()

     

       147
       147
       -
       

     

       148
       148
       -
       let rec parse_set_cookie ~clock ~domain:request_domain ~path:request_path

     

       149
       149
       -
           header_value =

     

       150
       150
       -
         Log.debug (fun m -> m "Parsing Set-Cookie: %s" header_value);

     

       151
       151
       -
       

     

       152
       152
       -
         (* Split into attributes *)

     

       153
       153
       -
         let parts = String.split_on_char ';' header_value |> List.map String.trim in

     

       154
       154
       -
       

     

       155
       155
       -
         match parts with

     

       156
       156
       -
         | [] -> None

     

       157
       157
       -
         | name_value :: attrs -> (

     

       158
       158
       -
             (* Parse name=value *)

     

       159
       159
       -
             match String.index_opt name_value '=' with

     

       160
       160
       -
             | None -> None

     

       161
       161
       -
             | Some eq_pos ->

     

       162
       162
       -
                 let name = String.sub name_value 0 eq_pos |> String.trim in

     

       163
       163
       -
                 let cookie_value =

     

       164
       164
       -
                   String.sub name_value (eq_pos + 1)

     

       165
       165
       -
                     (String.length name_value - eq_pos - 1)

     

       166
       166
       -
                   |> String.trim

     

       167
       167
       -
                 in

     

       168
       168
       -
       

     

       169
       169
       -
                 let now =

     

       170
       170
       -
                   Ptime.of_float_s (Eio.Time.now clock)

     

       171
       171
       -
                   |> Option.value ~default:Ptime.epoch

     

       172
       172
       -
                 in

     

       173
       173
       -
       

     

       174
       174
       -
                 (* Parse all attributes into mutable accumulator *)

     

       175
       175
       -
                 let accumulated_attrs = empty_attributes () in

     

       176
       176
       -
                 List.iter

     

       177
       177
       -
                   (fun attr ->

     

       178
       178
       -
                     match String.index_opt attr '=' with

     

       179
       179
       -
                     | None ->

     

       180
       180
       -
                         (* Attribute without value (e.g., Secure, HttpOnly) *)

     

       181
       181
       -
                         parse_attribute clock accumulated_attrs attr ""

     

       182
       182
       -
                     | Some eq ->

     

       183
       183
       -
                         let attr_name = String.sub attr 0 eq |> String.trim in

     

       184
       184
       -
                         let attr_value =

     

       185
       185
       -
                           String.sub attr (eq + 1) (String.length attr - eq - 1)

     

       186
       186
       -
                           |> String.trim

     

       187
       187
       -
                         in

     

       188
       188
       -
                         parse_attribute clock accumulated_attrs attr_name attr_value)

     

       189
       189
       -
                   attrs;

     

       190
       190
       -
       

     

       191
       191
       -
                 (* Validate attributes *)

     

       192
       192
       -
                 if not (validate_attributes accumulated_attrs) then (

     

       193
       193
       -
                   Log.warn (fun m -> m "Cookie validation failed, rejecting cookie");

     

       194
       194
       -
                   None)

     

       195
       195
       -
                 else

     

       196
       196
       -
                   let cookie =

     

       197
       197
       -
                     build_cookie ~request_domain ~request_path ~name ~value:cookie_value

     

       198
       198
       -
                       accumulated_attrs ~now

     

       199
       199
       -
                   in

     

       200
       200
       -
                   Log.debug (fun m -> m "Parsed cookie: %a" pp cookie);

     

       201
       201
       -
                   Some cookie)

     

       202
       202
       -
       

     

       203
       203
       -
       and make_cookie_header cookies =

     

       204
       204
       -
         cookies

     

       205
       205
       -
         |> List.map (fun c -> Printf.sprintf "%s=%s" (name c) (value c))

     

       206
       206
       -
         |> String.concat "; "

     

       207
       207
       -
       

     

       208
       208
       -
       (** {1 Pretty Printing} *)

     

       209
       209
       -
       

     

       210
       210
       -
       and pp_same_site ppf = function

     

       211
       211
       -
         | `Strict -> Format.pp_print_string ppf "Strict"

     

       212
       212
       -
         | `Lax -> Format.pp_print_string ppf "Lax"

     

       213
       213
       -
         | `None -> Format.pp_print_string ppf "None"

     

       214
       214
       -
       

     

       215
       215
       -
       and pp ppf cookie =

     

       216
       216
       -
         Format.fprintf ppf

     

       217
       217
       -
           "@[<hov 2>{ name=%S;@ value=%S;@ domain=%S;@ path=%S;@ secure=%b;@ \

     

       218
       218
       -
            http_only=%b;@ expires=%a;@ same_site=%a }@]"

     

       219
       219
       -
           (name cookie) (value cookie) (domain cookie) (path cookie) (secure cookie)

     

       220
       220
       -
           (http_only cookie)

     

       221
       221
       -
           (Format.pp_print_option Ptime.pp)

     

       222
       222
       -
           (expires cookie)

     

       223
       223
       -
           (Format.pp_print_option pp_same_site)

     

       224
       224
       -
           (same_site cookie)

     

       225
       225
       -
       

     

       226
       226
       -
       let pp_jar ppf jar =

     

       227
       227
       -
         Eio.Mutex.lock jar.mutex;

     

       228
       228
       -
         let cookies = jar.cookies in

     

       229
       229
       -
         Eio.Mutex.unlock jar.mutex;

     

       230
       230
       -
       

     

       231
       231
       -
         Format.fprintf ppf "@[<v>CookieJar with %d cookies:@," (List.length cookies);

     

       232
       232
       -
         List.iter (fun cookie -> Format.fprintf ppf "  %a@," pp cookie) cookies;

     

       233
       233
       -
         Format.fprintf ppf "@]"

     

       234
       234
       -
       

     

       235
       235
       -
       (** {1 Cookie Management} *)

     

       236
       236
       -
       

     

       237
       237
       -
       let add_cookie jar cookie =

     

       238
       238
       -
         Log.debug (fun m ->

     

       239
       239
       -
             m "Adding cookie: %s=%s for domain %s" (name cookie) (value cookie)

     

       240
       240
       -
               (domain cookie));

     

       241
       241
       -
       

     

       242
       242
       -
         Eio.Mutex.lock jar.mutex;

     

       243
       243
       -
         (* Remove existing cookie with same name, domain, and path *)

     

       244
       244
       -
         jar.cookies <-

     

       245
       245
       -
           List.filter

     

       246
       246
       -
             (fun c ->

     

       247
       247
       -
               not

     

       248
       248
       -
                 (name c = name cookie && domain c = domain cookie

     

       249
       249
       -
                && path c = path cookie))

     

       250
       250
       -
             jar.cookies;

     

       251
       251
       -
         jar.cookies <- cookie :: jar.cookies;

     

       252
       252
       -
         Eio.Mutex.unlock jar.mutex

     

       253
       253
       -
       

     

       254
       254
       -
       let get_cookies jar ~clock ~domain:request_domain ~path:request_path ~is_secure =

     

       255
       255
       -
         Log.debug (fun m ->

     

       256
       256
       -
             m "Getting cookies for domain=%s path=%s secure=%b" request_domain

     

       257
       257
       -
               request_path is_secure);

     

       258
       258
       -
       

     

       259
       259
       -
         Eio.Mutex.lock jar.mutex;

     

       260
       260
       -
         let applicable =

     

       261
       261
       -
           List.filter

     

       262
       262
       -
             (fun cookie ->

     

       263
       263
       -
               domain_matches (domain cookie) request_domain

     

       264
       264
       -
               && path_matches (path cookie) request_path

     

       265
       265
       -
               && ((not (secure cookie)) || is_secure))

     

       266
       266
       -
             jar.cookies

     

       267
       267
       -
         in

     

       268
       268
       -
       

     

       269
       269
       -
         (* Update last access time *)

     

       270
       270
       -
         let now =

     

       271
       271
       -
           Ptime.of_float_s (Eio.Time.now clock) |> Option.value ~default:Ptime.epoch

     

       272
       272
       -
         in

     

       273
       273
       -
         let updated =

     

       274
       274
       -
           List.map

     

       275
       275
       -
             (fun c ->

     

       276
       276
       -
               if List.memq c applicable then

     

       277
       277
       -
                 make ~domain:(domain c) ~path:(path c) ~name:(name c) ~value:(value c)

     

       278
       278
       -
                   ~secure:(secure c) ~http_only:(http_only c) ?expires:(expires c)

     

       279
       279
       -
                   ?same_site:(same_site c) ~creation_time:(creation_time c)

     

       280
       280
       -
                   ~last_access:now ()

     

       281
       281
       -
               else c)

     

       282
       282
       -
             jar.cookies

     

       283
       283
       -
         in

     

       284
       284
       -
         jar.cookies <- updated;

     

       285
       285
       -
         Eio.Mutex.unlock jar.mutex;

     

       286
       286
       -
       

     

       287
       287
       -
         Log.debug (fun m -> m "Found %d applicable cookies" (List.length applicable));

     

       288
       288
       -
         applicable

     

       289
       289
       -
       

     

       290
       290
       -
       let clear jar =

     

       291
       291
       -
         Log.info (fun m -> m "Clearing all cookies");

     

       292
       292
       -
         Eio.Mutex.lock jar.mutex;

     

       293
       293
       -
         jar.cookies <- [];

     

       294
       294
       -
         Eio.Mutex.unlock jar.mutex

     

       295
       295
       -
       

     

       296
       296
       -
       let clear_expired jar ~clock =

     

       297
       297
       -
         Eio.Mutex.lock jar.mutex;

     

       298
       298
       -
         let before_count = List.length jar.cookies in

     

       299
       299
       -
         jar.cookies <- List.filter (fun c -> not (is_expired c clock)) jar.cookies;

     

       300
       300
       -
         let removed = before_count - List.length jar.cookies in

     

       301
       301
       -
         Eio.Mutex.unlock jar.mutex;

     

       302
       302
       -
         Log.info (fun m -> m "Cleared %d expired cookies" removed)

     

       303
       303
       -
       

     

       304
       304
       -
       let clear_session_cookies jar =

     

       305
       305
       -
         Eio.Mutex.lock jar.mutex;

     

       306
       306
       -
         let before_count = List.length jar.cookies in

     

       307
       307
       -
         jar.cookies <- List.filter (fun c -> expires c <> None) jar.cookies;

     

       308
       308
       -
         let removed = before_count - List.length jar.cookies in

     

       309
       309
       -
         Eio.Mutex.unlock jar.mutex;

     

       310
       310
       -
         Log.info (fun m -> m "Cleared %d session cookies" removed)

     

       311
       311
       -
       

     

       312
       312
       -
       let count jar =

     

       313
       313
       -
         Eio.Mutex.lock jar.mutex;

     

       314
       314
       -
         let n = List.length jar.cookies in

     

       315
       315
       -
         Eio.Mutex.unlock jar.mutex;

     

       316
       316
       -
         n

     

       317
       317
       -
       

     

       318
       318
       -
       let get_all_cookies jar =

     

       319
       319
       -
         Eio.Mutex.lock jar.mutex;

     

       320
       320
       -
         let cookies = jar.cookies in

     

       321
       321
       -
         Eio.Mutex.unlock jar.mutex;

     

       322
       322
       -
         cookies

     

       323
       323
       -
       

     

       324
       324
       -
       let is_empty jar =

     

       325
       325
       -
         Eio.Mutex.lock jar.mutex;

     

       326
       326
       -
         let empty = jar.cookies = [] in

     

       327
       327
       -
         Eio.Mutex.unlock jar.mutex;

     

       328
       328
       -
         empty

     

       329
       329
       -
       

     

       330
       330
       -
       (** {1 Mozilla Format} *)

     

       331
       331
       -
       

     

       332
       332
       -
       let to_mozilla_format_internal jar =

     

       333
       333
       -
         let buffer = Buffer.create 1024 in

     

       334
       334
       -
         Buffer.add_string buffer "# Netscape HTTP Cookie File\n";

     

       335
       335
       -
         Buffer.add_string buffer "# This is a generated file!  Do not edit.\n\n";

     

       336
       336
       -
       

     

       337
       337
       -
         List.iter

     

       338
       338
       -
           (fun cookie ->

     

       339
       339
       -
             let include_subdomains =

     

       340
       340
       -
               if String.starts_with ~prefix:"." (domain cookie) then "TRUE" else "FALSE"

     

       341
       341
       -
             in

     

       342
       342
       -
             let secure_flag = if secure cookie then "TRUE" else "FALSE" in

     

       343
       343
       -
             let expires_str =

     

       344
       344
       -
               match expires cookie with

     

       345
       345
       -
               | None -> "0" (* Session cookie *)

     

       346
       346
       -
               | Some t ->

     

       347
       347
       -
                   let epoch = Ptime.to_float_s t |> int_of_float |> string_of_int in

     

       348
       348
       -
                   epoch

     

       349
       349
       -
             in

     

       350
       350
       -
       

     

       351
       351
       -
             Buffer.add_string buffer

     

       352
       352
       -
               (Printf.sprintf "%s\t%s\t%s\t%s\t%s\t%s\t%s\n" (domain cookie)

     

       353
       353
       -
                  include_subdomains (path cookie) secure_flag expires_str (name cookie)

     

       354
       354
       -
                  (value cookie)))

     

       355
       355
       -
           jar.cookies;

     

       356
       356
       -
       

     

       357
       357
       -
         Buffer.contents buffer

     

       358
       358
       -
       

     

       359
       359
       -
       let to_mozilla_format jar =

     

       360
       360
       -
         Eio.Mutex.lock jar.mutex;

     

       361
       361
       -
         let result = to_mozilla_format_internal jar in

     

       362
       362
       -
         Eio.Mutex.unlock jar.mutex;

     

       363
       363
       -
         result

     

       364
       364
       -
       

     

       365
       365
       -
       let from_mozilla_format ~clock content =

     

       366
       366
       -
         Log.debug (fun m -> m "Parsing Mozilla format cookies");

     

       367
       367
       -
         let jar = create () in

     

       368
       368
       -
       

     

       369
       369
       -
         let lines = String.split_on_char '\n' content in

     

       370
       370
       -
         List.iter

     

       371
       371
       -
           (fun line ->

     

       372
       372
       -
             let line = String.trim line in

     

       373
       373
       -
             if line <> "" && not (String.starts_with ~prefix:"#" line) then

     

       374
       374
       -
               match String.split_on_char '\t' line with

     

       375
       375
       -
               | [ domain; _include_subdomains; path; secure; expires; name; value ] ->

     

       376
       376
       -
                   let now =

     

       377
       377
       -
                     Ptime.of_float_s (Eio.Time.now clock)

     

       378
       378
       -
                     |> Option.value ~default:Ptime.epoch

     

       379
       379
       -
                   in

     

       380
       380
       -
                   let expires =

     

       381
       381
       -
                     let exp_int = try int_of_string expires with _ -> 0 in

     

       382
       382
       -
                     if exp_int = 0 then None else Ptime.of_float_s (float_of_int exp_int)

     

       383
       383
       -
                   in

     

       384
       384
       -
       

     

       385
       385
       -
                   let cookie =

     

       386
       386
       -
                     make ~domain ~path ~name ~value ~secure:(secure = "TRUE")

     

       387
       387
       -
                       ~http_only:false ?expires ?same_site:None ~creation_time:now

     

       388
       388
       -
                       ~last_access:now ()

     

       389
       389
       -
                   in

     

       390
       390
       -
                   add_cookie jar cookie;

     

       391
       391
       -
                   Log.debug (fun m -> m "Loaded cookie: %s=%s" name value)

     

       392
       392
       -
               | _ -> Log.warn (fun m -> m "Invalid cookie line: %s" line))

     

       393
       393
       -
           lines;

     

       394
       394
       -
       

     

       395
       395
       -
         Log.info (fun m -> m "Loaded %d cookies" (List.length jar.cookies));

     

       396
       396
       -
         jar

     

       397
       397
       -
       

     

       398
       398
       -
       (** {1 File Operations} *)

     

       399
       399
       -
       

     

       400
       400
       -
       let load ~clock path =

     

       401
       401
       -
         Log.info (fun m -> m "Loading cookies from %a" Eio.Path.pp path);

     

       402
       402
       -
       

     

       403
       403
       -
         try

     

       404
       404
       -
           let content = Eio.Path.load path in

     

       405
       405
       -
           from_mozilla_format ~clock content

     

       406
       406
       -
         with

     

       407
       407
       -
         | Eio.Io _ ->

     

       408
       408
       -
             Log.info (fun m -> m "Cookie file not found, creating empty jar");

     

       409
       409
       -
             create ()

     

       410
       410
       -
         | exn ->

     

       411
       411
       -
             Log.err (fun m -> m "Failed to load cookies: %s" (Printexc.to_string exn));

     

       412
       412
       -
             create ()

     

       413
       413
       -
       

     

       414
       414
       -
       let save path jar =

     

       415
       415
       -
         Log.info (fun m ->

     

       416
       416
       -
             m "Saving %d cookies to %a" (List.length jar.cookies) Eio.Path.pp path);

     

       417
       417
       -
       

     

       418
       418
       -
         let content = to_mozilla_format jar in

     

       419
       419
       -
       

     

       420
       420
       -
         try

     

       421
       421
       -
           Eio.Path.save ~create:(`Or_truncate 0o600) path content;

     

       422
       422
       -
           Log.debug (fun m -> m "Cookies saved successfully")

     

       423
       423
       -
         with exn ->

     

       424
       424
       -
           Log.err (fun m -> m "Failed to save cookies: %s" (Printexc.to_string exn))

-203

lib/cookeio.mli

···

       1
       1
       -
       (** Cookie management library for OCaml

     

       2
       2
       -
       

     

       3
       3
       -
           HTTP cookies are a mechanism that allows "server side

     

       4
       4
       -
           connections to store and retrieve information on the client side."

     

       5
       5
       -
           Originally designed to enable persistent client-side state for web

     

       6
       6
       -
           applications, cookies are essential for storing user preferences, session

     

       7
       7
       -
           data, shopping cart contents, and authentication tokens.

     

       8
       8
       -
       

     

       9
       9
       -
           This library provides a complete cookie jar implementation following

     

       10
       10
       -
           established web standards while integrating Eio for efficient asynchronous operations.

     

       11
       11
       -
       

     

       12
       12
       -
           {2 Cookie Format and Structure}

     

       13
       13
       -
       

     

       14
       14
       -
           Cookies are set via the Set-Cookie HTTP response header with the basic

     

       15
       15
       -
           format: [NAME=VALUE] with optional attributes including:

     

       16
       16
       -
           - [expires]: Optional cookie lifetime specification

     

       17
       17
       -
           - [domain]: Specifying valid domains using tail matching

     

       18
       18
       -
           - [path]: Defining URL subset for cookie validity

     

       19
       19
       -
           - [secure]: Transmission over secure channels only

     

       20
       20
       -
           - [httponly]: Not accessible to JavaScript

     

       21
       21
       -
           - [samesite]: Cross-site request behavior control

     

       22
       22
       -
       

     

       23
       23
       -
           {2 Domain and Path Matching}

     

       24
       24
       -
       

     

       25
       25
       -
           The library implements standard domain and path matching rules:

     

       26
       26
       -
           - Domain matching uses "tail matching" (e.g., "acme.com" matches

     

       27
       27
       -
             "anvil.acme.com")

     

       28
       28
       -
           - Path matching allows subset URL specification for fine-grained control

     

       29
       29
       -
           - More specific path mappings are sent first in Cookie headers

     

       30
       30
       -
       

     

       31
       31
       -
           *)

     

       32
       32
       -
       

     

       33
       33
       -
       type same_site = [ `Strict | `Lax | `None ]

     

       34
       34
       -
       (** Cookie same-site policy for controlling cross-site request behavior.

     

       35
       35
       -
       

     

       36
       36
       -
           - [`Strict]: Cookie only sent for same-site requests, providing maximum

     

       37
       37
       -
             protection

     

       38
       38
       -
           - [`Lax]: Cookie sent for same-site requests and top-level navigation

     

       39
       39
       -
             (default for modern browsers)

     

       40
       40
       -
           - [`None]: Cookie sent for all cross-site requests (requires [secure] flag)

     

       41
       41
       -
       *)

     

       42
       42
       -
       

     

       43
       43
       -
       type t

     

       44
       44
       -
       (** HTTP Cookie representation with all standard attributes.

     

       45
       45
       -
       

     

       46
       46
       -
           A cookie represents a name-value pair with associated metadata that controls

     

       47
       47
       -
           its scope, security, and lifetime. Cookies with the same [name], [domain],

     

       48
       48
       -
           and [path] will overwrite each other when added to a cookie jar. *)

     

       49
       49
       -
       

     

       50
       50
       -
       type jar

     

       51
       51
       -
       (** Cookie jar for storing and managing cookies.

     

       52
       52
       -
       

     

       53
       53
       -
           A cookie jar maintains a collection of cookies with automatic cleanup of

     

       54
       54
       -
           expired entries and enforcement of storage limits. It implements the

     

       55
       55
       -
           standard browser behavior for cookie storage, including:

     

       56
       56
       -
           - Automatic removal of expired cookies

     

       57
       57
       -
           - LRU eviction when storage limits are exceeded

     

       58
       58
       -
           - Domain and path-based cookie retrieval

     

       59
       59
       -
           - Mozilla format persistence for cross-tool compatibility *)

     

       60
       60
       -
       

     

       61
       61
       -
       (** {1 Cookie Accessors} *)

     

       62
       62
       -
       

     

       63
       63
       -
       val domain : t -> string

     

       64
       64
       -
       (** Get the domain of a cookie *)

     

       65
       65
       -
       

     

       66
       66
       -
       val path : t -> string

     

       67
       67
       -
       (** Get the path of a cookie *)

     

       68
       68
       -
       

     

       69
       69
       -
       val name : t -> string

     

       70
       70
       -
       (** Get the name of a cookie *)

     

       71
       71
       -
       

     

       72
       72
       -
       val value : t -> string

     

       73
       73
       -
       (** Get the value of a cookie *)

     

       74
       74
       -
       

     

       75
       75
       -
       val secure : t -> bool

     

       76
       76
       -
       (** Check if cookie is secure only *)

     

       77
       77
       -
       

     

       78
       78
       -
       val http_only : t -> bool

     

       79
       79
       -
       (** Check if cookie is HTTP only *)

     

       80
       80
       -
       

     

       81
       81
       -
       val expires : t -> Ptime.t option

     

       82
       82
       -
       (** Get the expiry time of a cookie *)

     

       83
       83
       -
       

     

       84
       84
       -
       val same_site : t -> same_site option

     

       85
       85
       -
       (** Get the same-site policy of a cookie *)

     

       86
       86
       -
       

     

       87
       87
       -
       val creation_time : t -> Ptime.t

     

       88
       88
       -
       (** Get the creation time of a cookie *)

     

       89
       89
       -
       

     

       90
       90
       -
       val last_access : t -> Ptime.t

     

       91
       91
       -
       (** Get the last access time of a cookie *)

     

       92
       92
       -
       

     

       93
       93
       -
       val make : domain:string -> path:string -> name:string -> value:string ->

     

       94
       94
       -
         ?secure:bool -> ?http_only:bool -> ?expires:Ptime.t ->

     

       95
       95
       -
         ?same_site:same_site -> creation_time:Ptime.t -> last_access:Ptime.t ->

     

       96
       96
       -
         unit -> t

     

       97
       97
       -
       (** Create a new cookie with the given attributes *)

     

       98
       98
       -
       

     

       99
       99
       -
       (** {1 Cookie Jar Creation and Loading} *)

     

       100
       100
       -
       

     

       101
       101
       -
       val create : unit -> jar

     

       102
       102
       -
       (** Create an empty cookie jar *)

     

       103
       103
       -
       

     

       104
       104
       -
       val load : clock:_ Eio.Time.clock -> Eio.Fs.dir_ty Eio.Path.t -> jar

     

       105
       105
       -
       (** Load cookies from Mozilla format file.

     

       106
       106
       -
       

     

       107
       107
       -
           Loads cookies from a file in Mozilla format, using the provided clock to set

     

       108
       108
       -
           creation and last access times. Returns an empty jar if the file doesn't

     

       109
       109
       -
           exist or cannot be loaded. *)

     

       110
       110
       -
       

     

       111
       111
       -
       val save : Eio.Fs.dir_ty Eio.Path.t -> jar -> unit

     

       112
       112
       -
       (** Save cookies to Mozilla format file *)

     

       113
       113
       -
       

     

       114
       114
       -
       (** {1 Cookie Jar Management} *)

     

       115
       115
       -
       

     

       116
       116
       -
       val add_cookie : jar -> t -> unit

     

       117
       117
       -
       (** Add a cookie to the jar *)

     

       118
       118
       -
       

     

       119
       119
       -
       val get_cookies :

     

       120
       120
       -
         jar ->

     

       121
       121
       -
         clock:_ Eio.Time.clock ->

     

       122
       122
       -
         domain:string ->

     

       123
       123
       -
         path:string ->

     

       124
       124
       -
         is_secure:bool ->

     

       125
       125
       -
         t list

     

       126
       126
       -
       (** Get cookies applicable for a URL.

     

       127
       127
       -
       

     

       128
       128
       -
           Returns all cookies that match the given domain and path, and satisfy the

     

       129
       129
       -
           secure flag requirement. Also updates the last access time of matching

     

       130
       130
       -
           cookies using the provided clock. *)

     

       131
       131
       -
       

     

       132
       132
       -
       val clear : jar -> unit

     

       133
       133
       -
       (** Clear all cookies *)

     

       134
       134
       -
       

     

       135
       135
       -
       val clear_expired : jar -> clock:_ Eio.Time.clock -> unit

     

       136
       136
       -
       (** Clear expired cookies *)

     

       137
       137
       -
       

     

       138
       138
       -
       val clear_session_cookies : jar -> unit

     

       139
       139
       -
       (** Clear session cookies (those without expiry) *)

     

       140
       140
       -
       

     

       141
       141
       -
       val count : jar -> int

     

       142
       142
       -
       (** Get the number of cookies in the jar *)

     

       143
       143
       -
       

     

       144
       144
       -
       val get_all_cookies : jar -> t list

     

       145
       145
       -
       (** Get all cookies in the jar *)

     

       146
       146
       -
       

     

       147
       147
       -
       val is_empty : jar -> bool

     

       148
       148
       -
       (** Check if the jar is empty *)

     

       149
       149
       -
       

     

       150
       150
       -
       (** {1 Cookie Creation and Parsing} *)

     

       151
       151
       -
       

     

       152
       152
       -
       val parse_set_cookie :

     

       153
       153
       -
         clock:_ Eio.Time.clock -> domain:string -> path:string -> string -> t option

     

       154
       154
       -
       (** Parse Set-Cookie header value into a cookie.

     

       155
       155
       -
       

     

       156
       156
       -
           Parses a Set-Cookie header value following RFC specifications:

     

       157
       157
       -
           - Basic format: [NAME=VALUE; attribute1; attribute2=value2]

     

       158
       158
       -
           - Supports all standard attributes: [expires], [max-age], [domain], [path],

     

       159
       159
       -
             [secure], [httponly], [samesite]

     

       160
       160
       -
           - Returns [None] if parsing fails or cookie validation fails

     

       161
       161
       -
           - The [domain] and [path] parameters provide the request context for default

     

       162
       162
       -
             values

     

       163
       163
       -
           - The [clock] parameter is used for calculating expiry times from [max-age]

     

       164
       164
       -
             attributes

     

       165
       165
       -
       

     

       166
       166
       -
           Cookie validation rules:

     

       167
       167
       -
           - [SameSite=None] requires the [Secure] flag to be set

     

       168
       168
       -
       

     

       169
       169
       -
           Example:

     

       170
       170
       -
           [parse_set_cookie ~clock ~domain:"example.com" ~path:"/"

     

       171
       171
       -
            "session=abc123; Secure; HttpOnly"] *)

     

       172
       172
       -
       

     

       173
       173
       -
       val make_cookie_header : t list -> string

     

       174
       174
       -
       (** Create cookie header value from cookies.

     

       175
       175
       -
       

     

       176
       176
       -
           Formats a list of cookies into a Cookie header value suitable for HTTP

     

       177
       177
       -
           requests.

     

       178
       178
       -
           - Format: [name1=value1; name2=value2; name3=value3]

     

       179
       179
       -
           - Only includes cookie names and values, not attributes

     

       180
       180
       -
           - Cookies should already be filtered for the target domain/path

     

       181
       181
       -
           - More specific path mappings should be ordered first in the input list

     

       182
       182
       -
       

     

       183
       183
       -
           Example: [make_cookie_header cookies] might return

     

       184
       184
       -
           ["session=abc123; theme=dark"] *)

     

       185
       185
       -
       

     

       186
       186
       -
       (** {1 Pretty Printing} *)

     

       187
       187
       -
       

     

       188
       188
       -
       val pp : Format.formatter -> t -> unit

     

       189
       189
       -
       (** Pretty print a cookie *)

     

       190
       190
       -
       

     

       191
       191
       -
       val pp_jar : Format.formatter -> jar -> unit

     

       192
       192
       -
       (** Pretty print a cookie jar *)

     

       193
       193
       -
       

     

       194
       194
       -
       (** {1 Mozilla Format} *)

     

       195
       195
       -
       

     

       196
       196
       -
       val to_mozilla_format : jar -> string

     

       197
       197
       -
       (** Write cookies in Mozilla format *)

     

       198
       198
       -
       

     

       199
       199
       -
       val from_mozilla_format : clock:_ Eio.Time.clock -> string -> jar

     

       200
       200
       -
       (** Parse Mozilla format cookies.

     

       201
       201
       -
       

     

       202
       202
       -
           Creates a cookie jar from a string in Mozilla cookie format, using the

     

       203
       203
       -
           provided clock to set creation and last access times. *)

+926

lib/core/cookeio.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
         Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.

     

       3
       3
       +
         SPDX-License-Identifier: ISC

     

       4
       4
       +
        ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       let src = Logs.Src.create "cookeio" ~doc:"Cookie management"

     

       7
       7
       +
       

     

       8
       8
       +
       module Log = (val Logs.src_log src : Logs.LOG)

     

       9
       9
       +
       

     

       10
       10
       +
       (** SameSite attribute for cross-site request control.

     

       11
       11
       +
       

     

       12
       12
       +
           The SameSite attribute is defined in the RFC 6265bis draft and controls

     

       13
       13
       +
           whether cookies are sent with cross-site requests.

     

       14
       14
       +
       

     

       15
       15
       +
           @see <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis#section-5.4.7> RFC 6265bis Section 5.4.7 - The SameSite Attribute *)

     

       16
       16
       +
       module SameSite = struct

     

       17
       17
       +
         type t = [ `Strict | `Lax | `None ]

     

       18
       18
       +
       

     

       19
       19
       +
         let equal = ( = )

     

       20
       20
       +
       

     

       21
       21
       +
         let pp ppf = function

     

       22
       22
       +
           | `Strict -> Format.pp_print_string ppf "Strict"

     

       23
       23
       +
           | `Lax -> Format.pp_print_string ppf "Lax"

     

       24
       24
       +
           | `None -> Format.pp_print_string ppf "None"

     

       25
       25
       +
       end

     

       26
       26
       +
       

     

       27
       27
       +
       (** Cookie expiration type.

     

       28
       28
       +
       

     

       29
       29
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3},

     

       30
       30
       +
           cookies have either a persistent expiry time or are session cookies that

     

       31
       31
       +
           expire when the user agent session ends.

     

       32
       32
       +
       

     

       33
       33
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       34
       34
       +
       module Expiration = struct

     

       35
       35
       +
         type t = [ `Session | `DateTime of Ptime.t ]

     

       36
       36
       +
       

     

       37
       37
       +
         let equal e1 e2 =

     

       38
       38
       +
           match (e1, e2) with

     

       39
       39
       +
           | `Session, `Session -> true

     

       40
       40
       +
           | `DateTime t1, `DateTime t2 -> Ptime.equal t1 t2

     

       41
       41
       +
           | _ -> false

     

       42
       42
       +
       

     

       43
       43
       +
         let pp ppf = function

     

       44
       44
       +
           | `Session -> Format.pp_print_string ppf "Session"

     

       45
       45
       +
           | `DateTime t -> Format.fprintf ppf "DateTime(%a)" Ptime.pp t

     

       46
       46
       +
       end

     

       47
       47
       +
       

     

       48
       48
       +
       type t = {

     

       49
       49
       +
         domain : string;

     

       50
       50
       +
         path : string;

     

       51
       51
       +
         name : string;

     

       52
       52
       +
         value : string;

     

       53
       53
       +
         secure : bool;

     

       54
       54
       +
         http_only : bool;

     

       55
       55
       +
         partitioned : bool;

     

       56
       56
       +
         host_only : bool;

     

       57
       57
       +
         expires : Expiration.t option;

     

       58
       58
       +
         max_age : Ptime.Span.t option;

     

       59
       59
       +
         same_site : SameSite.t option;

     

       60
       60
       +
         creation_time : Ptime.t;

     

       61
       61
       +
         last_access : Ptime.t;

     

       62
       62
       +
       }

     

       63
       63
       +
       (** HTTP Cookie *)

     

       64
       64
       +
       

     

       65
       65
       +
       (** {1 Cookie Accessors} *)

     

       66
       66
       +
       

     

       67
       67
       +
       let domain cookie = cookie.domain

     

       68
       68
       +
       let path cookie = cookie.path

     

       69
       69
       +
       let name cookie = cookie.name

     

       70
       70
       +
       let value cookie = cookie.value

     

       71
       71
       +
       

     

       72
       72
       +
       let value_trimmed cookie =

     

       73
       73
       +
         let v = cookie.value in

     

       74
       74
       +
         let len = String.length v in

     

       75
       75
       +
         if len < 2 then v

     

       76
       76
       +
         else

     

       77
       77
       +
           match (v.[0], v.[len - 1]) with

     

       78
       78
       +
           | '"', '"' -> String.sub v 1 (len - 2)

     

       79
       79
       +
           | _ -> v

     

       80
       80
       +
       

     

       81
       81
       +
       let secure cookie = cookie.secure

     

       82
       82
       +
       let http_only cookie = cookie.http_only

     

       83
       83
       +
       let partitioned cookie = cookie.partitioned

     

       84
       84
       +
       let host_only cookie = cookie.host_only

     

       85
       85
       +
       let expires cookie = cookie.expires

     

       86
       86
       +
       let max_age cookie = cookie.max_age

     

       87
       87
       +
       let same_site cookie = cookie.same_site

     

       88
       88
       +
       let creation_time cookie = cookie.creation_time

     

       89
       89
       +
       let last_access cookie = cookie.last_access

     

       90
       90
       +
       

     

       91
       91
       +
       let make ~domain ~path ~name ~value ?(secure = false) ?(http_only = false)

     

       92
       92
       +
           ?expires ?max_age ?same_site ?(partitioned = false) ?(host_only = false)

     

       93
       93
       +
           ~creation_time ~last_access () =

     

       94
       94
       +
         {

     

       95
       95
       +
           domain;

     

       96
       96
       +
           path;

     

       97
       97
       +
           name;

     

       98
       98
       +
           value;

     

       99
       99
       +
           secure;

     

       100
       100
       +
           http_only;

     

       101
       101
       +
           partitioned;

     

       102
       102
       +
           host_only;

     

       103
       103
       +
           expires;

     

       104
       104
       +
           max_age;

     

       105
       105
       +
           same_site;

     

       106
       106
       +
           creation_time;

     

       107
       107
       +
           last_access;

     

       108
       108
       +
         }

     

       109
       109
       +
       

     

       110
       110
       +
       (** {1 RFC 6265 Validation}

     

       111
       111
       +
       

     

       112
       112
       +
           Validation functions for cookie names, values, and attributes per

     

       113
       113
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1} RFC 6265 Section 4.1.1}.

     

       114
       114
       +
       

     

       115
       115
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 - Syntax *)

     

       116
       116
       +
       module Validate = struct

     

       117
       117
       +
         (** Check if a character is a valid RFC 2616 token character.

     

       118
       118
       +
       

     

       119
       119
       +
             Per RFC 6265, cookie-name must be a token as defined in RFC 2616 Section 2.2:

     

       120
       120
       +
             token = 1*<any CHAR except CTLs or separators>

     

       121
       121
       +
             separators = "(" | ")" | "<" | ">" | "@" | "," | ";" | ":" | "\" |

     

       122
       122
       +
                          <"> | "/" | "[" | "]" | "?" | "=" | "{" | "}" | SP | HT

     

       123
       123
       +
       

     

       124
       124
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)

     

       125
       125
       +
         let is_token_char = function

     

       126
       126
       +
           | '\x00' .. '\x1F' | '\x7F' -> false (* CTL characters *)

     

       127
       127
       +
           | '(' | ')' | '<' | '>' | '@' | ',' | ';' | ':' | '\\' | '"' | '/' | '['

     

       128
       128
       +
           | ']' | '?' | '=' | '{' | '}' | ' ' ->

     

       129
       129
       +
               false (* separators - note: HT (0x09) is already covered by CTL range *)

     

       130
       130
       +
           | _ -> true

     

       131
       131
       +
       

     

       132
       132
       +
         (** Validate a cookie name per RFC 6265.

     

       133
       133
       +
       

     

       134
       134
       +
             Cookie names must be valid RFC 2616 tokens: one or more characters

     

       135
       135
       +
             excluding control characters and separators.

     

       136
       136
       +
       

     

       137
       137
       +
             @param name The cookie name to validate

     

       138
       138
       +
             @return [Ok name] if valid, [Error message] with explanation if invalid

     

       139
       139
       +
       

     

       140
       140
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)

     

       141
       141
       +
         let cookie_name name =

     

       142
       142
       +
           let len = String.length name in

     

       143
       143
       +
           if len = 0 then

     

       144
       144
       +
             Error "Cookie name is empty; RFC 6265 requires at least one character"

     

       145
       145
       +
           else

     

       146
       146
       +
             let rec find_invalid i acc =

     

       147
       147
       +
               if i >= len then acc

     

       148
       148
       +
               else

     

       149
       149
       +
                 let c = String.unsafe_get name i in

     

       150
       150
       +
                 if is_token_char c then find_invalid (i + 1) acc

     

       151
       151
       +
                 else find_invalid (i + 1) (c :: acc)

     

       152
       152
       +
             in

     

       153
       153
       +
             match find_invalid 0 [] with

     

       154
       154
       +
             | [] -> Ok name

     

       155
       155
       +
             | invalid_chars ->

     

       156
       156
       +
                 let chars_str =

     

       157
       157
       +
                   invalid_chars

     

       158
       158
       +
                   |> List.rev

     

       159
       159
       +
                   |> List.map (fun c -> Printf.sprintf "%C" c)

     

       160
       160
       +
                   |> String.concat ", "

     

       161
       161
       +
                 in

     

       162
       162
       +
                 Error

     

       163
       163
       +
                   (Printf.sprintf

     

       164
       164
       +
                      "Cookie name %S contains invalid characters: %s. RFC 6265 requires \

     

       165
       165
       +
                       cookie names to be valid tokens (no control characters, spaces, \

     

       166
       166
       +
                       or separators like ()[]{}=,;:@\\\"/?<>)"

     

       167
       167
       +
                      name chars_str)

     

       168
       168
       +
       

     

       169
       169
       +
         (** Check if a character is a valid cookie-octet.

     

       170
       170
       +
       

     

       171
       171
       +
             Per RFC 6265 Section 4.1.1:

     

       172
       172
       +
             cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E

     

       173
       173
       +
             (US-ASCII excluding CTLs, whitespace, DQUOTE, comma, semicolon, backslash)

     

       174
       174
       +
       

     

       175
       175
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)

     

       176
       176
       +
         let is_cookie_octet = function

     

       177
       177
       +
           | '\x21' -> true (* ! *)

     

       178
       178
       +
           | '\x23' .. '\x2B' -> true (* # $ % & ' ( ) * + *)

     

       179
       179
       +
           | '\x2D' .. '\x3A' -> true (* - . / 0-9 : *)

     

       180
       180
       +
           | '\x3C' .. '\x5B' -> true (* < = > ? @ A-Z [ *)

     

       181
       181
       +
           | '\x5D' .. '\x7E' -> true (* ] ^ _ ` a-z { | } ~ *)

     

       182
       182
       +
           | _ -> false

     

       183
       183
       +
       

     

       184
       184
       +
         (** Validate a cookie value per RFC 6265.

     

       185
       185
       +
       

     

       186
       186
       +
             Cookie values must contain only cookie-octets, optionally wrapped in

     

       187
       187
       +
             double quotes. Invalid characters include: control characters, space,

     

       188
       188
       +
             double quote (except as wrapper), comma, semicolon, and backslash.

     

       189
       189
       +
       

     

       190
       190
       +
             @param value The cookie value to validate

     

       191
       191
       +
             @return [Ok value] if valid, [Error message] with explanation if invalid

     

       192
       192
       +
       

     

       193
       193
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)

     

       194
       194
       +
         let cookie_value value =

     

       195
       195
       +
           (* Handle optional DQUOTE wrapper *)

     

       196
       196
       +
           let len = String.length value in

     

       197
       197
       +
           let inner_value, inner_len =

     

       198
       198
       +
             if len >= 2 && value.[0] = '"' && value.[len - 1] = '"' then

     

       199
       199
       +
               (String.sub value 1 (len - 2), len - 2)

     

       200
       200
       +
             else (value, len)

     

       201
       201
       +
           in

     

       202
       202
       +
           let rec find_invalid i acc =

     

       203
       203
       +
             if i >= inner_len then acc

     

       204
       204
       +
             else

     

       205
       205
       +
               let c = String.unsafe_get inner_value i in

     

       206
       206
       +
               if is_cookie_octet c then find_invalid (i + 1) acc

     

       207
       207
       +
               else find_invalid (i + 1) (c :: acc)

     

       208
       208
       +
           in

     

       209
       209
       +
           match find_invalid 0 [] with

     

       210
       210
       +
           | [] -> Ok value

     

       211
       211
       +
           | invalid_chars ->

     

       212
       212
       +
               let chars_str =

     

       213
       213
       +
                 invalid_chars

     

       214
       214
       +
                 |> List.rev

     

       215
       215
       +
                 |> List.map (fun c ->

     

       216
       216
       +
                        match c with

     

       217
       217
       +
                        | ' ' -> "space (0x20)"

     

       218
       218
       +
                        | '"' -> "double-quote (0x22)"

     

       219
       219
       +
                        | ',' -> "comma (0x2C)"

     

       220
       220
       +
                        | ';' -> "semicolon (0x3B)"

     

       221
       221
       +
                        | '\\' -> "backslash (0x5C)"

     

       222
       222
       +
                        | c when Char.code c < 0x20 ->

     

       223
       223
       +
                            Printf.sprintf "control char (0x%02X)" (Char.code c)

     

       224
       224
       +
                        | c -> Printf.sprintf "%C (0x%02X)" c (Char.code c))

     

       225
       225
       +
                 |> String.concat ", "

     

       226
       226
       +
               in

     

       227
       227
       +
               Error

     

       228
       228
       +
                 (Printf.sprintf

     

       229
       229
       +
                    "Cookie value %S contains invalid characters: %s. RFC 6265 cookie \

     

       230
       230
       +
                     values may only contain printable ASCII excluding space, \

     

       231
       231
       +
                     double-quote, comma, semicolon, and backslash"

     

       232
       232
       +
                    value chars_str)

     

       233
       233
       +
       

     

       234
       234
       +
         (** Validate a domain attribute value.

     

       235
       235
       +
       

     

       236
       236
       +
             Domain values must be either:

     

       237
       237
       +
             - A valid domain name per RFC 1034 Section 3.5

     

       238
       238
       +
             - A valid IPv4 address

     

       239
       239
       +
             - A valid IPv6 address

     

       240
       240
       +
       

     

       241
       241
       +
             @param domain The domain value to validate (leading dot is stripped first)

     

       242
       242
       +
             @return [Ok domain] if valid, [Error message] with explanation if invalid

     

       243
       243
       +
       

     

       244
       244
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.3> RFC 6265 Section 4.1.2.3

     

       245
       245
       +
             @see <https://datatracker.ietf.org/doc/html/rfc1034#section-3.5> RFC 1034 Section 3.5 *)

     

       246
       246
       +
         let domain_value domain =

     

       247
       247
       +
           (* Strip leading dot per RFC 6265 Section 5.2.3 *)

     

       248
       248
       +
           let domain =

     

       249
       249
       +
             if String.starts_with ~prefix:"." domain && String.length domain > 1 then

     

       250
       250
       +
               String.sub domain 1 (String.length domain - 1)

     

       251
       251
       +
             else domain

     

       252
       252
       +
           in

     

       253
       253
       +
           if String.length domain = 0 then

     

       254
       254
       +
             Error "Domain attribute is empty"

     

       255
       255
       +
           else

     

       256
       256
       +
             (* First check if it's an IP address *)

     

       257
       257
       +
             match Ipaddr.of_string domain with

     

       258
       258
       +
             | Ok _ -> Ok domain (* Valid IP address *)

     

       259
       259
       +
             | Error _ -> (

     

       260
       260
       +
                 (* Not an IP, validate as domain name using domain-name library *)

     

       261
       261
       +
                 match Domain_name.of_string domain with

     

       262
       262
       +
                 | Ok _ -> Ok domain

     

       263
       263
       +
                 | Error (`Msg msg) ->

     

       264
       264
       +
                     Error

     

       265
       265
       +
                       (Printf.sprintf

     

       266
       266
       +
                          "Domain %S is not a valid domain name: %s. Domain names \

     

       267
       267
       +
                           must follow RFC 1034: labels must start with a letter, \

     

       268
       268
       +
                           contain only letters/digits/hyphens, not end with a \

     

       269
       269
       +
                           hyphen, and be at most 63 characters each"

     

       270
       270
       +
                          domain msg))

     

       271
       271
       +
       

     

       272
       272
       +
         (** Validate a path attribute value.

     

       273
       273
       +
       

     

       274
       274
       +
             Per RFC 6265 Section 4.1.1, path-value may contain any CHAR except

     

       275
       275
       +
             control characters and semicolon.

     

       276
       276
       +
       

     

       277
       277
       +
             @param path The path value to validate

     

       278
       278
       +
             @return [Ok path] if valid, [Error message] with explanation if invalid

     

       279
       279
       +
       

     

       280
       280
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)

     

       281
       281
       +
         let path_value path =

     

       282
       282
       +
           let len = String.length path in

     

       283
       283
       +
           let rec find_invalid i acc =

     

       284
       284
       +
             if i >= len then acc

     

       285
       285
       +
             else

     

       286
       286
       +
               let c = String.unsafe_get path i in

     

       287
       287
       +
               match c with

     

       288
       288
       +
               | '\x00' .. '\x1F' | '\x7F' | ';' -> find_invalid (i + 1) (c :: acc)

     

       289
       289
       +
               | _ -> find_invalid (i + 1) acc

     

       290
       290
       +
           in

     

       291
       291
       +
           match find_invalid 0 [] with

     

       292
       292
       +
           | [] -> Ok path

     

       293
       293
       +
           | invalid_chars ->

     

       294
       294
       +
               let chars_str =

     

       295
       295
       +
                 invalid_chars

     

       296
       296
       +
                 |> List.rev

     

       297
       297
       +
                 |> List.map (fun c -> Printf.sprintf "0x%02X" (Char.code c))

     

       298
       298
       +
                 |> String.concat ", "

     

       299
       299
       +
               in

     

       300
       300
       +
               Error

     

       301
       301
       +
                 (Printf.sprintf

     

       302
       302
       +
                    "Path %S contains invalid characters: %s. Paths may not contain \

     

       303
       303
       +
                     control characters or semicolons"

     

       304
       304
       +
                    path chars_str)

     

       305
       305
       +
       

     

       306
       306
       +
         (** Validate a Max-Age attribute value.

     

       307
       307
       +
       

     

       308
       308
       +
             Per RFC 6265 Section 4.1.1, max-age-av uses non-zero-digit *DIGIT.

     

       309
       309
       +
             However, per Section 5.2.2, user agents should treat values <= 0 as

     

       310
       310
       +
             "delete immediately". This function returns [Ok] for any integer since

     

       311
       311
       +
             the parsing code handles negative values by converting to 0.

     

       312
       312
       +
       

     

       313
       313
       +
             @param seconds The Max-Age value in seconds

     

       314
       314
       +
             @return [Ok seconds] always (negative values are handled in parsing)

     

       315
       315
       +
       

     

       316
       316
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1

     

       317
       317
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2> RFC 6265 Section 5.2.2 *)

     

       318
       318
       +
         let max_age seconds = Ok seconds

     

       319
       319
       +
       end

     

       320
       320
       +
       

     

       321
       321
       +
       (** {1 Public Suffix Validation}

     

       322
       322
       +
       

     

       323
       323
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3 Step 5},

     

       324
       324
       +
           cookies with Domain attributes that are public suffixes must be rejected

     

       325
       325
       +
           to prevent domain-wide cookie attacks.

     

       326
       326
       +
       

     

       327
       327
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model

     

       328
       328
       +
           @see <https://publicsuffix.org/list/> Public Suffix List *)

     

       329
       329
       +
       

     

       330
       330
       +
       (** Module-level Public Suffix List instance.

     

       331
       331
       +
       

     

       332
       332
       +
           Lazily initialized on first use. The PSL data is compiled into the

     

       333
       333
       +
           publicsuffix library at build time from the Mozilla Public Suffix List. *)

     

       334
       334
       +
       let psl = lazy (Publicsuffix.create ())

     

       335
       335
       +
       

     

       336
       336
       +
       (** Validate that a cookie domain is not a public suffix.

     

       337
       337
       +
       

     

       338
       338
       +
           Per RFC 6265 Section 5.3 Step 5, user agents MUST reject cookies where

     

       339
       339
       +
           the Domain attribute is a public suffix (e.g., ".com", ".co.uk") unless

     

       340
       340
       +
           the request host exactly matches that domain.

     

       341
       341
       +
       

     

       342
       342
       +
           This prevents attackers from setting domain-wide cookies that would affect

     

       343
       343
       +
           all sites under a TLD.

     

       344
       344
       +
       

     

       345
       345
       +
           @param request_domain The host from the HTTP request

     

       346
       346
       +
           @param cookie_domain The Domain attribute value (already normalized, without leading dot)

     

       347
       347
       +
           @return [Ok ()] if the domain is allowed, [Error msg] if it's a public suffix

     

       348
       348
       +
       

     

       349
       349
       +
           Examples:

     

       350
       350
       +
           - Request from "www.example.com", Domain=".com" → Error (public suffix)

     

       351
       351
       +
           - Request from "www.example.com", Domain=".example.com" → Ok (not public suffix)

     

       352
       352
       +
           - Request from "com", Domain=".com" → Ok (request host matches domain exactly)

     

       353
       353
       +
       

     

       354
       354
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 *)

     

       355
       355
       +
       let validate_not_public_suffix ~request_domain ~cookie_domain =

     

       356
       356
       +
         (* IP addresses bypass PSL check per RFC 6265 Section 5.1.3 *)

     

       357
       357
       +
         match Ipaddr.of_string cookie_domain with

     

       358
       358
       +
         | Ok _ -> Ok () (* IP addresses are not subject to PSL rules *)

     

       359
       359
       +
         | Error _ -> (

     

       360
       360
       +
             let psl = Lazy.force psl in

     

       361
       361
       +
             match Publicsuffix.is_public_suffix psl cookie_domain with

     

       362
       362
       +
             | Error _ | Ok false ->

     

       363
       363
       +
                 (* If PSL lookup fails (e.g., invalid domain) or not a public suffix,

     

       364
       364
       +
                    allow the cookie. Domain name validation is handled separately. *)

     

       365
       365
       +
                 Ok ()

     

       366
       366
       +
             | Ok true ->

     

       367
       367
       +
                 (* It's a public suffix - only allow if request host matches exactly.

     

       368
       368
       +
                    This allows a server that IS a public suffix (rare but possible with

     

       369
       369
       +
                    private domains like blogspot.com) to set cookies for itself. *)

     

       370
       370
       +
                 let request_lower = String.lowercase_ascii request_domain in

     

       371
       371
       +
                 let cookie_lower = String.lowercase_ascii cookie_domain in

     

       372
       372
       +
                 if request_lower = cookie_lower then Ok ()

     

       373
       373
       +
                 else

     

       374
       374
       +
                   Error

     

       375
       375
       +
                     (Printf.sprintf

     

       376
       376
       +
                        "Domain %S is a public suffix; RFC 6265 Section 5.3 prohibits \

     

       377
       377
       +
                         setting cookies for public suffixes to prevent domain-wide \

     

       378
       378
       +
                         cookie attacks. The request host %S does not exactly match \

     

       379
       379
       +
                         the domain."

     

       380
       380
       +
                        cookie_domain request_domain))

     

       381
       381
       +
       

     

       382
       382
       +
       (** {1 Cookie Parsing Helpers} *)

     

       383
       383
       +
       

     

       384
       384
       +
       (** Normalize a domain by stripping the leading dot.

     

       385
       385
       +
       

     

       386
       386
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3} RFC 6265 Section 5.2.3},

     

       387
       387
       +
           if the first character of the Domain attribute value is ".", that character

     

       388
       388
       +
           is ignored (the domain remains case-insensitive).

     

       389
       389
       +
       

     

       390
       390
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3> RFC 6265 Section 5.2.3 - The Domain Attribute *)

     

       391
       391
       +
       let normalize_domain domain =

     

       392
       392
       +
         match String.starts_with ~prefix:"." domain with

     

       393
       393
       +
         | true when String.length domain > 1 ->

     

       394
       394
       +
             String.sub domain 1 (String.length domain - 1)

     

       395
       395
       +
         | _ -> domain

     

       396
       396
       +
       

     

       397
       397
       +
       (** {1 HTTP Date Parsing}

     

       398
       398
       +
       

     

       399
       399
       +
           Date parsing follows {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.1} RFC 6265 Section 5.1.1}

     

       400
       400
       +
           which requires parsing dates in various HTTP formats. *)

     

       401
       401
       +
       

     

       402
       402
       +
       module DateParser = struct

     

       403
       403
       +
         (** Month name to number mapping (case-insensitive).

     

       404
       404
       +
       

     

       405
       405
       +
             Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.1} RFC 6265 Section 5.1.1},

     

       406
       406
       +
             month tokens are matched case-insensitively.

     

       407
       407
       +
       

     

       408
       408
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.1> RFC 6265 Section 5.1.1 - Dates *)

     

       409
       409
       +
         let month_of_string s =

     

       410
       410
       +
           match String.lowercase_ascii s with

     

       411
       411
       +
           | "jan" -> Some 1

     

       412
       412
       +
           | "feb" -> Some 2

     

       413
       413
       +
           | "mar" -> Some 3

     

       414
       414
       +
           | "apr" -> Some 4

     

       415
       415
       +
           | "may" -> Some 5

     

       416
       416
       +
           | "jun" -> Some 6

     

       417
       417
       +
           | "jul" -> Some 7

     

       418
       418
       +
           | "aug" -> Some 8

     

       419
       419
       +
           | "sep" -> Some 9

     

       420
       420
       +
           | "oct" -> Some 10

     

       421
       421
       +
           | "nov" -> Some 11

     

       422
       422
       +
           | "dec" -> Some 12

     

       423
       423
       +
           | _ -> None

     

       424
       424
       +
       

     

       425
       425
       +
         (** Normalize abbreviated years per RFC 6265.

     

       426
       426
       +
       

     

       427
       427
       +
             Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.1} RFC 6265 Section 5.1.1}:

     

       428
       428
       +
             - Years 70-99 get 1900 added (e.g., 95 → 1995)

     

       429
       429
       +
             - Years 0-69 get 2000 added (e.g., 25 → 2025)

     

       430
       430
       +
             - Years >= 100 are returned as-is

     

       431
       431
       +
       

     

       432
       432
       +
             Note: This implementation treats year 69 as 1969 (adding 1900), which

     

       433
       433
       +
             technically differs from the RFC's "70 and less than or equal to 99" rule.

     

       434
       434
       +
       

     

       435
       435
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.1> RFC 6265 Section 5.1.1 - Dates *)

     

       436
       436
       +
         let normalize_year year =

     

       437
       437
       +
           if year >= 0 && year <= 68 then year + 2000

     

       438
       438
       +
           else if year >= 69 && year <= 99 then year + 1900

     

       439
       439
       +
           else year

     

       440
       440
       +
       

     

       441
       441
       +
         (** Parse FMT1: "Wed, 21 Oct 2015 07:28:00 GMT" (RFC 1123) *)

     

       442
       442
       +
         let parse_fmt1 s =

     

       443
       443
       +
           try

     

       444
       444
       +
             Scanf.sscanf s "%s %d %s %d %d:%d:%d %s"

     

       445
       445
       +
               (fun _wday day mon year hour min sec tz ->

     

       446
       446
       +
                 (* Check timezone is GMT (case-insensitive) *)

     

       447
       447
       +
                 if String.lowercase_ascii tz <> "gmt" then None

     

       448
       448
       +
                 else

     

       449
       449
       +
                   match month_of_string mon with

     

       450
       450
       +
                   | None -> None

     

       451
       451
       +
                   | Some month ->

     

       452
       452
       +
                       let year = normalize_year year in

     

       453
       453
       +
                       Ptime.of_date_time ((year, month, day), ((hour, min, sec), 0)))

     

       454
       454
       +
           with _ -> None

     

       455
       455
       +
       

     

       456
       456
       +
         (** Parse FMT2: "Wednesday, 21-Oct-15 07:28:00 GMT" (RFC 850) *)

     

       457
       457
       +
         let parse_fmt2 s =

     

       458
       458
       +
           try

     

       459
       459
       +
             Scanf.sscanf s "%[^,], %d-%3s-%d %d:%d:%d %s"

     

       460
       460
       +
               (fun _wday day mon year hour min sec tz ->

     

       461
       461
       +
                 (* Check timezone is GMT (case-insensitive) *)

     

       462
       462
       +
                 if String.lowercase_ascii tz <> "gmt" then None

     

       463
       463
       +
                 else

     

       464
       464
       +
                   match month_of_string mon with

     

       465
       465
       +
                   | None -> None

     

       466
       466
       +
                   | Some month ->

     

       467
       467
       +
                       let year = normalize_year year in

     

       468
       468
       +
                       Ptime.of_date_time ((year, month, day), ((hour, min, sec), 0)))

     

       469
       469
       +
           with _ -> None

     

       470
       470
       +
       

     

       471
       471
       +
         (** Parse FMT3: "Wed Oct 21 07:28:00 2015" (asctime) *)

     

       472
       472
       +
         let parse_fmt3 s =

     

       473
       473
       +
           try

     

       474
       474
       +
             Scanf.sscanf s "%s %s %d %d:%d:%d %d"

     

       475
       475
       +
               (fun _wday mon day hour min sec year ->

     

       476
       476
       +
                 match month_of_string mon with

     

       477
       477
       +
                 | None -> None

     

       478
       478
       +
                 | Some month ->

     

       479
       479
       +
                     let year = normalize_year year in

     

       480
       480
       +
                     Ptime.of_date_time ((year, month, day), ((hour, min, sec), 0)))

     

       481
       481
       +
           with _ -> None

     

       482
       482
       +
       

     

       483
       483
       +
         (** Parse FMT4: "Wed, 21-Oct-2015 07:28:00 GMT" (variant) *)

     

       484
       484
       +
         let parse_fmt4 s =

     

       485
       485
       +
           try

     

       486
       486
       +
             Scanf.sscanf s "%s %d-%3s-%d %d:%d:%d %s"

     

       487
       487
       +
               (fun _wday day mon year hour min sec tz ->

     

       488
       488
       +
                 (* Check timezone is GMT (case-insensitive) *)

     

       489
       489
       +
                 if String.lowercase_ascii tz <> "gmt" then None

     

       490
       490
       +
                 else

     

       491
       491
       +
                   match month_of_string mon with

     

       492
       492
       +
                   | None -> None

     

       493
       493
       +
                   | Some month ->

     

       494
       494
       +
                       let year = normalize_year year in

     

       495
       495
       +
                       Ptime.of_date_time ((year, month, day), ((hour, min, sec), 0)))

     

       496
       496
       +
           with _ -> None

     

       497
       497
       +
       

     

       498
       498
       +
         (** Parse HTTP date by trying all supported formats in sequence *)

     

       499
       499
       +
         let parse_http_date s =

     

       500
       500
       +
           let ( <|> ) a b = match a with Some _ -> a | None -> b () in

     

       501
       501
       +
           parse_fmt1 s <|> fun () ->

     

       502
       502
       +
           parse_fmt2 s <|> fun () ->

     

       503
       503
       +
           parse_fmt3 s <|> fun () ->

     

       504
       504
       +
           parse_fmt4 s

     

       505
       505
       +
       end

     

       506
       506
       +
       

     

       507
       507
       +
       (** {1 Cookie Parsing} *)

     

       508
       508
       +
       

     

       509
       509
       +
       type cookie_attributes = {

     

       510
       510
       +
         mutable domain : string option;

     

       511
       511
       +
         mutable path : string option;

     

       512
       512
       +
         mutable secure : bool;

     

       513
       513
       +
         mutable http_only : bool;

     

       514
       514
       +
         mutable partitioned : bool;

     

       515
       515
       +
         mutable expires : Expiration.t option;

     

       516
       516
       +
         mutable max_age : Ptime.Span.t option;

     

       517
       517
       +
         mutable same_site : SameSite.t option;

     

       518
       518
       +
       }

     

       519
       519
       +
       (** Accumulated attributes from parsing Set-Cookie header *)

     

       520
       520
       +
       

     

       521
       521
       +
       (** Create empty attribute accumulator *)

     

       522
       522
       +
       let empty_attributes () =

     

       523
       523
       +
         {

     

       524
       524
       +
           domain = None;

     

       525
       525
       +
           path = None;

     

       526
       526
       +
           secure = false;

     

       527
       527
       +
           http_only = false;

     

       528
       528
       +
           partitioned = false;

     

       529
       529
       +
           expires = None;

     

       530
       530
       +
           max_age = None;

     

       531
       531
       +
           same_site = None;

     

       532
       532
       +
         }

     

       533
       533
       +
       

     

       534
       534
       +
       (** Parse a single cookie attribute and update the accumulator in-place.

     

       535
       535
       +
       

     

       536
       536
       +
           Attribute parsing follows {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2} RFC 6265 Section 5.2}

     

       537
       537
       +
           which defines the grammar and semantics for each cookie attribute.

     

       538
       538
       +
       

     

       539
       539
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2> RFC 6265 Section 5.2 - The Set-Cookie Header *)

     

       540
       540
       +
       let parse_attribute now attrs attr_name attr_value =

     

       541
       541
       +
         let attr_lower = String.lowercase_ascii attr_name in

     

       542
       542
       +
         match attr_lower with

     

       543
       543
       +
         | "domain" -> attrs.domain <- Some (normalize_domain attr_value)

     

       544
       544
       +
         | "path" -> attrs.path <- Some attr_value

     

       545
       545
       +
         | "expires" -> (

     

       546
       546
       +
             if

     

       547
       547
       +
               (* Special case: Expires=0 means session cookie *)

     

       548
       548
       +
               attr_value = "0"

     

       549
       549
       +
             then attrs.expires <- Some `Session

     

       550
       550
       +
             else

     

       551
       551
       +
               match Ptime.of_rfc3339 attr_value with

     

       552
       552
       +
               | Ok (time, _, _) -> attrs.expires <- Some (`DateTime time)

     

       553
       553
       +
               | Error (`RFC3339 (_, err)) -> (

     

       554
       554
       +
                   (* Try HTTP date format as fallback *)

     

       555
       555
       +
                   match DateParser.parse_http_date attr_value with

     

       556
       556
       +
                   | Some time -> attrs.expires <- Some (`DateTime time)

     

       557
       557
       +
                   | None ->

     

       558
       558
       +
                       Log.warn (fun m ->

     

       559
       559
       +
                           m "Failed to parse expires attribute '%s': %a" attr_value

     

       560
       560
       +
                             Ptime.pp_rfc3339_error err)))

     

       561
       561
       +
         | "max-age" -> (

     

       562
       562
       +
             match int_of_string_opt attr_value with

     

       563
       563
       +
             | Some seconds ->

     

       564
       564
       +
                 (* Handle negative values as 0 per RFC 6265 *)

     

       565
       565
       +
                 let seconds = max 0 seconds in

     

       566
       566
       +
                 let current_time = now () in

     

       567
       567
       +
                 (* Store the max-age as a Ptime.Span *)

     

       568
       568
       +
                 attrs.max_age <- Some (Ptime.Span.of_int_s seconds);

     

       569
       569
       +
                 (* Also compute and store expires as DateTime *)

     

       570
       570
       +
                 let expires =

     

       571
       571
       +
                   Ptime.add_span current_time (Ptime.Span.of_int_s seconds)

     

       572
       572
       +
                 in

     

       573
       573
       +
                 (match expires with

     

       574
       574
       +
                 | Some time -> attrs.expires <- Some (`DateTime time)

     

       575
       575
       +
                 | None -> ());

     

       576
       576
       +
                 Log.debug (fun m -> m "Parsed Max-Age: %d seconds" seconds)

     

       577
       577
       +
             | None ->

     

       578
       578
       +
                 Log.warn (fun m ->

     

       579
       579
       +
                     m "Failed to parse max-age attribute '%s'" attr_value))

     

       580
       580
       +
         | "secure" -> attrs.secure <- true

     

       581
       581
       +
         | "httponly" -> attrs.http_only <- true

     

       582
       582
       +
         | "partitioned" -> attrs.partitioned <- true

     

       583
       583
       +
         | "samesite" -> (

     

       584
       584
       +
             match String.lowercase_ascii attr_value with

     

       585
       585
       +
             | "strict" -> attrs.same_site <- Some `Strict

     

       586
       586
       +
             | "lax" -> attrs.same_site <- Some `Lax

     

       587
       587
       +
             | "none" -> attrs.same_site <- Some `None

     

       588
       588
       +
             | _ ->

     

       589
       589
       +
                 Log.warn (fun m ->

     

       590
       590
       +
                     m "Invalid samesite value '%s', ignoring" attr_value))

     

       591
       591
       +
         | _ ->

     

       592
       592
       +
             Log.debug (fun m -> m "Unknown cookie attribute '%s', ignoring" attr_name)

     

       593
       593
       +
       

     

       594
       594
       +
       (** Validate cookie attributes and log warnings for invalid combinations.

     

       595
       595
       +
       

     

       596
       596
       +
           Validates:

     

       597
       597
       +
           - SameSite=None requires the Secure flag (per RFC 6265bis)

     

       598
       598
       +
           - Partitioned requires the Secure flag (per CHIPS specification)

     

       599
       599
       +
       

     

       600
       600
       +
           @see <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis#section-5.4.7> RFC 6265bis Section 5.4.7 - SameSite

     

       601
       601
       +
           @see <https://developer.chrome.com/docs/privacy-sandbox/chips/> CHIPS - Cookies Having Independent Partitioned State *)

     

       602
       602
       +
       let validate_attributes attrs =

     

       603
       603
       +
         match (attrs.same_site, attrs.secure, attrs.partitioned) with

     

       604
       604
       +
         | Some `None, false, _ ->

     

       605
       605
       +
             Log.warn (fun m ->

     

       606
       606
       +
                 m

     

       607
       607
       +
                   "Cookie has SameSite=None but Secure flag is not set; this \

     

       608
       608
       +
                    violates RFC requirements");

     

       609
       609
       +
             false

     

       610
       610
       +
         | _, false, true ->

     

       611
       611
       +
             Log.warn (fun m ->

     

       612
       612
       +
                 m

     

       613
       613
       +
                   "Cookie has Partitioned attribute but Secure flag is not set; this \

     

       614
       614
       +
                    violates CHIPS requirements");

     

       615
       615
       +
             false

     

       616
       616
       +
         | _ -> true

     

       617
       617
       +
       

     

       618
       618
       +
       (** Build final cookie from name/value and accumulated attributes.

     

       619
       619
       +
       

     

       620
       620
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3}:

     

       621
       621
       +
           - If Domain attribute is present, host-only-flag = false, domain = attribute value

     

       622
       622
       +
           - If Domain attribute is absent, host-only-flag = true, domain = request host

     

       623
       623
       +
       

     

       624
       624
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       625
       625
       +
       let build_cookie ~request_domain ~request_path ~name ~value attrs ~now =

     

       626
       626
       +
         let host_only, domain =

     

       627
       627
       +
           match attrs.domain with

     

       628
       628
       +
           | Some d -> (false, normalize_domain d)

     

       629
       629
       +
           | None -> (true, request_domain)

     

       630
       630
       +
         in

     

       631
       631
       +
         let path = Option.value attrs.path ~default:request_path in

     

       632
       632
       +
         make ~domain ~path ~name ~value ~secure:attrs.secure

     

       633
       633
       +
           ~http_only:attrs.http_only ?expires:attrs.expires ?max_age:attrs.max_age

     

       634
       634
       +
           ?same_site:attrs.same_site ~partitioned:attrs.partitioned ~host_only

     

       635
       635
       +
           ~creation_time:now ~last_access:now ()

     

       636
       636
       +
       

     

       637
       637
       +
       (** {1 Pretty Printing} *)

     

       638
       638
       +
       

     

       639
       639
       +
       let pp ppf cookie =

     

       640
       640
       +
         Format.fprintf ppf

     

       641
       641
       +
           "@[<hov 2>{ name=%S;@ value=%S;@ domain=%S;@ path=%S;@ secure=%b;@ \

     

       642
       642
       +
            http_only=%b;@ partitioned=%b;@ host_only=%b;@ expires=%a;@ max_age=%a;@ \

     

       643
       643
       +
            same_site=%a }@]"

     

       644
       644
       +
           (name cookie) (value cookie) (domain cookie) (path cookie) (secure cookie)

     

       645
       645
       +
           (http_only cookie) (partitioned cookie) (host_only cookie)

     

       646
       646
       +
           (Format.pp_print_option Expiration.pp)

     

       647
       647
       +
           (expires cookie)

     

       648
       648
       +
           (Format.pp_print_option Ptime.Span.pp)

     

       649
       649
       +
           (max_age cookie)

     

       650
       650
       +
           (Format.pp_print_option SameSite.pp)

     

       651
       651
       +
           (same_site cookie)

     

       652
       652
       +
       

     

       653
       653
       +
       (** {1 Cookie Parsing} *)

     

       654
       654
       +
       

     

       655
       655
       +
       (** Parse a Set-Cookie HTTP response header.

     

       656
       656
       +
       

     

       657
       657
       +
           Parses the header according to {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2} RFC 6265 Section 5.2},

     

       658
       658
       +
           extracting the cookie name, value, and all attributes. Returns [Error msg] if

     

       659
       659
       +
           the cookie is invalid or fails validation, with a descriptive error message.

     

       660
       660
       +
       

     

       661
       661
       +
           @param now Function returning current time for Max-Age computation

     

       662
       662
       +
           @param domain The request host (used as default domain)

     

       663
       663
       +
           @param path The request path (used as default path)

     

       664
       664
       +
           @param header_value The Set-Cookie header value string

     

       665
       665
       +
           @return [Ok cookie] if parsing succeeds, [Error msg] with explanation if invalid

     

       666
       666
       +
       

     

       667
       667
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2> RFC 6265 Section 5.2 - The Set-Cookie Header *)

     

       668
       668
       +
       let of_set_cookie_header ~now ~domain:request_domain ~path:request_path

     

       669
       669
       +
           header_value =

     

       670
       670
       +
         Log.debug (fun m -> m "Parsing Set-Cookie: %s" header_value);

     

       671
       671
       +
       

     

       672
       672
       +
         (* Split into attributes *)

     

       673
       673
       +
         let parts = String.split_on_char ';' header_value |> List.map String.trim in

     

       674
       674
       +
       

     

       675
       675
       +
         match parts with

     

       676
       676
       +
         | [] -> Error "Empty Set-Cookie header"

     

       677
       677
       +
         | name_value :: attrs -> (

     

       678
       678
       +
             (* Parse name=value *)

     

       679
       679
       +
             match String.index_opt name_value '=' with

     

       680
       680
       +
             | None ->

     

       681
       681
       +
                 Error

     

       682
       682
       +
                   (Printf.sprintf

     

       683
       683
       +
                      "Set-Cookie header missing '=' separator in name-value pair: %S"

     

       684
       684
       +
                      name_value)

     

       685
       685
       +
             | Some eq_pos -> (

     

       686
       686
       +
                 let name = String.sub name_value 0 eq_pos |> String.trim in

     

       687
       687
       +
                 let cookie_value =

     

       688
       688
       +
                   String.sub name_value (eq_pos + 1)

     

       689
       689
       +
                     (String.length name_value - eq_pos - 1)

     

       690
       690
       +
                   |> String.trim

     

       691
       691
       +
                 in

     

       692
       692
       +
       

     

       693
       693
       +
                 (* Validate cookie name per RFC 6265 *)

     

       694
       694
       +
                 match Validate.cookie_name name with

     

       695
       695
       +
                 | Error msg -> Error msg

     

       696
       696
       +
                 | Ok name -> (

     

       697
       697
       +
                     (* Validate cookie value per RFC 6265 *)

     

       698
       698
       +
                     match Validate.cookie_value cookie_value with

     

       699
       699
       +
                     | Error msg -> Error msg

     

       700
       700
       +
                     | Ok cookie_value ->

     

       701
       701
       +
                         let current_time = now () in

     

       702
       702
       +
       

     

       703
       703
       +
                         (* Parse all attributes into mutable accumulator *)

     

       704
       704
       +
                         let accumulated_attrs = empty_attributes () in

     

       705
       705
       +
                         let attr_errors = ref [] in

     

       706
       706
       +
                         List.iter

     

       707
       707
       +
                           (fun attr ->

     

       708
       708
       +
                             match String.index_opt attr '=' with

     

       709
       709
       +
                             | None ->

     

       710
       710
       +
                                 (* Attribute without value (e.g., Secure, HttpOnly) *)

     

       711
       711
       +
                                 parse_attribute now accumulated_attrs attr ""

     

       712
       712
       +
                             | Some eq ->

     

       713
       713
       +
                                 let attr_name = String.sub attr 0 eq |> String.trim in

     

       714
       714
       +
                                 let attr_value =

     

       715
       715
       +
                                   String.sub attr (eq + 1)

     

       716
       716
       +
                                     (String.length attr - eq - 1)

     

       717
       717
       +
                                   |> String.trim

     

       718
       718
       +
                                 in

     

       719
       719
       +
                                 (* Validate domain and path attributes *)

     

       720
       720
       +
                                 (match String.lowercase_ascii attr_name with

     

       721
       721
       +
                                 | "domain" -> (

     

       722
       722
       +
                                     match Validate.domain_value attr_value with

     

       723
       723
       +
                                     | Error msg -> attr_errors := msg :: !attr_errors

     

       724
       724
       +
                                     | Ok _ -> ())

     

       725
       725
       +
                                 | "path" -> (

     

       726
       726
       +
                                     match Validate.path_value attr_value with

     

       727
       727
       +
                                     | Error msg -> attr_errors := msg :: !attr_errors

     

       728
       728
       +
                                     | Ok _ -> ())

     

       729
       729
       +
                                 | "max-age" -> (

     

       730
       730
       +
                                     match int_of_string_opt attr_value with

     

       731
       731
       +
                                     | Some seconds -> (

     

       732
       732
       +
                                         match Validate.max_age seconds with

     

       733
       733
       +
                                         | Error msg ->

     

       734
       734
       +
                                             attr_errors := msg :: !attr_errors

     

       735
       735
       +
                                         | Ok _ -> ())

     

       736
       736
       +
                                     | None -> ())

     

       737
       737
       +
                                 | _ -> ());

     

       738
       738
       +
                                 parse_attribute now accumulated_attrs attr_name

     

       739
       739
       +
                                   attr_value)

     

       740
       740
       +
                           attrs;

     

       741
       741
       +
       

     

       742
       742
       +
                         (* Check for attribute validation errors *)

     

       743
       743
       +
                         if List.length !attr_errors > 0 then

     

       744
       744
       +
                           Error (String.concat "; " (List.rev !attr_errors))

     

       745
       745
       +
                         else if not (validate_attributes accumulated_attrs) then

     

       746
       746
       +
                           Error

     

       747
       747
       +
                             "Cookie validation failed: SameSite=None requires \

     

       748
       748
       +
                              Secure flag, and Partitioned requires Secure flag"

     

       749
       749
       +
                         else

     

       750
       750
       +
                           (* Public suffix validation per RFC 6265 Section 5.3 Step 5.

     

       751
       751
       +
                              Only applies when Domain attribute is present. *)

     

       752
       752
       +
                           let psl_result =

     

       753
       753
       +
                             match accumulated_attrs.domain with

     

       754
       754
       +
                             | None ->

     

       755
       755
       +
                                 (* No Domain attribute - cookie is host-only, no PSL check needed *)

     

       756
       756
       +
                                 Ok ()

     

       757
       757
       +
                             | Some cookie_domain ->

     

       758
       758
       +
                                 let normalized = normalize_domain cookie_domain in

     

       759
       759
       +
                                 validate_not_public_suffix ~request_domain ~cookie_domain:normalized

     

       760
       760
       +
                           in

     

       761
       761
       +
                           (match psl_result with

     

       762
       762
       +
                           | Error msg -> Error msg

     

       763
       763
       +
                           | Ok () ->

     

       764
       764
       +
                               let cookie =

     

       765
       765
       +
                                 build_cookie ~request_domain ~request_path ~name

     

       766
       766
       +
                                   ~value:cookie_value accumulated_attrs ~now:current_time

     

       767
       767
       +
                               in

     

       768
       768
       +
                               Log.debug (fun m -> m "Parsed cookie: %a" pp cookie);

     

       769
       769
       +
                               Ok cookie))))

     

       770
       770
       +
       

     

       771
       771
       +
       (** Parse a Cookie HTTP request header.

     

       772
       772
       +
       

     

       773
       773
       +
           Parses the header according to {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.2} RFC 6265 Section 4.2}.

     

       774
       774
       +
           The Cookie header contains semicolon-separated name=value pairs.

     

       775
       775
       +
       

     

       776
       776
       +
           Validates cookie names and values per RFC 6265 and detects duplicate

     

       777
       777
       +
           cookie names (which is an error per Section 4.2.1).

     

       778
       778
       +
       

     

       779
       779
       +
           Cookies parsed from the Cookie header have [host_only = true] since we

     

       780
       780
       +
           cannot determine from the header alone whether they originally had a

     

       781
       781
       +
           Domain attribute.

     

       782
       782
       +
       

     

       783
       783
       +
           @param now Function returning current time for timestamps

     

       784
       784
       +
           @param domain The request host (assigned to all parsed cookies)

     

       785
       785
       +
           @param path The request path (assigned to all parsed cookies)

     

       786
       786
       +
           @param header_value The Cookie header value string

     

       787
       787
       +
           @return [Ok cookies] if all cookies parse successfully with no duplicates,

     

       788
       788
       +
                   [Error msg] with explanation if validation fails

     

       789
       789
       +
       

     

       790
       790
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.2> RFC 6265 Section 4.2 - The Cookie Header *)

     

       791
       791
       +
       let of_cookie_header ~now ~domain ~path header_value =

     

       792
       792
       +
         Log.debug (fun m -> m "Parsing Cookie header: %s" header_value);

     

       793
       793
       +
       

     

       794
       794
       +
         (* Split on semicolons *)

     

       795
       795
       +
         let parts = String.split_on_char ';' header_value |> List.map String.trim in

     

       796
       796
       +
       

     

       797
       797
       +
         (* Filter out empty parts *)

     

       798
       798
       +
         let parts = List.filter (fun s -> String.length s > 0) parts in

     

       799
       799
       +
       

     

       800
       800
       +
         (* Parse each name=value pair, collecting results *)

     

       801
       801
       +
         let results =

     

       802
       802
       +
           List.fold_left

     

       803
       803
       +
             (fun acc name_value ->

     

       804
       804
       +
               match acc with

     

       805
       805
       +
               | Error _ -> acc (* Propagate earlier errors *)

     

       806
       806
       +
               | Ok (cookies, seen_names) -> (

     

       807
       807
       +
                   match String.index_opt name_value '=' with

     

       808
       808
       +
                   | None ->

     

       809
       809
       +
                       Error

     

       810
       810
       +
                         (Printf.sprintf "Cookie missing '=' separator: %S" name_value)

     

       811
       811
       +
                   | Some eq_pos -> (

     

       812
       812
       +
                       let cookie_name =

     

       813
       813
       +
                         String.sub name_value 0 eq_pos |> String.trim

     

       814
       814
       +
                       in

     

       815
       815
       +
                       (* Validate cookie name per RFC 6265 *)

     

       816
       816
       +
                       match Validate.cookie_name cookie_name with

     

       817
       817
       +
                       | Error msg -> Error msg

     

       818
       818
       +
                       | Ok cookie_name -> (

     

       819
       819
       +
                           (* Check for duplicate names per RFC 6265 Section 4.2.1 *)

     

       820
       820
       +
                           if List.mem cookie_name seen_names then

     

       821
       821
       +
                             Error

     

       822
       822
       +
                               (Printf.sprintf

     

       823
       823
       +
                                  "Duplicate cookie name %S in Cookie header; RFC \

     

       824
       824
       +
                                   6265 Section 4.2.1 forbids duplicate names"

     

       825
       825
       +
                                  cookie_name)

     

       826
       826
       +
                           else

     

       827
       827
       +
                             let cookie_value =

     

       828
       828
       +
                               String.sub name_value (eq_pos + 1)

     

       829
       829
       +
                                 (String.length name_value - eq_pos - 1)

     

       830
       830
       +
                               |> String.trim

     

       831
       831
       +
                             in

     

       832
       832
       +
                             (* Validate cookie value per RFC 6265 *)

     

       833
       833
       +
                             match Validate.cookie_value cookie_value with

     

       834
       834
       +
                             | Error msg -> Error msg

     

       835
       835
       +
                             | Ok cookie_value ->

     

       836
       836
       +
                                 let current_time = now () in

     

       837
       837
       +
                                 (* Create cookie with defaults from Cookie header context.

     

       838
       838
       +
                                    Cookies from Cookie headers have host_only=true since we don't

     

       839
       839
       +
                                    know if they originally had a Domain attribute. *)

     

       840
       840
       +
                                 let cookie =

     

       841
       841
       +
                                   make ~domain ~path ~name:cookie_name

     

       842
       842
       +
                                     ~value:cookie_value ~secure:false ~http_only:false

     

       843
       843
       +
                                     ~partitioned:false ~host_only:true

     

       844
       844
       +
                                     ~creation_time:current_time

     

       845
       845
       +
                                     ~last_access:current_time ()

     

       846
       846
       +
                                 in

     

       847
       847
       +
                                 Ok (cookie :: cookies, cookie_name :: seen_names)))))

     

       848
       848
       +
             (Ok ([], []))

     

       849
       849
       +
             parts

     

       850
       850
       +
         in

     

       851
       851
       +
         match results with

     

       852
       852
       +
         | Error msg -> Error msg

     

       853
       853
       +
         | Ok (cookies, _) -> Ok (List.rev cookies)

     

       854
       854
       +
       

     

       855
       855
       +
       (** Generate a Cookie HTTP request header from a list of cookies.

     

       856
       856
       +
       

     

       857
       857
       +
           Formats cookies according to {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.2} RFC 6265 Section 4.2}

     

       858
       858
       +
           as semicolon-separated name=value pairs.

     

       859
       859
       +
       

     

       860
       860
       +
           @param cookies List of cookies to include

     

       861
       861
       +
           @return The Cookie header value string

     

       862
       862
       +
       

     

       863
       863
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.2> RFC 6265 Section 4.2 - The Cookie Header *)

     

       864
       864
       +
       let make_cookie_header cookies =

     

       865
       865
       +
         cookies

     

       866
       866
       +
         |> List.map (fun c -> Printf.sprintf "%s=%s" (name c) (value c))

     

       867
       867
       +
         |> String.concat "; "

     

       868
       868
       +
       

     

       869
       869
       +
       (** Generate a Set-Cookie HTTP response header from a cookie.

     

       870
       870
       +
       

     

       871
       871
       +
           Formats the cookie according to {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1} RFC 6265 Section 4.1}

     

       872
       872
       +
           including all attributes.

     

       873
       873
       +
       

     

       874
       874
       +
           Note: The Expires attribute is currently formatted using RFC 3339, which

     

       875
       875
       +
           differs from the RFC-recommended rfc1123-date format.

     

       876
       876
       +
       

     

       877
       877
       +
           @param cookie The cookie to serialize

     

       878
       878
       +
           @return The Set-Cookie header value string

     

       879
       879
       +
       

     

       880
       880
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1> RFC 6265 Section 4.1 - The Set-Cookie Header *)

     

       881
       881
       +
       let make_set_cookie_header cookie =

     

       882
       882
       +
         let buffer = Buffer.create 128 in

     

       883
       883
       +
         Buffer.add_string buffer (Printf.sprintf "%s=%s" (name cookie) (value cookie));

     

       884
       884
       +
       

     

       885
       885
       +
         (* Add Max-Age if present *)

     

       886
       886
       +
         Option.iter

     

       887
       887
       +
           (fun span ->

     

       888
       888
       +
             Option.iter

     

       889
       889
       +
               (fun seconds ->

     

       890
       890
       +
                 Buffer.add_string buffer (Printf.sprintf "; Max-Age=%d" seconds))

     

       891
       891
       +
               (Ptime.Span.to_int_s span))

     

       892
       892
       +
           (max_age cookie);

     

       893
       893
       +
       

     

       894
       894
       +
         (* Add Expires if present *)

     

       895
       895
       +
         Option.iter

     

       896
       896
       +
           (function

     

       897
       897
       +
             | `Session -> Buffer.add_string buffer "; Expires=0"

     

       898
       898
       +
             | `DateTime exp_time ->

     

       899
       899
       +
                 let exp_str = Ptime.to_rfc3339 ~tz_offset_s:0 exp_time in

     

       900
       900
       +
                 Buffer.add_string buffer (Printf.sprintf "; Expires=%s" exp_str))

     

       901
       901
       +
           (expires cookie);

     

       902
       902
       +
       

     

       903
       903
       +
         (* Add Domain *)

     

       904
       904
       +
         Buffer.add_string buffer (Printf.sprintf "; Domain=%s" (domain cookie));

     

       905
       905
       +
       

     

       906
       906
       +
         (* Add Path *)

     

       907
       907
       +
         Buffer.add_string buffer (Printf.sprintf "; Path=%s" (path cookie));

     

       908
       908
       +
       

     

       909
       909
       +
         (* Add Secure flag *)

     

       910
       910
       +
         if secure cookie then Buffer.add_string buffer "; Secure";

     

       911
       911
       +
       

     

       912
       912
       +
         (* Add HttpOnly flag *)

     

       913
       913
       +
         if http_only cookie then Buffer.add_string buffer "; HttpOnly";

     

       914
       914
       +
       

     

       915
       915
       +
         (* Add Partitioned flag *)

     

       916
       916
       +
         if partitioned cookie then Buffer.add_string buffer "; Partitioned";

     

       917
       917
       +
       

     

       918
       918
       +
         (* Add SameSite *)

     

       919
       919
       +
         Option.iter

     

       920
       920
       +
           (function

     

       921
       921
       +
             | `Strict -> Buffer.add_string buffer "; SameSite=Strict"

     

       922
       922
       +
             | `Lax -> Buffer.add_string buffer "; SameSite=Lax"

     

       923
       923
       +
             | `None -> Buffer.add_string buffer "; SameSite=None")

     

       924
       924
       +
           (same_site cookie);

     

       925
       925
       +
       

     

       926
       926
       +
         Buffer.contents buffer

+533

lib/core/cookeio.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
         Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.

     

       3
       3
       +
         SPDX-License-Identifier: ISC

     

       4
       4
       +
        ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Cookie management library for OCaml

     

       7
       7
       +
       

     

       8
       8
       +
           HTTP cookies are a mechanism defined in

     

       9
       9
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265} RFC 6265} that allows

     

       10
       10
       +
           "server side connections to store and retrieve information on the client

     

       11
       11
       +
           side." Originally designed to enable persistent client-side state for web

     

       12
       12
       +
           applications, cookies are essential for storing user preferences, session

     

       13
       13
       +
           data, shopping cart contents, and authentication tokens.

     

       14
       14
       +
       

     

       15
       15
       +
           This library provides a complete cookie implementation following RFC 6265

     

       16
       16
       +
           while integrating Eio for efficient asynchronous operations.

     

       17
       17
       +
       

     

       18
       18
       +
           {2 Cookie Format and Structure}

     

       19
       19
       +
       

     

       20
       20
       +
           Cookies are set via the Set-Cookie HTTP response header

     

       21
       21
       +
           ({{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1} Section 4.1})

     

       22
       22
       +
           with the basic format: [NAME=VALUE] with optional attributes including:

     

       23
       23
       +
           - [expires]: Cookie lifetime specification

     

       24
       24
       +
             ({{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.1} Section 5.2.1})

     

       25
       25
       +
           - [max-age]: Cookie lifetime in seconds

     

       26
       26
       +
             ({{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2} Section 5.2.2})

     

       27
       27
       +
           - [domain]: Valid domains using tail matching

     

       28
       28
       +
             ({{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3} Section 5.2.3})

     

       29
       29
       +
           - [path]: URL subset for cookie validity

     

       30
       30
       +
             ({{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4} Section 5.2.4})

     

       31
       31
       +
           - [secure]: Transmission over secure channels only

     

       32
       32
       +
             ({{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.5} Section 5.2.5})

     

       33
       33
       +
           - [httponly]: Not accessible to JavaScript

     

       34
       34
       +
             ({{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.6} Section 5.2.6})

     

       35
       35
       +
           - [samesite]: Cross-site request behavior (RFC 6265bis)

     

       36
       36
       +
           - [partitioned]: CHIPS partitioned storage

     

       37
       37
       +
       

     

       38
       38
       +
           {2 Domain and Path Matching}

     

       39
       39
       +
       

     

       40
       40
       +
           The library implements standard domain and path matching rules from

     

       41
       41
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3} Section 5.1.3}

     

       42
       42
       +
           and {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4} Section 5.1.4}:

     

       43
       43
       +
           - Domain matching uses suffix matching for hostnames (e.g., "example.com"

     

       44
       44
       +
             matches "sub.example.com")

     

       45
       45
       +
           - IP addresses require exact match only

     

       46
       46
       +
           - Path matching requires exact match or prefix with "/" separator

     

       47
       47
       +
       

     

       48
       48
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265> RFC 6265 - HTTP State Management Mechanism

     

       49
       49
       +
       

     

       50
       50
       +
           {2 Standards and References}

     

       51
       51
       +
       

     

       52
       52
       +
           This library implements and references the following IETF specifications:

     

       53
       53
       +
       

     

       54
       54
       +
           {ul

     

       55
       55
       +
           {- {{:https://datatracker.ietf.org/doc/html/rfc6265}RFC 6265} -

     

       56
       56
       +
              HTTP State Management Mechanism (April 2011) - Primary specification}

     

       57
       57
       +
           {- {{:https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis}RFC 6265bis} -

     

       58
       58
       +
              Cookies: HTTP State Management Mechanism (Draft) - SameSite attribute and modern updates}

     

       59
       59
       +
           {- {{:https://datatracker.ietf.org/doc/html/rfc1034#section-3.5}RFC 1034 Section 3.5} -

     

       60
       60
       +
              Domain Names - Preferred Name Syntax for domain validation}

     

       61
       61
       +
           {- {{:https://datatracker.ietf.org/doc/html/rfc2616#section-2.2}RFC 2616 Section 2.2} -

     

       62
       62
       +
              HTTP/1.1 - Token syntax definition}

     

       63
       63
       +
           {- {{:https://datatracker.ietf.org/doc/html/rfc1123#section-5.2.14}RFC 1123 Section 5.2.14} -

     

       64
       64
       +
              Internet Host Requirements - Date format (rfc1123-date)}}

     

       65
       65
       +
       

     

       66
       66
       +
           Additional standards:

     

       67
       67
       +
           {ul

     

       68
       68
       +
           {- {{:https://publicsuffix.org/}Mozilla Public Suffix List} - Registry

     

       69
       69
       +
              of public suffixes for cookie domain validation per RFC 6265 Section 5.3 Step 5}} *)

     

       70
       70
       +
       

     

       71
       71
       +
       (** {1 Types} *)

     

       72
       72
       +
       

     

       73
       73
       +
       module SameSite : sig

     

       74
       74
       +
         type t = [ `Strict | `Lax | `None ]

     

       75
       75
       +
         (** Cookie same-site policy for controlling cross-site request behavior.

     

       76
       76
       +
       

     

       77
       77
       +
             Defined in RFC 6265bis draft.

     

       78
       78
       +
       

     

       79
       79
       +
             - [`Strict]: Cookie only sent for same-site requests, providing maximum

     

       80
       80
       +
               protection

     

       81
       81
       +
             - [`Lax]: Cookie sent for same-site requests and top-level navigation

     

       82
       82
       +
               (default for modern browsers)

     

       83
       83
       +
             - [`None]: Cookie sent for all cross-site requests (requires [secure]

     

       84
       84
       +
               flag per RFC 6265bis)

     

       85
       85
       +
       

     

       86
       86
       +
             @see <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis#section-5.4.7> RFC 6265bis Section 5.4.7 - The SameSite Attribute *)

     

       87
       87
       +
       

     

       88
       88
       +
         val equal : t -> t -> bool

     

       89
       89
       +
         (** Equality function for same-site values. *)

     

       90
       90
       +
       

     

       91
       91
       +
         val pp : Format.formatter -> t -> unit

     

       92
       92
       +
         (** Pretty printer for same-site values. *)

     

       93
       93
       +
       end

     

       94
       94
       +
       

     

       95
       95
       +
       module Expiration : sig

     

       96
       96
       +
         type t = [ `Session | `DateTime of Ptime.t ]

     

       97
       97
       +
         (** Cookie expiration strategy.

     

       98
       98
       +
       

     

       99
       99
       +
             Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3}:

     

       100
       100
       +
             - [`Session]: Session cookie that expires when user agent session ends

     

       101
       101
       +
               (persistent-flag = false)

     

       102
       102
       +
             - [`DateTime time]: Persistent cookie that expires at specific time

     

       103
       103
       +
               (persistent-flag = true)

     

       104
       104
       +
       

     

       105
       105
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       106
       106
       +
       

     

       107
       107
       +
         val equal : t -> t -> bool

     

       108
       108
       +
         (** Equality function for expiration values. *)

     

       109
       109
       +
       

     

       110
       110
       +
         val pp : Format.formatter -> t -> unit

     

       111
       111
       +
         (** Pretty printer for expiration values. *)

     

       112
       112
       +
       end

     

       113
       113
       +
       

     

       114
       114
       +
       type t

     

       115
       115
       +
       (** HTTP Cookie representation with all standard attributes.

     

       116
       116
       +
       

     

       117
       117
       +
           A cookie represents a name-value pair with associated metadata that controls

     

       118
       118
       +
           its scope, security, and lifetime. Per

     

       119
       119
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3},

     

       120
       120
       +
           cookies with the same [name], [domain], and [path] will overwrite each other

     

       121
       121
       +
           when stored.

     

       122
       122
       +
       

     

       123
       123
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       124
       124
       +
       

     

       125
       125
       +
       (** {1 Cookie Accessors} *)

     

       126
       126
       +
       

     

       127
       127
       +
       val domain : t -> string

     

       128
       128
       +
       (** Get the domain of a cookie.

     

       129
       129
       +
       

     

       130
       130
       +
           The domain is normalized per

     

       131
       131
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3} RFC 6265 Section 5.2.3}

     

       132
       132
       +
           (leading dots removed). *)

     

       133
       133
       +
       

     

       134
       134
       +
       val path : t -> string

     

       135
       135
       +
       (** Get the path of a cookie.

     

       136
       136
       +
       

     

       137
       137
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4> RFC 6265 Section 5.2.4 - The Path Attribute *)

     

       138
       138
       +
       

     

       139
       139
       +
       val name : t -> string

     

       140
       140
       +
       (** Get the name of a cookie. *)

     

       141
       141
       +
       

     

       142
       142
       +
       val value : t -> string

     

       143
       143
       +
       (** Get the value of a cookie. *)

     

       144
       144
       +
       

     

       145
       145
       +
       val value_trimmed : t -> string

     

       146
       146
       +
       (** Get cookie value with surrounding double-quotes removed if they form a

     

       147
       147
       +
           matching pair.

     

       148
       148
       +
       

     

       149
       149
       +
           Only removes quotes when both opening and closing quotes are present. The

     

       150
       150
       +
           raw value is always preserved in {!value}. This is useful for handling

     

       151
       151
       +
           quoted cookie values.

     

       152
       152
       +
       

     

       153
       153
       +
           Examples:

     

       154
       154
       +
           - ["value"] → ["value"]

     

       155
       155
       +
           - ["\"value\""] → ["value"]

     

       156
       156
       +
           - ["\"value"] → ["\"value"] (no matching pair)

     

       157
       157
       +
           - ["\"val\"\""] → ["val\""] (removes outer pair only) *)

     

       158
       158
       +
       

     

       159
       159
       +
       val secure : t -> bool

     

       160
       160
       +
       (** Check if cookie has the Secure flag.

     

       161
       161
       +
       

     

       162
       162
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.5} RFC 6265 Section 5.2.5},

     

       163
       163
       +
           Secure cookies are only sent over HTTPS connections.

     

       164
       164
       +
       

     

       165
       165
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.5> RFC 6265 Section 5.2.5 - The Secure Attribute *)

     

       166
       166
       +
       

     

       167
       167
       +
       val http_only : t -> bool

     

       168
       168
       +
       (** Check if cookie has the HttpOnly flag.

     

       169
       169
       +
       

     

       170
       170
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.6} RFC 6265 Section 5.2.6},

     

       171
       171
       +
           HttpOnly cookies are not accessible to client-side scripts.

     

       172
       172
       +
       

     

       173
       173
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.6> RFC 6265 Section 5.2.6 - The HttpOnly Attribute *)

     

       174
       174
       +
       

     

       175
       175
       +
       val partitioned : t -> bool

     

       176
       176
       +
       (** Check if cookie has the Partitioned attribute.

     

       177
       177
       +
       

     

       178
       178
       +
           Partitioned cookies are part of CHIPS (Cookies Having Independent

     

       179
       179
       +
           Partitioned State) and are stored separately per top-level site, enabling

     

       180
       180
       +
           privacy-preserving third-party cookie functionality. Partitioned cookies

     

       181
       181
       +
           must always be Secure.

     

       182
       182
       +
       

     

       183
       183
       +
           @see <https://developer.chrome.com/docs/privacy-sandbox/chips/> CHIPS - Cookies Having Independent Partitioned State *)

     

       184
       184
       +
       

     

       185
       185
       +
       val host_only : t -> bool

     

       186
       186
       +
       (** Check if cookie has the host-only flag set.

     

       187
       187
       +
       

     

       188
       188
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3 Step 6}:

     

       189
       189
       +
           - If the Set-Cookie header included a Domain attribute, host-only-flag is

     

       190
       190
       +
             false and the cookie matches the domain and all subdomains.

     

       191
       191
       +
           - If no Domain attribute was present, host-only-flag is true and the cookie

     

       192
       192
       +
             only matches the exact request host.

     

       193
       193
       +
       

     

       194
       194
       +
           Example:

     

       195
       195
       +
           - Cookie set on "example.com" with Domain=example.com: host_only=false,

     

       196
       196
       +
             matches example.com and sub.example.com

     

       197
       197
       +
           - Cookie set on "example.com" without Domain attribute: host_only=true,

     

       198
       198
       +
             matches only example.com, not sub.example.com

     

       199
       199
       +
       

     

       200
       200
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       201
       201
       +
       

     

       202
       202
       +
       val expires : t -> Expiration.t option

     

       203
       203
       +
       (** Get the expiration attribute if set.

     

       204
       204
       +
       

     

       205
       205
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.1} RFC 6265 Section 5.2.1}:

     

       206
       206
       +
           - [None]: No expiration specified (session cookie)

     

       207
       207
       +
           - [Some `Session]: Session cookie (expires when user agent session ends)

     

       208
       208
       +
           - [Some (`DateTime t)]: Expires at specific time [t]

     

       209
       209
       +
       

     

       210
       210
       +
           Both [max_age] and [expires] can be present simultaneously. This library

     

       211
       211
       +
           stores both independently.

     

       212
       212
       +
       

     

       213
       213
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.1> RFC 6265 Section 5.2.1 - The Expires Attribute *)

     

       214
       214
       +
       

     

       215
       215
       +
       val max_age : t -> Ptime.Span.t option

     

       216
       216
       +
       (** Get the max-age attribute if set.

     

       217
       217
       +
       

     

       218
       218
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2} RFC 6265 Section 5.2.2},

     

       219
       219
       +
           Max-Age specifies the cookie lifetime in seconds. Both [max_age] and

     

       220
       220
       +
           [expires] can be present simultaneously. When both are present in a

     

       221
       221
       +
           Set-Cookie header, browsers prioritize [max_age] per

     

       222
       222
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} Section 5.3 Step 3}.

     

       223
       223
       +
       

     

       224
       224
       +
           This library stores both independently and serializes both when present.

     

       225
       225
       +
       

     

       226
       226
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2> RFC 6265 Section 5.2.2 - The Max-Age Attribute *)

     

       227
       227
       +
       

     

       228
       228
       +
       val same_site : t -> SameSite.t option

     

       229
       229
       +
       (** Get the same-site policy of a cookie.

     

       230
       230
       +
       

     

       231
       231
       +
           @see <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis#section-5.4.7> RFC 6265bis Section 5.4.7 - The SameSite Attribute *)

     

       232
       232
       +
       

     

       233
       233
       +
       val creation_time : t -> Ptime.t

     

       234
       234
       +
       (** Get the creation time of a cookie.

     

       235
       235
       +
       

     

       236
       236
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3},

     

       237
       237
       +
           this is set when the cookie is first received. *)

     

       238
       238
       +
       

     

       239
       239
       +
       val last_access : t -> Ptime.t

     

       240
       240
       +
       (** Get the last access time of a cookie.

     

       241
       241
       +
       

     

       242
       242
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3},

     

       243
       243
       +
           this is updated each time the cookie is retrieved for a request. *)

     

       244
       244
       +
       

     

       245
       245
       +
       val make :

     

       246
       246
       +
         domain:string ->

     

       247
       247
       +
         path:string ->

     

       248
       248
       +
         name:string ->

     

       249
       249
       +
         value:string ->

     

       250
       250
       +
         ?secure:bool ->

     

       251
       251
       +
         ?http_only:bool ->

     

       252
       252
       +
         ?expires:Expiration.t ->

     

       253
       253
       +
         ?max_age:Ptime.Span.t ->

     

       254
       254
       +
         ?same_site:SameSite.t ->

     

       255
       255
       +
         ?partitioned:bool ->

     

       256
       256
       +
         ?host_only:bool ->

     

       257
       257
       +
         creation_time:Ptime.t ->

     

       258
       258
       +
         last_access:Ptime.t ->

     

       259
       259
       +
         unit ->

     

       260
       260
       +
         t

     

       261
       261
       +
       (** Create a new cookie with the given attributes.

     

       262
       262
       +
       

     

       263
       263
       +
           @param domain The cookie domain (will be normalized)

     

       264
       264
       +
           @param path The cookie path

     

       265
       265
       +
           @param name The cookie name

     

       266
       266
       +
           @param value The cookie value

     

       267
       267
       +
           @param secure If true, cookie only sent over HTTPS (default: false)

     

       268
       268
       +
           @param http_only If true, cookie not accessible to scripts (default: false)

     

       269
       269
       +
           @param expires Expiration time

     

       270
       270
       +
           @param max_age Lifetime in seconds

     

       271
       271
       +
           @param same_site Cross-site request policy

     

       272
       272
       +
           @param partitioned CHIPS partitioned storage (default: false)

     

       273
       273
       +
           @param host_only If true, exact domain match only (default: false). Per

     

       274
       274
       +
                  {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3},

     

       275
       275
       +
                  this should be true when no Domain attribute was present in the

     

       276
       276
       +
                  Set-Cookie header.

     

       277
       277
       +
           @param creation_time When the cookie was created

     

       278
       278
       +
           @param last_access Last time the cookie was accessed

     

       279
       279
       +
       

     

       280
       280
       +
           Note: If [partitioned] is [true], the cookie must also be [secure]. Invalid

     

       281
       281
       +
           combinations will result in validation errors.

     

       282
       282
       +
       

     

       283
       283
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       284
       284
       +
       

     

       285
       285
       +
       (** {1 RFC 6265 Validation}

     

       286
       286
       +
       

     

       287
       287
       +
           Validation functions for cookie names, values, and attributes per

     

       288
       288
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1} RFC 6265 Section 4.1.1}.

     

       289
       289
       +
       

     

       290
       290
       +
           These functions implement the syntactic requirements from RFC 6265 to ensure

     

       291
       291
       +
           cookies conform to the specification before being sent in HTTP headers.

     

       292
       292
       +
           All validation failures return detailed error messages citing the specific

     

       293
       293
       +
           RFC requirement that was violated.

     

       294
       294
       +
       

     

       295
       295
       +
           {2 Validation Philosophy}

     

       296
       296
       +
       

     

       297
       297
       +
           Per RFC 6265 Section 4, there is an important distinction between:

     

       298
       298
       +
           - {b Server requirements} (Section 4.1): Strict syntax for generating Set-Cookie headers

     

       299
       299
       +
           - {b User agent requirements} (Section 5): Lenient parsing for receiving Set-Cookie headers

     

       300
       300
       +
       

     

       301
       301
       +
           These validation functions enforce the {b server requirements}, ensuring that

     

       302
       302
       +
           cookies generated by this library conform to RFC 6265 syntax. When parsing

     

       303
       303
       +
           cookies from HTTP headers, the library may be more lenient to maximize

     

       304
       304
       +
           interoperability with non-compliant servers.

     

       305
       305
       +
       

     

       306
       306
       +
           {2 Character Set Requirements}

     

       307
       307
       +
       

     

       308
       308
       +
           RFC 6265 restricts cookies to US-ASCII characters with specific exclusions:

     

       309
       309
       +
           - Cookie names: RFC 2616 tokens (no CTLs, no separators)

     

       310
       310
       +
           - Cookie values: cookie-octet characters (0x21, 0x23-0x2B, 0x2D-0x3A, 0x3C-0x5B, 0x5D-0x7E)

     

       311
       311
       +
           - Domain values: RFC 1034 domain name syntax or IP addresses

     

       312
       312
       +
           - Path values: Any character except CTLs and semicolon

     

       313
       313
       +
       

     

       314
       314
       +
           These functions return [Ok value] on success or [Error msg] with a detailed

     

       315
       315
       +
           explanation of why validation failed.

     

       316
       316
       +
       

     

       317
       317
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 - Syntax *)

     

       318
       318
       +
       

     

       319
       319
       +
       module Validate : sig

     

       320
       320
       +
         val cookie_name : string -> (string, string) result

     

       321
       321
       +
         (** Validate a cookie name per RFC 6265.

     

       322
       322
       +
       

     

       323
       323
       +
             Cookie names must be valid RFC 2616 tokens: one or more characters

     

       324
       324
       +
             excluding control characters and separators.

     

       325
       325
       +
       

     

       326
       326
       +
             Per {{:https://datatracker.ietf.org/doc/html/rfc2616#section-2.2}RFC 2616 Section 2.2},

     

       327
       327
       +
             a token is defined as: one or more characters excluding control characters

     

       328
       328
       +
             and the following 19 separator characters: parentheses, angle brackets, at-sign,

     

       329
       329
       +
             comma, semicolon, colon, backslash, double-quote, forward slash, square brackets,

     

       330
       330
       +
             question mark, equals, curly braces, space, and horizontal tab.

     

       331
       331
       +
       

     

       332
       332
       +
             This means tokens consist of visible ASCII characters (33-126) excluding

     

       333
       333
       +
             control characters (0-31, 127) and the separator characters listed above.

     

       334
       334
       +
       

     

       335
       335
       +
             @param name The cookie name to validate

     

       336
       336
       +
             @return [Ok name] if valid, [Error message] with explanation if invalid

     

       337
       337
       +
       

     

       338
       338
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1

     

       339
       339
       +
             @see <https://datatracker.ietf.org/doc/html/rfc2616#section-2.2> RFC 2616 Section 2.2 - Basic Rules *)

     

       340
       340
       +
       

     

       341
       341
       +
         val cookie_value : string -> (string, string) result

     

       342
       342
       +
         (** Validate a cookie value per RFC 6265.

     

       343
       343
       +
       

     

       344
       344
       +
             Cookie values must contain only cookie-octets, optionally wrapped in

     

       345
       345
       +
             double quotes. Invalid characters include: control characters, space,

     

       346
       346
       +
             double quote (except as wrapper), comma, semicolon, and backslash.

     

       347
       347
       +
       

     

       348
       348
       +
             Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1}RFC 6265 Section 4.1.1},

     

       349
       349
       +
             cookie-value may be:

     

       350
       350
       +
             - Zero or more cookie-octet characters, or

     

       351
       351
       +
             - Double-quoted string containing cookie-octet characters

     

       352
       352
       +
       

     

       353
       353
       +
             Where cookie-octet excludes: CTLs (0x00-0x1F, 0x7F), space (0x20),

     

       354
       354
       +
             double-quote (0x22), comma (0x2C), semicolon (0x3B), and backslash (0x5C).

     

       355
       355
       +
       

     

       356
       356
       +
             Valid cookie-octet characters: 0x21, 0x23-0x2B, 0x2D-0x3A, 0x3C-0x5B, 0x5D-0x7E

     

       357
       357
       +
       

     

       358
       358
       +
             @param value The cookie value to validate

     

       359
       359
       +
             @return [Ok value] if valid, [Error message] with explanation if invalid

     

       360
       360
       +
       

     

       361
       361
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)

     

       362
       362
       +
       

     

       363
       363
       +
         val domain_value : string -> (string, string) result

     

       364
       364
       +
         (** Validate a domain attribute value.

     

       365
       365
       +
       

     

       366
       366
       +
             Domain values must be either:

     

       367
       367
       +
             - A valid domain name per RFC 1034 Section 3.5

     

       368
       368
       +
             - A valid IPv4 address

     

       369
       369
       +
             - A valid IPv6 address

     

       370
       370
       +
       

     

       371
       371
       +
             Per {{:https://datatracker.ietf.org/doc/html/rfc1034#section-3.5}RFC 1034 Section 3.5},

     

       372
       372
       +
             preferred domain name syntax requires:

     

       373
       373
       +
             - Labels separated by dots

     

       374
       374
       +
             - Labels must start with a letter

     

       375
       375
       +
             - Labels must end with a letter or digit

     

       376
       376
       +
             - Labels may contain letters, digits, and hyphens

     

       377
       377
       +
             - Labels are case-insensitive

     

       378
       378
       +
             - Total length limited to 255 octets

     

       379
       379
       +
       

     

       380
       380
       +
             Leading dots are stripped per RFC 6265 Section 5.2.3 before validation.

     

       381
       381
       +
       

     

       382
       382
       +
             @param domain The domain value to validate (leading dot is stripped first)

     

       383
       383
       +
             @return [Ok domain] if valid, [Error message] with explanation if invalid

     

       384
       384
       +
       

     

       385
       385
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.3> RFC 6265 Section 4.1.2.3

     

       386
       386
       +
             @see <https://datatracker.ietf.org/doc/html/rfc1034#section-3.5> RFC 1034 Section 3.5 *)

     

       387
       387
       +
       

     

       388
       388
       +
         val path_value : string -> (string, string) result

     

       389
       389
       +
         (** Validate a path attribute value.

     

       390
       390
       +
       

     

       391
       391
       +
             Per RFC 6265 Section 4.1.1, path-value may contain any CHAR except

     

       392
       392
       +
             control characters and semicolon.

     

       393
       393
       +
       

     

       394
       394
       +
             @param path The path value to validate

     

       395
       395
       +
             @return [Ok path] if valid, [Error message] with explanation if invalid

     

       396
       396
       +
       

     

       397
       397
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)

     

       398
       398
       +
       

     

       399
       399
       +
         val max_age : int -> (int, string) result

     

       400
       400
       +
         (** Validate a Max-Age attribute value.

     

       401
       401
       +
       

     

       402
       402
       +
             Per RFC 6265 Section 4.1.1, max-age-av uses non-zero-digit *DIGIT.

     

       403
       403
       +
             However, per Section 5.2.2, user agents should treat values <= 0 as

     

       404
       404
       +
             "delete immediately". This function returns [Ok] for any integer since

     

       405
       405
       +
             the parsing code handles negative values by converting to 0.

     

       406
       406
       +
       

     

       407
       407
       +
             @param seconds The Max-Age value in seconds

     

       408
       408
       +
             @return [Ok seconds] always (negative values are handled in parsing)

     

       409
       409
       +
       

     

       410
       410
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1

     

       411
       411
       +
             @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2> RFC 6265 Section 5.2.2 *)

     

       412
       412
       +
       end

     

       413
       413
       +
       

     

       414
       414
       +
       (** {1 Cookie Creation and Parsing} *)

     

       415
       415
       +
       

     

       416
       416
       +
       val of_set_cookie_header :

     

       417
       417
       +
         now:(unit -> Ptime.t) ->

     

       418
       418
       +
         domain:string ->

     

       419
       419
       +
         path:string ->

     

       420
       420
       +
         string ->

     

       421
       421
       +
         (t, string) result

     

       422
       422
       +
       (** Parse Set-Cookie response header value into a cookie.

     

       423
       423
       +
       

     

       424
       424
       +
           Parses a Set-Cookie header following

     

       425
       425
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2} RFC 6265 Section 5.2}:

     

       426
       426
       +
           - Basic format: [NAME=VALUE; attribute1; attribute2=value2]

     

       427
       427
       +
           - Supports all standard attributes: [expires], [max-age], [domain], [path],

     

       428
       428
       +
             [secure], [httponly], [samesite], [partitioned]

     

       429
       429
       +
           - Returns [Error msg] if parsing fails or cookie validation fails, with

     

       430
       430
       +
             a detailed explanation of what was invalid

     

       431
       431
       +
           - The [domain] and [path] parameters provide the request context for default

     

       432
       432
       +
             values

     

       433
       433
       +
           - The [now] parameter is used for calculating expiry times from [max-age]

     

       434
       434
       +
             attributes and setting creation/access times

     

       435
       435
       +
       

     

       436
       436
       +
           Validation rules applied:

     

       437
       437
       +
           - Cookie name must be a valid RFC 2616 token (no CTLs or separators)

     

       438
       438
       +
           - Cookie value must contain only valid cookie-octets

     

       439
       439
       +
           - Domain must be a valid domain name (RFC 1034) or IP address

     

       440
       440
       +
           - Path must not contain control characters or semicolons

     

       441
       441
       +
           - Max-Age must be non-negative

     

       442
       442
       +
           - [SameSite=None] requires the [Secure] flag to be set (RFC 6265bis)

     

       443
       443
       +
           - [Partitioned] requires the [Secure] flag to be set (CHIPS)

     

       444
       444
       +
           - Domain must not be a public suffix per

     

       445
       445
       +
             {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3 Step 5}

     

       446
       446
       +
             (unless the request host exactly matches the domain). This uses the

     

       447
       447
       +
             {{:https://publicsuffix.org/list/} Mozilla Public Suffix List} to prevent

     

       448
       448
       +
             domain-wide cookie attacks.

     

       449
       449
       +
       

     

       450
       450
       +
           {3 Public Suffix Validation}

     

       451
       451
       +
       

     

       452
       452
       +
           Cookies with Domain attributes that are public suffixes (e.g., [.com], [.co.uk],

     

       453
       453
       +
           [.github.io]) are rejected to prevent a malicious site from setting cookies

     

       454
       454
       +
           that would affect all sites under that TLD.

     

       455
       455
       +
       

     

       456
       456
       +
           Examples:

     

       457
       457
       +
           - Request from [www.example.com], Domain=[.com] → rejected (public suffix)

     

       458
       458
       +
           - Request from [www.example.com], Domain=[.example.com] → allowed

     

       459
       459
       +
           - Request from [blogspot.com], Domain=[.blogspot.com] → allowed (request matches)

     

       460
       460
       +
       

     

       461
       461
       +
           Example:

     

       462
       462
       +
           {[of_set_cookie_header ~now:(fun () -> Ptime_clock.now ())

     

       463
       463
       +
            ~domain:"example.com" ~path:"/" "session=abc123; Secure; HttpOnly"]}

     

       464
       464
       +
       

     

       465
       465
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2> RFC 6265 Section 5.2 - The Set-Cookie Header

     

       466
       466
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model (public suffix check)

     

       467
       467
       +
           @see <https://publicsuffix.org/list/> Public Suffix List *)

     

       468
       468
       +
       

     

       469
       469
       +
       val of_cookie_header :

     

       470
       470
       +
         now:(unit -> Ptime.t) ->

     

       471
       471
       +
         domain:string ->

     

       472
       472
       +
         path:string ->

     

       473
       473
       +
         string ->

     

       474
       474
       +
         (t list, string) result

     

       475
       475
       +
       (** Parse Cookie request header containing semicolon-separated name=value pairs.

     

       476
       476
       +
       

     

       477
       477
       +
           Parses a Cookie header following

     

       478
       478
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.2} RFC 6265 Section 4.2}.

     

       479
       479
       +
           Cookie headers contain only name=value pairs without attributes:

     

       480
       480
       +
           ["name1=value1; name2=value2; name3=value3"]

     

       481
       481
       +
       

     

       482
       482
       +
           Validates each cookie name and value per RFC 6265 and detects duplicate

     

       483
       483
       +
           cookie names (which is forbidden per Section 4.2.1).

     

       484
       484
       +
       

     

       485
       485
       +
           Creates cookies with:

     

       486
       486
       +
           - Provided [domain] and [path] from request context

     

       487
       487
       +
           - All security flags set to [false] (defaults)

     

       488
       488
       +
           - All optional attributes set to [None]

     

       489
       489
       +
           - [host_only = true] (since we cannot determine from the header alone

     

       490
       490
       +
             whether cookies originally had a Domain attribute)

     

       491
       491
       +
           - [creation_time] and [last_access] set to current time from [now]

     

       492
       492
       +
       

     

       493
       493
       +
           Returns [Ok cookies] if all cookies parse successfully with no duplicates,

     

       494
       494
       +
           or [Error msg] if any validation fails.

     

       495
       495
       +
       

     

       496
       496
       +
           Example:

     

       497
       497
       +
           {[of_cookie_header ~now:(fun () -> Ptime_clock.now ()) ~domain:"example.com"

     

       498
       498
       +
            ~path:"/" "session=abc; theme=dark"]}

     

       499
       499
       +
       

     

       500
       500
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.2> RFC 6265 Section 4.2 - The Cookie Header *)

     

       501
       501
       +
       

     

       502
       502
       +
       val make_cookie_header : t list -> string

     

       503
       503
       +
       (** Create Cookie header value from cookies.

     

       504
       504
       +
       

     

       505
       505
       +
           Formats a list of cookies into a Cookie header value suitable for HTTP

     

       506
       506
       +
           requests per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.2} RFC 6265 Section 4.2}.

     

       507
       507
       +
           - Format: [name1=value1; name2=value2; name3=value3]

     

       508
       508
       +
           - Only includes cookie names and values, not attributes

     

       509
       509
       +
           - Cookies should already be filtered for the target domain/path

     

       510
       510
       +
       

     

       511
       511
       +
           Example: [make_cookie_header cookies] might return

     

       512
       512
       +
           ["session=abc123; theme=dark"]

     

       513
       513
       +
       

     

       514
       514
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.2> RFC 6265 Section 4.2 - The Cookie Header *)

     

       515
       515
       +
       

     

       516
       516
       +
       val make_set_cookie_header : t -> string

     

       517
       517
       +
       (** Create Set-Cookie header value from a cookie.

     

       518
       518
       +
       

     

       519
       519
       +
           Formats a cookie into a Set-Cookie header value suitable for HTTP responses

     

       520
       520
       +
           per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1} RFC 6265 Section 4.1}.

     

       521
       521
       +
           Includes all cookie attributes: Max-Age, Expires, Domain, Path, Secure,

     

       522
       522
       +
           HttpOnly, Partitioned, and SameSite.

     

       523
       523
       +
       

     

       524
       524
       +
           Note: The Expires attribute is currently formatted using RFC 3339 format,

     

       525
       525
       +
           which differs from the RFC-recommended rfc1123-date format specified in

     

       526
       526
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1} Section 4.1.1}.

     

       527
       527
       +
       

     

       528
       528
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1> RFC 6265 Section 4.1 - The Set-Cookie Header *)

     

       529
       529
       +
       

     

       530
       530
       +
       (** {1 Pretty Printing} *)

     

       531
       531
       +
       

     

       532
       532
       +
       val pp : Format.formatter -> t -> unit

     

       533
       533
       +
       (** Pretty print a cookie. *)

lib/core/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name cookeio)

     

       3
       3
       +
        (public_name cookeio)

     

       4
       4
       +
        (libraries logs ptime ipaddr domain-name publicsuffix))

-4

lib/dune

···

       1
       1
       -
       (library

     

       2
       2
       -
        (name cookeio)

     

       3
       3
       -
        (public_name cookeio)

     

       4
       4
       -
        (libraries eio logs ptime unix))

+578

lib/jar/cookeio_jar.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
         Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.

     

       3
       3
       +
         SPDX-License-Identifier: ISC

     

       4
       4
       +
        ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       let src = Logs.Src.create "cookie_jar" ~doc:"Cookie jar management"

     

       7
       7
       +
       

     

       8
       8
       +
       module Log = (val Logs.src_log src : Logs.LOG)

     

       9
       9
       +
       

     

       10
       10
       +
       type t = {

     

       11
       11
       +
         mutable original_cookies : Cookeio.t list; (* from client *)

     

       12
       12
       +
         mutable delta_cookies : Cookeio.t list; (* to send back *)

     

       13
       13
       +
         mutex : Eio.Mutex.t;

     

       14
       14
       +
       }

     

       15
       15
       +
       (** Cookie jar for storing and managing cookies *)

     

       16
       16
       +
       

     

       17
       17
       +
       (** {1 Cookie Jar Creation} *)

     

       18
       18
       +
       

     

       19
       19
       +
       let create () =

     

       20
       20
       +
         Log.debug (fun m -> m "Creating new empty cookie jar");

     

       21
       21
       +
         { original_cookies = []; delta_cookies = []; mutex = Eio.Mutex.create () }

     

       22
       22
       +
       

     

       23
       23
       +
       (** {1 Cookie Matching Helpers} *)

     

       24
       24
       +
       

     

       25
       25
       +
       (** Two cookies are considered identical if they have the same name, domain,

     

       26
       26
       +
           and path. This is used when replacing or removing cookies.

     

       27
       27
       +
       

     

       28
       28
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       29
       29
       +
       let cookie_identity_matches c1 c2 =

     

       30
       30
       +
         Cookeio.name c1 = Cookeio.name c2

     

       31
       31
       +
         && Cookeio.domain c1 = Cookeio.domain c2

     

       32
       32
       +
         && Cookeio.path c1 = Cookeio.path c2

     

       33
       33
       +
       

     

       34
       34
       +
       (** Normalize a domain by stripping the leading dot.

     

       35
       35
       +
       

     

       36
       36
       +
           Per RFC 6265, the Domain attribute value is canonicalized by removing any

     

       37
       37
       +
           leading dot before storage.

     

       38
       38
       +
       

     

       39
       39
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3> RFC 6265 Section 5.2.3 - The Domain Attribute *)

     

       40
       40
       +
       let normalize_domain domain =

     

       41
       41
       +
         match String.starts_with ~prefix:"." domain with

     

       42
       42
       +
         | true when String.length domain > 1 ->

     

       43
       43
       +
             String.sub domain 1 (String.length domain - 1)

     

       44
       44
       +
         | _ -> domain

     

       45
       45
       +
       

     

       46
       46
       +
       (** Remove duplicate cookies, keeping the last occurrence.

     

       47
       47
       +
       

     

       48
       48
       +
           Used to deduplicate combined cookie lists where delta cookies should

     

       49
       49
       +
           take precedence over original cookies. *)

     

       50
       50
       +
       let dedup_by_identity cookies =

     

       51
       51
       +
         let rec aux acc = function

     

       52
       52
       +
           | [] -> List.rev acc

     

       53
       53
       +
           | c :: rest ->

     

       54
       54
       +
               let has_duplicate =

     

       55
       55
       +
                 List.exists (fun c2 -> cookie_identity_matches c c2) rest

     

       56
       56
       +
               in

     

       57
       57
       +
               if has_duplicate then aux acc rest else aux (c :: acc) rest

     

       58
       58
       +
         in

     

       59
       59
       +
         aux [] cookies

     

       60
       60
       +
       

     

       61
       61
       +
       (** Check if a string is an IP address (IPv4 or IPv6).

     

       62
       62
       +
       

     

       63
       63
       +
           Per RFC 6265 Section 5.1.3, domain matching should only apply to hostnames,

     

       64
       64
       +
           not IP addresses. IP addresses require exact match only.

     

       65
       65
       +
       

     

       66
       66
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3> RFC 6265 Section 5.1.3 - Domain Matching *)

     

       67
       67
       +
       let is_ip_address domain = Result.is_ok (Ipaddr.of_string domain)

     

       68
       68
       +
       

     

       69
       69
       +
       (** Check if a cookie domain matches a request domain.

     

       70
       70
       +
       

     

       71
       71
       +
           Per RFC 6265 Section 5.1.3, a string domain-matches a given domain string if:

     

       72
       72
       +
           - The domain string and the string are identical, OR

     

       73
       73
       +
           - All of the following are true:

     

       74
       74
       +
             - The domain string is a suffix of the string

     

       75
       75
       +
             - The last character of the string not in the domain string is "."

     

       76
       76
       +
             - The string is a host name (i.e., not an IP address)

     

       77
       77
       +
       

     

       78
       78
       +
           Additionally, per Section 5.3 Step 6, if the cookie has the host-only-flag

     

       79
       79
       +
           set, only exact matches are allowed.

     

       80
       80
       +
       

     

       81
       81
       +
           @param host_only If true, only exact domain match is allowed

     

       82
       82
       +
           @param cookie_domain The domain stored in the cookie (without leading dot)

     

       83
       83
       +
           @param request_domain The domain from the HTTP request

     

       84
       84
       +
           @return true if the cookie should be sent for this domain

     

       85
       85
       +
       

     

       86
       86
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3> RFC 6265 Section 5.1.3 - Domain Matching

     

       87
       87
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model (host-only-flag) *)

     

       88
       88
       +
       let domain_matches ~host_only cookie_domain request_domain =

     

       89
       89
       +
         request_domain = cookie_domain

     

       90
       90
       +
         || (not (is_ip_address request_domain || host_only)

     

       91
       91
       +
             && String.ends_with ~suffix:("." ^ cookie_domain) request_domain)

     

       92
       92
       +
       

     

       93
       93
       +
       (** Check if a cookie path matches a request path.

     

       94
       94
       +
       

     

       95
       95
       +
           Per RFC 6265 Section 5.1.4, a request-path path-matches a given cookie-path if:

     

       96
       96
       +
           - The cookie-path and the request-path are identical, OR

     

       97
       97
       +
           - The cookie-path is a prefix of the request-path, AND either:

     

       98
       98
       +
             - The last character of the cookie-path is "/", OR

     

       99
       99
       +
             - The first character of the request-path that is not included in the

     

       100
       100
       +
               cookie-path is "/"

     

       101
       101
       +
       

     

       102
       102
       +
           @param cookie_path The path stored in the cookie

     

       103
       103
       +
           @param request_path The path from the HTTP request

     

       104
       104
       +
           @return true if the cookie should be sent for this path

     

       105
       105
       +
       

     

       106
       106
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4> RFC 6265 Section 5.1.4 - Paths and Path-Match *)

     

       107
       107
       +
       let path_matches cookie_path request_path =

     

       108
       108
       +
         if cookie_path = request_path then true

     

       109
       109
       +
         else if String.starts_with ~prefix:cookie_path request_path then

     

       110
       110
       +
           let cookie_len = String.length cookie_path in

     

       111
       111
       +
           String.ends_with ~suffix:"/" cookie_path

     

       112
       112
       +
           || (String.length request_path > cookie_len && request_path.[cookie_len] = '/')

     

       113
       113
       +
         else false

     

       114
       114
       +
       

     

       115
       115
       +
       (** {1 Cookie Expiration} *)

     

       116
       116
       +
       

     

       117
       117
       +
       (** Check if a cookie has expired based on its expiry-time.

     

       118
       118
       +
       

     

       119
       119
       +
           Per RFC 6265 Section 5.3, a cookie is expired if the current date and time

     

       120
       120
       +
           is past the expiry-time. Session cookies (with no Expires or Max-Age) never

     

       121
       121
       +
           expire via this check - they expire when the "session" ends.

     

       122
       122
       +
       

     

       123
       123
       +
           @param cookie The cookie to check

     

       124
       124
       +
           @param clock The Eio clock for current time

     

       125
       125
       +
           @return true if the cookie has expired

     

       126
       126
       +
       

     

       127
       127
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       128
       128
       +
       let is_expired cookie clock =

     

       129
       129
       +
         match Cookeio.expires cookie with

     

       130
       130
       +
         | None -> false (* No expiration *)

     

       131
       131
       +
         | Some `Session ->

     

       132
       132
       +
             false (* Session cookie - not expired until browser closes *)

     

       133
       133
       +
         | Some (`DateTime exp_time) ->

     

       134
       134
       +
             let now =

     

       135
       135
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       136
       136
       +
               |> Option.value ~default:Ptime.epoch

     

       137
       137
       +
             in

     

       138
       138
       +
             Ptime.compare now exp_time > 0

     

       139
       139
       +
       

     

       140
       140
       +
       let pp ppf jar =

     

       141
       141
       +
         Eio.Mutex.lock jar.mutex;

     

       142
       142
       +
         let original = jar.original_cookies in

     

       143
       143
       +
         let delta = jar.delta_cookies in

     

       144
       144
       +
         Eio.Mutex.unlock jar.mutex;

     

       145
       145
       +
       

     

       146
       146
       +
         let all_cookies = original @ delta in

     

       147
       147
       +
         Format.fprintf ppf "@[<v>CookieJar with %d cookies (%d original, %d delta):@,"

     

       148
       148
       +
           (List.length all_cookies) (List.length original) (List.length delta);

     

       149
       149
       +
         List.iter

     

       150
       150
       +
           (fun cookie -> Format.fprintf ppf "  %a@," Cookeio.pp cookie)

     

       151
       151
       +
           all_cookies;

     

       152
       152
       +
         Format.fprintf ppf "@]"

     

       153
       153
       +
       

     

       154
       154
       +
       (** {1 Cookie Management} *)

     

       155
       155
       +
       

     

       156
       156
       +
       (** Preserve creation time from an existing cookie when replacing.

     

       157
       157
       +
       

     

       158
       158
       +
           Per RFC 6265 Section 5.3, Step 11.3: "If the newly created cookie was

     

       159
       159
       +
           received from a 'non-HTTP' API and the old-cookie's http-only-flag is

     

       160
       160
       +
           true, abort these steps and ignore the newly created cookie entirely."

     

       161
       161
       +
           Step 11.3 also states: "Update the creation-time of the old-cookie to

     

       162
       162
       +
           match the creation-time of the newly created cookie."

     

       163
       163
       +
       

     

       164
       164
       +
           However, the common interpretation (and browser behavior) is to preserve

     

       165
       165
       +
           the original creation-time when updating a cookie. This matches what

     

       166
       166
       +
           Step 3 of Section 5.4 uses for ordering (creation-time stability).

     

       167
       167
       +
       

     

       168
       168
       +
           @param old_cookie The existing cookie being replaced (if any)

     

       169
       169
       +
           @param new_cookie The new cookie to add

     

       170
       170
       +
           @return The new cookie with creation_time preserved from old_cookie if present

     

       171
       171
       +
       

     

       172
       172
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       173
       173
       +
       let preserve_creation_time old_cookie_opt new_cookie =

     

       174
       174
       +
         match old_cookie_opt with

     

       175
       175
       +
         | None -> new_cookie

     

       176
       176
       +
         | Some old_cookie ->

     

       177
       177
       +
             Cookeio.make ~domain:(Cookeio.domain new_cookie)

     

       178
       178
       +
               ~path:(Cookeio.path new_cookie) ~name:(Cookeio.name new_cookie)

     

       179
       179
       +
               ~value:(Cookeio.value new_cookie) ~secure:(Cookeio.secure new_cookie)

     

       180
       180
       +
               ~http_only:(Cookeio.http_only new_cookie)

     

       181
       181
       +
               ?expires:(Cookeio.expires new_cookie)

     

       182
       182
       +
               ?max_age:(Cookeio.max_age new_cookie)

     

       183
       183
       +
               ?same_site:(Cookeio.same_site new_cookie)

     

       184
       184
       +
               ~partitioned:(Cookeio.partitioned new_cookie)

     

       185
       185
       +
               ~host_only:(Cookeio.host_only new_cookie)

     

       186
       186
       +
               ~creation_time:(Cookeio.creation_time old_cookie)

     

       187
       187
       +
               ~last_access:(Cookeio.last_access new_cookie)

     

       188
       188
       +
               ()

     

       189
       189
       +
       

     

       190
       190
       +
       let add_cookie jar cookie =

     

       191
       191
       +
         Log.debug (fun m ->

     

       192
       192
       +
             m "Adding cookie to delta: %s=%s for domain %s" (Cookeio.name cookie)

     

       193
       193
       +
               (Cookeio.value cookie) (Cookeio.domain cookie));

     

       194
       194
       +
       

     

       195
       195
       +
         Eio.Mutex.lock jar.mutex;

     

       196
       196
       +
       

     

       197
       197
       +
         (* Find existing cookie with same identity to preserve creation_time

     

       198
       198
       +
            per RFC 6265 Section 5.3, Step 11.3 *)

     

       199
       199
       +
         let existing =

     

       200
       200
       +
           List.find_opt (fun c -> cookie_identity_matches c cookie) jar.delta_cookies

     

       201
       201
       +
         in

     

       202
       202
       +
         let existing =

     

       203
       203
       +
           match existing with

     

       204
       204
       +
           | Some _ -> existing

     

       205
       205
       +
           | None ->

     

       206
       206
       +
               (* Also check original cookies for creation time preservation *)

     

       207
       207
       +
               List.find_opt

     

       208
       208
       +
                 (fun c -> cookie_identity_matches c cookie)

     

       209
       209
       +
                 jar.original_cookies

     

       210
       210
       +
         in

     

       211
       211
       +
       

     

       212
       212
       +
         let cookie = preserve_creation_time existing cookie in

     

       213
       213
       +
       

     

       214
       214
       +
         (* Remove existing cookie with same identity from delta *)

     

       215
       215
       +
         jar.delta_cookies <-

     

       216
       216
       +
           List.filter

     

       217
       217
       +
             (fun c -> not (cookie_identity_matches c cookie))

     

       218
       218
       +
             jar.delta_cookies;

     

       219
       219
       +
         jar.delta_cookies <- cookie :: jar.delta_cookies;

     

       220
       220
       +
         Eio.Mutex.unlock jar.mutex

     

       221
       221
       +
       

     

       222
       222
       +
       let add_original jar cookie =

     

       223
       223
       +
         Log.debug (fun m ->

     

       224
       224
       +
             m "Adding original cookie: %s=%s for domain %s" (Cookeio.name cookie)

     

       225
       225
       +
               (Cookeio.value cookie) (Cookeio.domain cookie));

     

       226
       226
       +
       

     

       227
       227
       +
         Eio.Mutex.lock jar.mutex;

     

       228
       228
       +
       

     

       229
       229
       +
         (* Find existing cookie with same identity to preserve creation_time

     

       230
       230
       +
            per RFC 6265 Section 5.3, Step 11.3 *)

     

       231
       231
       +
         let existing =

     

       232
       232
       +
           List.find_opt

     

       233
       233
       +
             (fun c -> cookie_identity_matches c cookie)

     

       234
       234
       +
             jar.original_cookies

     

       235
       235
       +
         in

     

       236
       236
       +
       

     

       237
       237
       +
         let cookie = preserve_creation_time existing cookie in

     

       238
       238
       +
       

     

       239
       239
       +
         (* Remove existing cookie with same identity from original *)

     

       240
       240
       +
         jar.original_cookies <-

     

       241
       241
       +
           List.filter

     

       242
       242
       +
             (fun c -> not (cookie_identity_matches c cookie))

     

       243
       243
       +
             jar.original_cookies;

     

       244
       244
       +
         jar.original_cookies <- cookie :: jar.original_cookies;

     

       245
       245
       +
         Eio.Mutex.unlock jar.mutex

     

       246
       246
       +
       

     

       247
       247
       +
       let delta jar =

     

       248
       248
       +
         Eio.Mutex.lock jar.mutex;

     

       249
       249
       +
         let result = jar.delta_cookies in

     

       250
       250
       +
         Eio.Mutex.unlock jar.mutex;

     

       251
       251
       +
         Log.debug (fun m -> m "Returning %d delta cookies" (List.length result));

     

       252
       252
       +
         result

     

       253
       253
       +
       

     

       254
       254
       +
       (** Create a removal cookie for deleting a cookie from the client.

     

       255
       255
       +
       

     

       256
       256
       +
           Per RFC 6265 Section 5.3, to remove a cookie, the server sends a Set-Cookie

     

       257
       257
       +
           header with an expiry date in the past. We also set Max-Age=0 and an empty

     

       258
       258
       +
           value for maximum compatibility.

     

       259
       259
       +
       

     

       260
       260
       +
           @param cookie The cookie to create a removal for

     

       261
       261
       +
           @param clock The Eio clock for timestamps

     

       262
       262
       +
           @return A new cookie configured to cause deletion

     

       263
       263
       +
       

     

       264
       264
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       265
       265
       +
       let make_removal_cookie cookie ~clock =

     

       266
       266
       +
         let now =

     

       267
       267
       +
           Ptime.of_float_s (Eio.Time.now clock) |> Option.value ~default:Ptime.epoch

     

       268
       268
       +
         in

     

       269
       269
       +
         (* Create a cookie with Max-Age=0 and past expiration (1 year ago) *)

     

       270
       270
       +
         let past_expiry =

     

       271
       271
       +
           Ptime.sub_span now (Ptime.Span.of_int_s (365 * 24 * 60 * 60))

     

       272
       272
       +
           |> Option.value ~default:Ptime.epoch

     

       273
       273
       +
         in

     

       274
       274
       +
         Cookeio.make ~domain:(Cookeio.domain cookie) ~path:(Cookeio.path cookie)

     

       275
       275
       +
           ~name:(Cookeio.name cookie) ~value:"" ~secure:(Cookeio.secure cookie)

     

       276
       276
       +
           ~http_only:(Cookeio.http_only cookie) ~expires:(`DateTime past_expiry)

     

       277
       277
       +
           ~max_age:(Ptime.Span.of_int_s 0) ?same_site:(Cookeio.same_site cookie)

     

       278
       278
       +
           ~partitioned:(Cookeio.partitioned cookie)

     

       279
       279
       +
           ~host_only:(Cookeio.host_only cookie)

     

       280
       280
       +
           ~creation_time:now ~last_access:now ()

     

       281
       281
       +
       

     

       282
       282
       +
       let remove jar ~clock cookie =

     

       283
       283
       +
         Log.debug (fun m ->

     

       284
       284
       +
             m "Removing cookie: %s=%s for domain %s" (Cookeio.name cookie)

     

       285
       285
       +
               (Cookeio.value cookie) (Cookeio.domain cookie));

     

       286
       286
       +
       

     

       287
       287
       +
         Eio.Mutex.lock jar.mutex;

     

       288
       288
       +
         (* Check if this cookie exists in original_cookies *)

     

       289
       289
       +
         let in_original =

     

       290
       290
       +
           List.exists (fun c -> cookie_identity_matches c cookie) jar.original_cookies

     

       291
       291
       +
         in

     

       292
       292
       +
       

     

       293
       293
       +
         if in_original then (

     

       294
       294
       +
           (* Create a removal cookie and add it to delta *)

     

       295
       295
       +
           let removal = make_removal_cookie cookie ~clock in

     

       296
       296
       +
           jar.delta_cookies <-

     

       297
       297
       +
             List.filter

     

       298
       298
       +
               (fun c -> not (cookie_identity_matches c removal))

     

       299
       299
       +
               jar.delta_cookies;

     

       300
       300
       +
           jar.delta_cookies <- removal :: jar.delta_cookies;

     

       301
       301
       +
           Log.debug (fun m -> m "Created removal cookie in delta for original cookie"))

     

       302
       302
       +
         else (

     

       303
       303
       +
           (* Just remove from delta if it exists there *)

     

       304
       304
       +
           jar.delta_cookies <-

     

       305
       305
       +
             List.filter

     

       306
       306
       +
               (fun c -> not (cookie_identity_matches c cookie))

     

       307
       307
       +
               jar.delta_cookies;

     

       308
       308
       +
           Log.debug (fun m -> m "Removed cookie from delta"));

     

       309
       309
       +
       

     

       310
       310
       +
         Eio.Mutex.unlock jar.mutex

     

       311
       311
       +
       

     

       312
       312
       +
       (** Compare cookies for ordering per RFC 6265 Section 5.4, Step 2.

     

       313
       313
       +
       

     

       314
       314
       +
           Cookies SHOULD be sorted:

     

       315
       315
       +
           1. Cookies with longer paths listed first

     

       316
       316
       +
           2. Among equal-length paths, cookies with earlier creation-times first

     

       317
       317
       +
       

     

       318
       318
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.4> RFC 6265 Section 5.4 - The Cookie Header *)

     

       319
       319
       +
       let compare_cookie_order c1 c2 =

     

       320
       320
       +
         let path1_len = String.length (Cookeio.path c1) in

     

       321
       321
       +
         let path2_len = String.length (Cookeio.path c2) in

     

       322
       322
       +
         (* Longer paths first (descending order) *)

     

       323
       323
       +
         match Int.compare path2_len path1_len with

     

       324
       324
       +
         | 0 ->

     

       325
       325
       +
             (* Equal path lengths: earlier creation time first (ascending order) *)

     

       326
       326
       +
             Ptime.compare (Cookeio.creation_time c1) (Cookeio.creation_time c2)

     

       327
       327
       +
         | n -> n

     

       328
       328
       +
       

     

       329
       329
       +
       (** Retrieve cookies that should be sent for a given request.

     

       330
       330
       +
       

     

       331
       331
       +
           Per RFC 6265 Section 5.4, the user agent should include a Cookie header

     

       332
       332
       +
           containing cookies that match the request-uri's domain, path, and security

     

       333
       333
       +
           context. This function also updates the last-access-time for matched cookies.

     

       334
       334
       +
       

     

       335
       335
       +
           Cookies are sorted per Section 5.4, Step 2:

     

       336
       336
       +
           1. Cookies with longer paths listed first

     

       337
       337
       +
           2. Among equal-length paths, earlier creation-times listed first

     

       338
       338
       +
       

     

       339
       339
       +
           @param jar The cookie jar to search

     

       340
       340
       +
           @param clock The Eio clock for timestamp updates

     

       341
       341
       +
           @param domain The request domain (hostname or IP address)

     

       342
       342
       +
           @param path The request path

     

       343
       343
       +
           @param is_secure Whether the request is over a secure channel (HTTPS)

     

       344
       344
       +
           @return List of cookies that should be included in the Cookie header, sorted

     

       345
       345
       +
       

     

       346
       346
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.4> RFC 6265 Section 5.4 - The Cookie Header *)

     

       347
       347
       +
       let get_cookies jar ~clock ~domain:request_domain ~path:request_path ~is_secure

     

       348
       348
       +
           =

     

       349
       349
       +
         Log.debug (fun m ->

     

       350
       350
       +
             m "Getting cookies for domain=%s path=%s secure=%b" request_domain

     

       351
       351
       +
               request_path is_secure);

     

       352
       352
       +
       

     

       353
       353
       +
         Eio.Mutex.lock jar.mutex;

     

       354
       354
       +
       

     

       355
       355
       +
         (* Combine original and delta cookies, with delta taking precedence *)

     

       356
       356
       +
         let all_cookies = jar.original_cookies @ jar.delta_cookies in

     

       357
       357
       +
         let unique_cookies = dedup_by_identity all_cookies in

     

       358
       358
       +
       

     

       359
       359
       +
         (* Filter for applicable cookies, excluding removal cookies and expired cookies *)

     

       360
       360
       +
         let applicable =

     

       361
       361
       +
           List.filter

     

       362
       362
       +
             (fun cookie ->

     

       363
       363
       +
               Cookeio.value cookie <> ""

     

       364
       364
       +
               (* Exclude removal cookies *)

     

       365
       365
       +
               && (not (is_expired cookie clock))

     

       366
       366
       +
               (* Exclude expired cookies *)

     

       367
       367
       +
               && domain_matches ~host_only:(Cookeio.host_only cookie)

     

       368
       368
       +
                    (Cookeio.domain cookie) request_domain

     

       369
       369
       +
               && path_matches (Cookeio.path cookie) request_path

     

       370
       370
       +
               && ((not (Cookeio.secure cookie)) || is_secure))

     

       371
       371
       +
             unique_cookies

     

       372
       372
       +
         in

     

       373
       373
       +
       

     

       374
       374
       +
         (* Sort cookies per RFC 6265 Section 5.4, Step 2:

     

       375
       375
       +
            - Longer paths first

     

       376
       376
       +
            - Equal paths: earlier creation time first *)

     

       377
       377
       +
         let sorted = List.sort compare_cookie_order applicable in

     

       378
       378
       +
       

     

       379
       379
       +
         (* Update last access time in both lists *)

     

       380
       380
       +
         let now =

     

       381
       381
       +
           Ptime.of_float_s (Eio.Time.now clock) |> Option.value ~default:Ptime.epoch

     

       382
       382
       +
         in

     

       383
       383
       +
         let update_last_access cookies =

     

       384
       384
       +
           List.map

     

       385
       385
       +
             (fun c ->

     

       386
       386
       +
               if List.exists (fun a -> cookie_identity_matches a c) applicable then

     

       387
       387
       +
                 Cookeio.make ~domain:(Cookeio.domain c) ~path:(Cookeio.path c)

     

       388
       388
       +
                   ~name:(Cookeio.name c) ~value:(Cookeio.value c)

     

       389
       389
       +
                   ~secure:(Cookeio.secure c) ~http_only:(Cookeio.http_only c)

     

       390
       390
       +
                   ?expires:(Cookeio.expires c) ?max_age:(Cookeio.max_age c)

     

       391
       391
       +
                   ?same_site:(Cookeio.same_site c)

     

       392
       392
       +
                   ~partitioned:(Cookeio.partitioned c)

     

       393
       393
       +
                   ~host_only:(Cookeio.host_only c)

     

       394
       394
       +
                   ~creation_time:(Cookeio.creation_time c) ~last_access:now ()

     

       395
       395
       +
               else c)

     

       396
       396
       +
             cookies

     

       397
       397
       +
         in

     

       398
       398
       +
         jar.original_cookies <- update_last_access jar.original_cookies;

     

       399
       399
       +
         jar.delta_cookies <- update_last_access jar.delta_cookies;

     

       400
       400
       +
       

     

       401
       401
       +
         Eio.Mutex.unlock jar.mutex;

     

       402
       402
       +
       

     

       403
       403
       +
         Log.debug (fun m -> m "Found %d applicable cookies" (List.length sorted));

     

       404
       404
       +
         sorted

     

       405
       405
       +
       

     

       406
       406
       +
       let clear jar =

     

       407
       407
       +
         Log.info (fun m -> m "Clearing all cookies");

     

       408
       408
       +
         Eio.Mutex.lock jar.mutex;

     

       409
       409
       +
         jar.original_cookies <- [];

     

       410
       410
       +
         jar.delta_cookies <- [];

     

       411
       411
       +
         Eio.Mutex.unlock jar.mutex

     

       412
       412
       +
       

     

       413
       413
       +
       let clear_expired jar ~clock =

     

       414
       414
       +
         Eio.Mutex.lock jar.mutex;

     

       415
       415
       +
         let before_count =

     

       416
       416
       +
           List.length jar.original_cookies + List.length jar.delta_cookies

     

       417
       417
       +
         in

     

       418
       418
       +
         jar.original_cookies <-

     

       419
       419
       +
           List.filter (fun c -> not (is_expired c clock)) jar.original_cookies;

     

       420
       420
       +
         jar.delta_cookies <-

     

       421
       421
       +
           List.filter (fun c -> not (is_expired c clock)) jar.delta_cookies;

     

       422
       422
       +
         let removed =

     

       423
       423
       +
           before_count

     

       424
       424
       +
           - (List.length jar.original_cookies + List.length jar.delta_cookies)

     

       425
       425
       +
         in

     

       426
       426
       +
         Eio.Mutex.unlock jar.mutex;

     

       427
       427
       +
         Log.info (fun m -> m "Cleared %d expired cookies" removed)

     

       428
       428
       +
       

     

       429
       429
       +
       let clear_session_cookies jar =

     

       430
       430
       +
         Eio.Mutex.lock jar.mutex;

     

       431
       431
       +
         let before_count =

     

       432
       432
       +
           List.length jar.original_cookies + List.length jar.delta_cookies

     

       433
       433
       +
         in

     

       434
       434
       +
         (* Keep only cookies that are NOT session cookies *)

     

       435
       435
       +
         let is_not_session c =

     

       436
       436
       +
           match Cookeio.expires c with

     

       437
       437
       +
           | Some `Session -> false (* This is a session cookie, remove it *)

     

       438
       438
       +
           | None | Some (`DateTime _) -> true (* Keep these *)

     

       439
       439
       +
         in

     

       440
       440
       +
         jar.original_cookies <- List.filter is_not_session jar.original_cookies;

     

       441
       441
       +
         jar.delta_cookies <- List.filter is_not_session jar.delta_cookies;

     

       442
       442
       +
         let removed =

     

       443
       443
       +
           before_count

     

       444
       444
       +
           - (List.length jar.original_cookies + List.length jar.delta_cookies)

     

       445
       445
       +
         in

     

       446
       446
       +
         Eio.Mutex.unlock jar.mutex;

     

       447
       447
       +
         Log.info (fun m -> m "Cleared %d session cookies" removed)

     

       448
       448
       +
       

     

       449
       449
       +
       let count jar =

     

       450
       450
       +
         Eio.Mutex.lock jar.mutex;

     

       451
       451
       +
         let all_cookies = jar.original_cookies @ jar.delta_cookies in

     

       452
       452
       +
         let unique = dedup_by_identity all_cookies in

     

       453
       453
       +
         let n = List.length unique in

     

       454
       454
       +
         Eio.Mutex.unlock jar.mutex;

     

       455
       455
       +
         n

     

       456
       456
       +
       

     

       457
       457
       +
       let get_all_cookies jar =

     

       458
       458
       +
         Eio.Mutex.lock jar.mutex;

     

       459
       459
       +
         let all_cookies = jar.original_cookies @ jar.delta_cookies in

     

       460
       460
       +
         let unique = dedup_by_identity all_cookies in

     

       461
       461
       +
         Eio.Mutex.unlock jar.mutex;

     

       462
       462
       +
         unique

     

       463
       463
       +
       

     

       464
       464
       +
       let is_empty jar =

     

       465
       465
       +
         Eio.Mutex.lock jar.mutex;

     

       466
       466
       +
         let empty = jar.original_cookies = [] && jar.delta_cookies = [] in

     

       467
       467
       +
         Eio.Mutex.unlock jar.mutex;

     

       468
       468
       +
         empty

     

       469
       469
       +
       

     

       470
       470
       +
       (** {1 Mozilla Format} *)

     

       471
       471
       +
       

     

       472
       472
       +
       let to_mozilla_format_internal jar =

     

       473
       473
       +
         let buffer = Buffer.create 1024 in

     

       474
       474
       +
         Buffer.add_string buffer "# Netscape HTTP Cookie File\n";

     

       475
       475
       +
         Buffer.add_string buffer "# This is a generated file!  Do not edit.\n\n";

     

       476
       476
       +
       

     

       477
       477
       +
         (* Combine and deduplicate cookies *)

     

       478
       478
       +
         let all_cookies = jar.original_cookies @ jar.delta_cookies in

     

       479
       479
       +
         let unique = dedup_by_identity all_cookies in

     

       480
       480
       +
       

     

       481
       481
       +
         List.iter

     

       482
       482
       +
           (fun cookie ->

     

       483
       483
       +
             (* Mozilla format: include_subdomains=TRUE means host_only=false *)

     

       484
       484
       +
             let include_subdomains = if Cookeio.host_only cookie then "FALSE" else "TRUE" in

     

       485
       485
       +
             let secure_flag = if Cookeio.secure cookie then "TRUE" else "FALSE" in

     

       486
       486
       +
             let expires_str =

     

       487
       487
       +
               match Cookeio.expires cookie with

     

       488
       488
       +
               | None -> "0" (* No expiration *)

     

       489
       489
       +
               | Some `Session -> "0" (* Session cookie *)

     

       490
       490
       +
               | Some (`DateTime t) ->

     

       491
       491
       +
                   let epoch = Ptime.to_float_s t |> int_of_float |> string_of_int in

     

       492
       492
       +
                   epoch

     

       493
       493
       +
             in

     

       494
       494
       +
       

     

       495
       495
       +
             Buffer.add_string buffer

     

       496
       496
       +
               (Printf.sprintf "%s\t%s\t%s\t%s\t%s\t%s\t%s\n" (Cookeio.domain cookie)

     

       497
       497
       +
                  include_subdomains (Cookeio.path cookie) secure_flag expires_str

     

       498
       498
       +
                  (Cookeio.name cookie) (Cookeio.value cookie)))

     

       499
       499
       +
           unique;

     

       500
       500
       +
       

     

       501
       501
       +
         Buffer.contents buffer

     

       502
       502
       +
       

     

       503
       503
       +
       let to_mozilla_format jar =

     

       504
       504
       +
         Eio.Mutex.lock jar.mutex;

     

       505
       505
       +
         let result = to_mozilla_format_internal jar in

     

       506
       506
       +
         Eio.Mutex.unlock jar.mutex;

     

       507
       507
       +
         result

     

       508
       508
       +
       

     

       509
       509
       +
       let from_mozilla_format ~clock content =

     

       510
       510
       +
         Log.debug (fun m -> m "Parsing Mozilla format cookies");

     

       511
       511
       +
         let jar = create () in

     

       512
       512
       +
       

     

       513
       513
       +
         let lines = String.split_on_char '\n' content in

     

       514
       514
       +
         List.iter

     

       515
       515
       +
           (fun line ->

     

       516
       516
       +
             let line = String.trim line in

     

       517
       517
       +
             if line <> "" && not (String.starts_with ~prefix:"#" line) then

     

       518
       518
       +
               match String.split_on_char '\t' line with

     

       519
       519
       +
               | [ domain; include_subdomains; path; secure; expires; name; value ] ->

     

       520
       520
       +
                   let now =

     

       521
       521
       +
                     Ptime.of_float_s (Eio.Time.now clock)

     

       522
       522
       +
                     |> Option.value ~default:Ptime.epoch

     

       523
       523
       +
                   in

     

       524
       524
       +
                   let expires =

     

       525
       525
       +
                     match int_of_string_opt expires with

     

       526
       526
       +
                     | Some exp_int when exp_int <> 0 ->

     

       527
       527
       +
                         Option.map (fun t -> `DateTime t)

     

       528
       528
       +
                           (Ptime.of_float_s (float_of_int exp_int))

     

       529
       529
       +
                     | _ -> None

     

       530
       530
       +
                   in

     

       531
       531
       +
                   (* Mozilla format: include_subdomains=TRUE means host_only=false *)

     

       532
       532
       +
                   let host_only = include_subdomains <> "TRUE" in

     

       533
       533
       +
       

     

       534
       534
       +
                   let cookie =

     

       535
       535
       +
                     Cookeio.make ~domain:(normalize_domain domain) ~path ~name ~value

     

       536
       536
       +
                       ~secure:(secure = "TRUE") ~http_only:false ?expires

     

       537
       537
       +
                       ?max_age:None ?same_site:None ~partitioned:false ~host_only

     

       538
       538
       +
                       ~creation_time:now ~last_access:now ()

     

       539
       539
       +
                   in

     

       540
       540
       +
                   add_original jar cookie;

     

       541
       541
       +
                   Log.debug (fun m -> m "Loaded cookie: %s=%s" name value)

     

       542
       542
       +
               | _ -> Log.warn (fun m -> m "Invalid cookie line: %s" line))

     

       543
       543
       +
           lines;

     

       544
       544
       +
       

     

       545
       545
       +
         Log.info (fun m -> m "Loaded %d cookies" (List.length jar.original_cookies));

     

       546
       546
       +
         jar

     

       547
       547
       +
       

     

       548
       548
       +
       (** {1 File Operations} *)

     

       549
       549
       +
       

     

       550
       550
       +
       let load ~clock path =

     

       551
       551
       +
         Log.info (fun m -> m "Loading cookies from %a" Eio.Path.pp path);

     

       552
       552
       +
       

     

       553
       553
       +
         try

     

       554
       554
       +
           let content = Eio.Path.load path in

     

       555
       555
       +
           from_mozilla_format ~clock content

     

       556
       556
       +
         with

     

       557
       557
       +
         | Eio.Io _ ->

     

       558
       558
       +
             Log.info (fun m -> m "Cookie file not found, creating empty jar");

     

       559
       559
       +
             create ()

     

       560
       560
       +
         | exn ->

     

       561
       561
       +
             Log.err (fun m -> m "Failed to load cookies: %s" (Printexc.to_string exn));

     

       562
       562
       +
             create ()

     

       563
       563
       +
       

     

       564
       564
       +
       let save path jar =

     

       565
       565
       +
         Eio.Mutex.lock jar.mutex;

     

       566
       566
       +
         let total_cookies =

     

       567
       567
       +
           List.length jar.original_cookies + List.length jar.delta_cookies

     

       568
       568
       +
         in

     

       569
       569
       +
         Eio.Mutex.unlock jar.mutex;

     

       570
       570
       +
         Log.info (fun m -> m "Saving %d cookies to %a" total_cookies Eio.Path.pp path);

     

       571
       571
       +
       

     

       572
       572
       +
         let content = to_mozilla_format jar in

     

       573
       573
       +
       

     

       574
       574
       +
         try

     

       575
       575
       +
           Eio.Path.save ~create:(`Or_truncate 0o600) path content;

     

       576
       576
       +
           Log.debug (fun m -> m "Cookies saved successfully")

     

       577
       577
       +
         with exn ->

     

       578
       578
       +
           Log.err (fun m -> m "Failed to save cookies: %s" (Printexc.to_string exn))

+220

lib/jar/cookeio_jar.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
         Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.

     

       3
       3
       +
         SPDX-License-Identifier: ISC

     

       4
       4
       +
        ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Cookie jar for storing and managing HTTP cookies.

     

       7
       7
       +
       

     

       8
       8
       +
           This module provides a complete cookie jar implementation following

     

       9
       9
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265} RFC 6265} while

     

       10
       10
       +
           integrating Eio for efficient asynchronous operations.

     

       11
       11
       +
       

     

       12
       12
       +
           A cookie jar maintains a collection of cookies with automatic cleanup of

     

       13
       13
       +
           expired entries. It implements the standard browser behavior for cookie

     

       14
       14
       +
           storage, including:

     

       15
       15
       +
           - Automatic removal of expired cookies

     

       16
       16
       +
           - Domain and path-based cookie retrieval per

     

       17
       17
       +
             {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.4} Section 5.4}

     

       18
       18
       +
           - Delta tracking for Set-Cookie headers

     

       19
       19
       +
           - Mozilla format persistence for cross-tool compatibility

     

       20
       20
       +
       

     

       21
       21
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265> RFC 6265 - HTTP State Management Mechanism

     

       22
       22
       +
       

     

       23
       23
       +
           {2 Standards and References}

     

       24
       24
       +
       

     

       25
       25
       +
           This cookie jar implements the storage model from:

     

       26
       26
       +
       

     

       27
       27
       +
           {ul

     

       28
       28
       +
           {- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3}RFC 6265 Section 5.3} -

     

       29
       29
       +
              Storage Model - Cookie insertion, replacement, and expiration}

     

       30
       30
       +
           {- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.4}RFC 6265 Section 5.4} -

     

       31
       31
       +
              The Cookie Header - Cookie retrieval and ordering}}

     

       32
       32
       +
       

     

       33
       33
       +
           Key RFC 6265 requirements implemented:

     

       34
       34
       +
           {ul

     

       35
       35
       +
           {- Domain matching per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3}Section 5.1.3}}

     

       36
       36
       +
           {- Path matching per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4}Section 5.1.4}}

     

       37
       37
       +
           {- Cookie ordering per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.4}Section 5.4 Step 2}}

     

       38
       38
       +
           {- Creation time preservation per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3}Section 5.3 Step 11.3}}} *)

     

       39
       39
       +
       

     

       40
       40
       +
       type t

     

       41
       41
       +
       (** Cookie jar for storing and managing cookies.

     

       42
       42
       +
       

     

       43
       43
       +
           A cookie jar maintains a collection of cookies with automatic cleanup of

     

       44
       44
       +
           expired entries and enforcement of storage limits. It implements the

     

       45
       45
       +
           standard browser behavior for cookie storage per

     

       46
       46
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3}. *)

     

       47
       47
       +
       

     

       48
       48
       +
       (** {1 Cookie Jar Creation and Loading} *)

     

       49
       49
       +
       

     

       50
       50
       +
       val create : unit -> t

     

       51
       51
       +
       (** Create an empty cookie jar. *)

     

       52
       52
       +
       

     

       53
       53
       +
       val load : clock:_ Eio.Time.clock -> Eio.Fs.dir_ty Eio.Path.t -> t

     

       54
       54
       +
       (** Load cookies from Mozilla format file.

     

       55
       55
       +
       

     

       56
       56
       +
           Loads cookies from a file in Mozilla format, using the provided clock to set

     

       57
       57
       +
           creation and last access times. Returns an empty jar if the file doesn't

     

       58
       58
       +
           exist or cannot be loaded. *)

     

       59
       59
       +
       

     

       60
       60
       +
       val save : Eio.Fs.dir_ty Eio.Path.t -> t -> unit

     

       61
       61
       +
       (** Save cookies to Mozilla format file. *)

     

       62
       62
       +
       

     

       63
       63
       +
       (** {1 Cookie Jar Management} *)

     

       64
       64
       +
       

     

       65
       65
       +
       val add_cookie : t -> Cookeio.t -> unit

     

       66
       66
       +
       (** Add a cookie to the jar.

     

       67
       67
       +
       

     

       68
       68
       +
           The cookie is added to the delta, meaning it will appear in Set-Cookie

     

       69
       69
       +
           headers when calling {!delta}. If a cookie with the same name/domain/path

     

       70
       70
       +
           exists, it will be replaced per

     

       71
       71
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3}.

     

       72
       72
       +
       

     

       73
       73
       +
           Per Section 5.3, Step 11.3, when replacing an existing cookie, the original

     

       74
       74
       +
           creation-time is preserved. This ensures stable cookie ordering per

     

       75
       75
       +
           Section 5.4, Step 2.

     

       76
       76
       +
       

     

       77
       77
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       78
       78
       +
       

     

       79
       79
       +
       val add_original : t -> Cookeio.t -> unit

     

       80
       80
       +
       (** Add an original cookie to the jar.

     

       81
       81
       +
       

     

       82
       82
       +
           Original cookies are those received from the client (via Cookie header).

     

       83
       83
       +
           They do not appear in the delta. This method should be used when loading

     

       84
       84
       +
           cookies from incoming HTTP requests.

     

       85
       85
       +
       

     

       86
       86
       +
           Per Section 5.3, Step 11.3, when replacing an existing cookie, the original

     

       87
       87
       +
           creation-time is preserved.

     

       88
       88
       +
       

     

       89
       89
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       90
       90
       +
       

     

       91
       91
       +
       val delta : t -> Cookeio.t list

     

       92
       92
       +
       (** Get cookies that need to be sent in Set-Cookie headers.

     

       93
       93
       +
       

     

       94
       94
       +
           Returns cookies that have been added via {!add_cookie} and removal cookies

     

       95
       95
       +
           for original cookies that have been removed. Does not include original

     

       96
       96
       +
           cookies that were added via {!add_original}.

     

       97
       97
       +
       

     

       98
       98
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1> RFC 6265 Section 4.1 - Set-Cookie *)

     

       99
       99
       +
       

     

       100
       100
       +
       val remove : t -> clock:_ Eio.Time.clock -> Cookeio.t -> unit

     

       101
       101
       +
       (** Remove a cookie from the jar.

     

       102
       102
       +
       

     

       103
       103
       +
           If an original cookie with the same name/domain/path exists, creates a

     

       104
       104
       +
           removal cookie (empty value, Max-Age=0, past expiration) that appears in the

     

       105
       105
       +
           delta. If only a delta cookie exists, simply removes it from the delta.

     

       106
       106
       +
       

     

       107
       107
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3},

     

       108
       108
       +
           cookies are removed by sending a Set-Cookie with an expiry date in the past.

     

       109
       109
       +
       

     

       110
       110
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model *)

     

       111
       111
       +
       

     

       112
       112
       +
       val get_cookies :

     

       113
       113
       +
         t ->

     

       114
       114
       +
         clock:_ Eio.Time.clock ->

     

       115
       115
       +
         domain:string ->

     

       116
       116
       +
         path:string ->

     

       117
       117
       +
         is_secure:bool ->

     

       118
       118
       +
         Cookeio.t list

     

       119
       119
       +
       (** Get cookies applicable for a URL.

     

       120
       120
       +
       

     

       121
       121
       +
           Implements the cookie retrieval algorithm from

     

       122
       122
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.4}RFC 6265 Section 5.4}

     

       123
       123
       +
           for generating the Cookie header.

     

       124
       124
       +
       

     

       125
       125
       +
           {3 Algorithm}

     

       126
       126
       +
       

     

       127
       127
       +
           Per RFC 6265 Section 5.4, the user agent should:

     

       128
       128
       +
           1. Filter cookies by domain matching (Section 5.1.3)

     

       129
       129
       +
           2. Filter cookies by path matching (Section 5.1.4)

     

       130
       130
       +
           3. Filter out cookies with Secure attribute when request is non-secure

     

       131
       131
       +
           4. Filter out expired cookies

     

       132
       132
       +
           5. Sort remaining cookies (longer paths first, then by creation time)

     

       133
       133
       +
           6. Update last-access-time for retrieved cookies

     

       134
       134
       +
       

     

       135
       135
       +
           This function implements all these steps, combining original and delta cookies

     

       136
       136
       +
           with delta taking precedence. Excludes:

     

       137
       137
       +
           - Removal cookies (empty value)

     

       138
       138
       +
           - Expired cookies (expiry-time in the past per Section 5.3)

     

       139
       139
       +
           - Secure cookies when [is_secure = false]

     

       140
       140
       +
       

     

       141
       141
       +
           {3 Cookie Ordering}

     

       142
       142
       +
       

     

       143
       143
       +
           Cookies are sorted per Section 5.4, Step 2:

     

       144
       144
       +
           - Cookies with longer paths are listed before cookies with shorter paths

     

       145
       145
       +
           - Among cookies with equal-length paths, cookies with earlier creation-times

     

       146
       146
       +
             are listed first

     

       147
       147
       +
       

     

       148
       148
       +
           This ordering ensures more specific cookies take precedence.

     

       149
       149
       +
       

     

       150
       150
       +
           {3 Matching Rules}

     

       151
       151
       +
       

     

       152
       152
       +
           Domain matching follows {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3} Section 5.1.3}:

     

       153
       153
       +
           - IP addresses require exact match only

     

       154
       154
       +
           - Hostnames support subdomain matching unless host-only flag is set

     

       155
       155
       +
       

     

       156
       156
       +
           Path matching follows {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4} Section 5.1.4}.

     

       157
       157
       +
       

     

       158
       158
       +
           @param t Cookie jar

     

       159
       159
       +
           @param clock Clock for updating last-access-time

     

       160
       160
       +
           @param domain Request domain

     

       161
       161
       +
           @param path Request path

     

       162
       162
       +
           @param is_secure Whether the request is over a secure channel (HTTPS)

     

       163
       163
       +
           @return List of matching cookies, sorted per RFC 6265

     

       164
       164
       +
       

     

       165
       165
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.3> RFC 6265 Section 5.3 - Storage Model (expiry)

     

       166
       166
       +
           @see <https://datatracker.ietf.org/doc/html/rfc6265#section-5.4> RFC 6265 Section 5.4 - The Cookie Header *)

     

       167
       167
       +
       

     

       168
       168
       +
       val clear : t -> unit

     

       169
       169
       +
       (** Clear all cookies. *)

     

       170
       170
       +
       

     

       171
       171
       +
       val clear_expired : t -> clock:_ Eio.Time.clock -> unit

     

       172
       172
       +
       (** Clear expired cookies.

     

       173
       173
       +
       

     

       174
       174
       +
           Removes cookies whose expiry-time is in the past per

     

       175
       175
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3}. *)

     

       176
       176
       +
       

     

       177
       177
       +
       val clear_session_cookies : t -> unit

     

       178
       178
       +
       (** Clear session cookies.

     

       179
       179
       +
       

     

       180
       180
       +
           Removes cookies that have no Expires or Max-Age attribute (session cookies).

     

       181
       181
       +
           Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3},

     

       182
       182
       +
           these cookies are normally removed when the user agent "session" ends. *)

     

       183
       183
       +
       

     

       184
       184
       +
       val count : t -> int

     

       185
       185
       +
       (** Get the number of unique cookies in the jar. *)

     

       186
       186
       +
       

     

       187
       187
       +
       val get_all_cookies : t -> Cookeio.t list

     

       188
       188
       +
       (** Get all cookies in the jar.

     

       189
       189
       +
       

     

       190
       190
       +
           Returns all cookies including expired ones (for inspection/debugging).

     

       191
       191
       +
           Use {!get_cookies} with appropriate domain/path for filtered results that

     

       192
       192
       +
           exclude expired cookies, or call {!clear_expired} first. *)

     

       193
       193
       +
       

     

       194
       194
       +
       val is_empty : t -> bool

     

       195
       195
       +
       (** Check if the jar is empty. *)

     

       196
       196
       +
       

     

       197
       197
       +
       (** {1 Pretty Printing} *)

     

       198
       198
       +
       

     

       199
       199
       +
       val pp : Format.formatter -> t -> unit

     

       200
       200
       +
       (** Pretty print a cookie jar. *)

     

       201
       201
       +
       

     

       202
       202
       +
       (** {1 Mozilla Format} *)

     

       203
       203
       +
       

     

       204
       204
       +
       val to_mozilla_format : t -> string

     

       205
       205
       +
       (** Serialize cookies in Mozilla/Netscape cookie format.

     

       206
       206
       +
       

     

       207
       207
       +
           The Mozilla format uses tab-separated fields:

     

       208
       208
       +
           {[domain \t include_subdomains \t path \t secure \t expires \t name \t value]}

     

       209
       209
       +
       

     

       210
       210
       +
           The [include_subdomains] field corresponds to the inverse of the

     

       211
       211
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} host-only-flag}

     

       212
       212
       +
           in RFC 6265. *)

     

       213
       213
       +
       

     

       214
       214
       +
       val from_mozilla_format : clock:_ Eio.Time.clock -> string -> t

     

       215
       215
       +
       (** Parse Mozilla format cookies.

     

       216
       216
       +
       

     

       217
       217
       +
           Creates a cookie jar from a string in Mozilla cookie format, using the

     

       218
       218
       +
           provided clock to set creation and last access times. The [include_subdomains]

     

       219
       219
       +
           field is mapped to the host-only-flag per

     

       220
       220
       +
           {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.3} RFC 6265 Section 5.3}. *)

lib/jar/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name cookeio_jar)

     

       3
       3
       +
        (public_name cookeio.jar)

     

       4
       4
       +
        (libraries cookeio eio logs ptime unix ipaddr))

+2075

spec/rfc6265.txt

···

       1
       1
       +
       

     

       2
       2
       +
       

     

       3
       3
       +
       

     

       4
       4
       +
       

     

       5
       5
       +
       

     

       6
       6
       +
       

     

       7
       7
       +
       Internet Engineering Task Force (IETF)                          A. Barth

     

       8
       8
       +
       Request for Comments: 6265                                 U.C. Berkeley

     

       9
       9
       +
       Obsoletes: 2965                                               April 2011

     

       10
       10
       +
       Category: Standards Track

     

       11
       11
       +
       ISSN: 2070-1721

     

       12
       12
       +
       

     

       13
       13
       +
       

     

       14
       14
       +
                           HTTP State Management Mechanism

     

       15
       15
       +
       

     

       16
       16
       +
       Abstract

     

       17
       17
       +
       

     

       18
       18
       +
          This document defines the HTTP Cookie and Set-Cookie header fields.

     

       19
       19
       +
          These header fields can be used by HTTP servers to store state

     

       20
       20
       +
          (called cookies) at HTTP user agents, letting the servers maintain a

     

       21
       21
       +
          stateful session over the mostly stateless HTTP protocol.  Although

     

       22
       22
       +
          cookies have many historical infelicities that degrade their security

     

       23
       23
       +
          and privacy, the Cookie and Set-Cookie header fields are widely used

     

       24
       24
       +
          on the Internet.  This document obsoletes RFC 2965.

     

       25
       25
       +
       

     

       26
       26
       +
       Status of This Memo

     

       27
       27
       +
       

     

       28
       28
       +
          This is an Internet Standards Track document.

     

       29
       29
       +
       

     

       30
       30
       +
          This document is a product of the Internet Engineering Task Force

     

       31
       31
       +
          (IETF).  It represents the consensus of the IETF community.  It has

     

       32
       32
       +
          received public review and has been approved for publication by the

     

       33
       33
       +
          Internet Engineering Steering Group (IESG).  Further information on

     

       34
       34
       +
          Internet Standards is available in Section 2 of RFC 5741.

     

       35
       35
       +
       

     

       36
       36
       +
          Information about the current status of this document, any errata,

     

       37
       37
       +
          and how to provide feedback on it may be obtained at

     

       38
       38
       +
          http://www.rfc-editor.org/info/rfc6265.

     

       39
       39
       +
       

     

       40
       40
       +
       Copyright Notice

     

       41
       41
       +
       

     

       42
       42
       +
          Copyright (c) 2011 IETF Trust and the persons identified as the

     

       43
       43
       +
          document authors.  All rights reserved.

     

       44
       44
       +
       

     

       45
       45
       +
          This document is subject to BCP 78 and the IETF Trust's Legal

     

       46
       46
       +
          Provisions Relating to IETF Documents

     

       47
       47
       +
          (http://trustee.ietf.org/license-info) in effect on the date of

     

       48
       48
       +
          publication of this document.  Please review these documents

     

       49
       49
       +
          carefully, as they describe your rights and restrictions with respect

     

       50
       50
       +
          to this document.  Code Components extracted from this document must

     

       51
       51
       +
          include Simplified BSD License text as described in Section 4.e of

     

       52
       52
       +
          the Trust Legal Provisions and are provided without warranty as

     

       53
       53
       +
          described in the Simplified BSD License.

     

       54
       54
       +
       

     

       55
       55
       +
       

     

       56
       56
       +
       

     

       57
       57
       +
       

     

       58
       58
       +
       Barth                        Standards Track                    [Page 1]

     

       59
       59
       +
       

     

       60
       60
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       61
       61
       +
       

     

       62
       62
       +
       

     

       63
       63
       +
          This document may contain material from IETF Documents or IETF

     

       64
       64
       +
          Contributions published or made publicly available before November

     

       65
       65
       +
          10, 2008.  The person(s) controlling the copyright in some of this

     

       66
       66
       +
          material may not have granted the IETF Trust the right to allow

     

       67
       67
       +
          modifications of such material outside the IETF Standards Process.

     

       68
       68
       +
          Without obtaining an adequate license from the person(s) controlling

     

       69
       69
       +
          the copyright in such materials, this document may not be modified

     

       70
       70
       +
          outside the IETF Standards Process, and derivative works of it may

     

       71
       71
       +
          not be created outside the IETF Standards Process, except to format

     

       72
       72
       +
          it for publication as an RFC or to translate it into languages other

     

       73
       73
       +
          than English.

     

       74
       74
       +
       

     

       75
       75
       +
       Table of Contents

     

       76
       76
       +
       

     

       77
       77
       +
          1. Introduction ....................................................3

     

       78
       78
       +
          2. Conventions .....................................................4

     

       79
       79
       +
             2.1. Conformance Criteria .......................................4

     

       80
       80
       +
             2.2. Syntax Notation ............................................5

     

       81
       81
       +
             2.3. Terminology ................................................5

     

       82
       82
       +
          3. Overview ........................................................6

     

       83
       83
       +
             3.1. Examples ...................................................6

     

       84
       84
       +
          4. Server Requirements .............................................8

     

       85
       85
       +
             4.1. Set-Cookie .................................................8

     

       86
       86
       +
                  4.1.1. Syntax ..............................................8

     

       87
       87
       +
                  4.1.2. Semantics (Non-Normative) ..........................10

     

       88
       88
       +
             4.2. Cookie ....................................................13

     

       89
       89
       +
                  4.2.1. Syntax .............................................13

     

       90
       90
       +
                  4.2.2. Semantics ..........................................13

     

       91
       91
       +
          5. User Agent Requirements ........................................14

     

       92
       92
       +
             5.1. Subcomponent Algorithms ...................................14

     

       93
       93
       +
                  5.1.1. Dates ..............................................14

     

       94
       94
       +
                  5.1.2. Canonicalized Host Names ...........................16

     

       95
       95
       +
                  5.1.3. Domain Matching ....................................16

     

       96
       96
       +
                  5.1.4. Paths and Path-Match ...............................16

     

       97
       97
       +
             5.2. The Set-Cookie Header .....................................17

     

       98
       98
       +
                  5.2.1. The Expires Attribute ..............................19

     

       99
       99
       +
                  5.2.2. The Max-Age Attribute ..............................20

     

       100
       100
       +
                  5.2.3. The Domain Attribute ...............................20

     

       101
       101
       +
                  5.2.4. The Path Attribute .................................21

     

       102
       102
       +
                  5.2.5. The Secure Attribute ...............................21

     

       103
       103
       +
                  5.2.6. The HttpOnly Attribute .............................21

     

       104
       104
       +
             5.3. Storage Model .............................................21

     

       105
       105
       +
             5.4. The Cookie Header .........................................25

     

       106
       106
       +
          6. Implementation Considerations ..................................27

     

       107
       107
       +
             6.1. Limits ....................................................27

     

       108
       108
       +
             6.2. Application Programming Interfaces ........................27

     

       109
       109
       +
             6.3. IDNA Dependency and Migration .............................27

     

       110
       110
       +
          7. Privacy Considerations .........................................28

     

       111
       111
       +
       

     

       112
       112
       +
       

     

       113
       113
       +
       

     

       114
       114
       +
       Barth                        Standards Track                    [Page 2]

     

       115
       115
       +
       

     

       116
       116
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       117
       117
       +
       

     

       118
       118
       +
       

     

       119
       119
       +
             7.1. Third-Party Cookies .......................................28

     

       120
       120
       +
             7.2. User Controls .............................................28

     

       121
       121
       +
             7.3. Expiration Dates ..........................................29

     

       122
       122
       +
          8. Security Considerations ........................................29

     

       123
       123
       +
             8.1. Overview ..................................................29

     

       124
       124
       +
             8.2. Ambient Authority .........................................30

     

       125
       125
       +
             8.3. Clear Text ................................................30

     

       126
       126
       +
             8.4. Session Identifiers .......................................31

     

       127
       127
       +
             8.5. Weak Confidentiality ......................................32

     

       128
       128
       +
             8.6. Weak Integrity ............................................32

     

       129
       129
       +
             8.7. Reliance on DNS ...........................................33

     

       130
       130
       +
          9. IANA Considerations ............................................33

     

       131
       131
       +
             9.1. Cookie ....................................................34

     

       132
       132
       +
             9.2. Set-Cookie ................................................34

     

       133
       133
       +
             9.3. Cookie2 ...................................................34

     

       134
       134
       +
             9.4. Set-Cookie2 ...............................................34

     

       135
       135
       +
          10. References ....................................................35

     

       136
       136
       +
             10.1. Normative References .....................................35

     

       137
       137
       +
             10.2. Informative References ...................................35

     

       138
       138
       +
          Appendix A. Acknowledgements ......................................37

     

       139
       139
       +
       

     

       140
       140
       +
       1.  Introduction

     

       141
       141
       +
       

     

       142
       142
       +
          This document defines the HTTP Cookie and Set-Cookie header fields.

     

       143
       143
       +
          Using the Set-Cookie header field, an HTTP server can pass name/value

     

       144
       144
       +
          pairs and associated metadata (called cookies) to a user agent.  When

     

       145
       145
       +
          the user agent makes subsequent requests to the server, the user

     

       146
       146
       +
          agent uses the metadata and other information to determine whether to

     

       147
       147
       +
          return the name/value pairs in the Cookie header.

     

       148
       148
       +
       

     

       149
       149
       +
          Although simple on their surface, cookies have a number of

     

       150
       150
       +
          complexities.  For example, the server indicates a scope for each

     

       151
       151
       +
          cookie when sending it to the user agent.  The scope indicates the

     

       152
       152
       +
          maximum amount of time in which the user agent should return the

     

       153
       153
       +
          cookie, the servers to which the user agent should return the cookie,

     

       154
       154
       +
          and the URI schemes for which the cookie is applicable.

     

       155
       155
       +
       

     

       156
       156
       +
          For historical reasons, cookies contain a number of security and

     

       157
       157
       +
          privacy infelicities.  For example, a server can indicate that a

     

       158
       158
       +
          given cookie is intended for "secure" connections, but the Secure

     

       159
       159
       +
          attribute does not provide integrity in the presence of an active

     

       160
       160
       +
          network attacker.  Similarly, cookies for a given host are shared

     

       161
       161
       +
          across all the ports on that host, even though the usual "same-origin

     

       162
       162
       +
          policy" used by web browsers isolates content retrieved via different

     

       163
       163
       +
          ports.

     

       164
       164
       +
       

     

       165
       165
       +
          There are two audiences for this specification: developers of cookie-

     

       166
       166
       +
          generating servers and developers of cookie-consuming user agents.

     

       167
       167
       +
       

     

       168
       168
       +
       

     

       169
       169
       +
       

     

       170
       170
       +
       Barth                        Standards Track                    [Page 3]

     

       171
       171
       +
       

     

       172
       172
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       173
       173
       +
       

     

       174
       174
       +
       

     

       175
       175
       +
          To maximize interoperability with user agents, servers SHOULD limit

     

       176
       176
       +
          themselves to the well-behaved profile defined in Section 4 when

     

       177
       177
       +
          generating cookies.

     

       178
       178
       +
       

     

       179
       179
       +
          User agents MUST implement the more liberal processing rules defined

     

       180
       180
       +
          in Section 5, in order to maximize interoperability with existing

     

       181
       181
       +
          servers that do not conform to the well-behaved profile defined in

     

       182
       182
       +
          Section 4.

     

       183
       183
       +
       

     

       184
       184
       +
          This document specifies the syntax and semantics of these headers as

     

       185
       185
       +
          they are actually used on the Internet.  In particular, this document

     

       186
       186
       +
          does not create new syntax or semantics beyond those in use today.

     

       187
       187
       +
          The recommendations for cookie generation provided in Section 4

     

       188
       188
       +
          represent a preferred subset of current server behavior, and even the

     

       189
       189
       +
          more liberal cookie processing algorithm provided in Section 5 does

     

       190
       190
       +
          not recommend all of the syntactic and semantic variations in use

     

       191
       191
       +
          today.  Where some existing software differs from the recommended

     

       192
       192
       +
          protocol in significant ways, the document contains a note explaining

     

       193
       193
       +
          the difference.

     

       194
       194
       +
       

     

       195
       195
       +
          Prior to this document, there were at least three descriptions of

     

       196
       196
       +
          cookies: the so-called "Netscape cookie specification" [Netscape],

     

       197
       197
       +
          RFC 2109 [RFC2109], and RFC 2965 [RFC2965].  However, none of these

     

       198
       198
       +
          documents describe how the Cookie and Set-Cookie headers are actually

     

       199
       199
       +
          used on the Internet (see [Kri2001] for historical context).  In

     

       200
       200
       +
          relation to previous IETF specifications of HTTP state management

     

       201
       201
       +
          mechanisms, this document requests the following actions:

     

       202
       202
       +
       

     

       203
       203
       +
          1.  Change the status of [RFC2109] to Historic (it has already been

     

       204
       204
       +
              obsoleted by [RFC2965]).

     

       205
       205
       +
       

     

       206
       206
       +
          2.  Change the status of [RFC2965] to Historic.

     

       207
       207
       +
       

     

       208
       208
       +
          3.  Indicate that [RFC2965] has been obsoleted by this document.

     

       209
       209
       +
       

     

       210
       210
       +
          In particular, in moving RFC 2965 to Historic and obsoleting it, this

     

       211
       211
       +
          document deprecates the use of the Cookie2 and Set-Cookie2 header

     

       212
       212
       +
          fields.

     

       213
       213
       +
       

     

       214
       214
       +
       2.  Conventions

     

       215
       215
       +
       

     

       216
       216
       +
       2.1.  Conformance Criteria

     

       217
       217
       +
       

     

       218
       218
       +
          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

     

       219
       219
       +
          "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this

     

       220
       220
       +
          document are to be interpreted as described in [RFC2119].

     

       221
       221
       +
       

     

       222
       222
       +
       

     

       223
       223
       +
       

     

       224
       224
       +
       

     

       225
       225
       +
       

     

       226
       226
       +
       Barth                        Standards Track                    [Page 4]

     

       227
       227
       +
       

     

       228
       228
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       229
       229
       +
       

     

       230
       230
       +
       

     

       231
       231
       +
          Requirements phrased in the imperative as part of algorithms (such as

     

       232
       232
       +
          "strip any leading space characters" or "return false and abort these

     

       233
       233
       +
          steps") are to be interpreted with the meaning of the key word

     

       234
       234
       +
          ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm.

     

       235
       235
       +
       

     

       236
       236
       +
          Conformance requirements phrased as algorithms or specific steps can

     

       237
       237
       +
          be implemented in any manner, so long as the end result is

     

       238
       238
       +
          equivalent.  In particular, the algorithms defined in this

     

       239
       239
       +
          specification are intended to be easy to understand and are not

     

       240
       240
       +
          intended to be performant.

     

       241
       241
       +
       

     

       242
       242
       +
       2.2.  Syntax Notation

     

       243
       243
       +
       

     

       244
       244
       +
          This specification uses the Augmented Backus-Naur Form (ABNF)

     

       245
       245
       +
          notation of [RFC5234].

     

       246
       246
       +
       

     

       247
       247
       +
          The following core rules are included by reference, as defined in

     

       248
       248
       +
          [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF

     

       249
       249
       +
          (CR LF), CTLs (controls), DIGIT (decimal 0-9), DQUOTE (double quote),

     

       250
       250
       +
          HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), NUL (null octet),

     

       251
       251
       +
          OCTET (any 8-bit sequence of data except NUL), SP (space), HTAB

     

       252
       252
       +
          (horizontal tab), CHAR (any [USASCII] character), VCHAR (any visible

     

       253
       253
       +
          [USASCII] character), and WSP (whitespace).

     

       254
       254
       +
       

     

       255
       255
       +
          The OWS (optional whitespace) rule is used where zero or more linear

     

       256
       256
       +
          whitespace characters MAY appear:

     

       257
       257
       +
       

     

       258
       258
       +
          OWS            = *( [ obs-fold ] WSP )

     

       259
       259
       +
                           ; "optional" whitespace

     

       260
       260
       +
          obs-fold       = CRLF

     

       261
       261
       +
       

     

       262
       262
       +
          OWS SHOULD either not be produced or be produced as a single SP

     

       263
       263
       +
          character.

     

       264
       264
       +
       

     

       265
       265
       +
       2.3.  Terminology

     

       266
       266
       +
       

     

       267
       267
       +
          The terms user agent, client, server, proxy, and origin server have

     

       268
       268
       +
          the same meaning as in the HTTP/1.1 specification ([RFC2616], Section

     

       269
       269
       +
          1.3).

     

       270
       270
       +
       

     

       271
       271
       +
          The request-host is the name of the host, as known by the user agent,

     

       272
       272
       +
          to which the user agent is sending an HTTP request or from which it

     

       273
       273
       +
          is receiving an HTTP response (i.e., the name of the host to which it

     

       274
       274
       +
          sent the corresponding HTTP request).

     

       275
       275
       +
       

     

       276
       276
       +
          The term request-uri is defined in Section 5.1.2 of [RFC2616].

     

       277
       277
       +
       

     

       278
       278
       +
       

     

       279
       279
       +
       

     

       280
       280
       +
       

     

       281
       281
       +
       

     

       282
       282
       +
       Barth                        Standards Track                    [Page 5]

     

       283
       283
       +
       

     

       284
       284
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       285
       285
       +
       

     

       286
       286
       +
       

     

       287
       287
       +
          Two sequences of octets are said to case-insensitively match each

     

       288
       288
       +
          other if and only if they are equivalent under the i;ascii-casemap

     

       289
       289
       +
          collation defined in [RFC4790].

     

       290
       290
       +
       

     

       291
       291
       +
          The term string means a sequence of non-NUL octets.

     

       292
       292
       +
       

     

       293
       293
       +
       3.  Overview

     

       294
       294
       +
       

     

       295
       295
       +
          This section outlines a way for an origin server to send state

     

       296
       296
       +
          information to a user agent and for the user agent to return the

     

       297
       297
       +
          state information to the origin server.

     

       298
       298
       +
       

     

       299
       299
       +
          To store state, the origin server includes a Set-Cookie header in an

     

       300
       300
       +
          HTTP response.  In subsequent requests, the user agent returns a

     

       301
       301
       +
          Cookie request header to the origin server.  The Cookie header

     

       302
       302
       +
          contains cookies the user agent received in previous Set-Cookie

     

       303
       303
       +
          headers.  The origin server is free to ignore the Cookie header or

     

       304
       304
       +
          use its contents for an application-defined purpose.

     

       305
       305
       +
       

     

       306
       306
       +
          Origin servers MAY send a Set-Cookie response header with any

     

       307
       307
       +
          response.  User agents MAY ignore Set-Cookie headers contained in

     

       308
       308
       +
          responses with 100-level status codes but MUST process Set-Cookie

     

       309
       309
       +
          headers contained in other responses (including responses with 400-

     

       310
       310
       +
          and 500-level status codes).  An origin server can include multiple

     

       311
       311
       +
          Set-Cookie header fields in a single response.  The presence of a

     

       312
       312
       +
          Cookie or a Set-Cookie header field does not preclude HTTP caches

     

       313
       313
       +
          from storing and reusing a response.

     

       314
       314
       +
       

     

       315
       315
       +
          Origin servers SHOULD NOT fold multiple Set-Cookie header fields into

     

       316
       316
       +
          a single header field.  The usual mechanism for folding HTTP headers

     

       317
       317
       +
          fields (i.e., as defined in [RFC2616]) might change the semantics of

     

       318
       318
       +
          the Set-Cookie header field because the %x2C (",") character is used

     

       319
       319
       +
          by Set-Cookie in a way that conflicts with such folding.

     

       320
       320
       +
       

     

       321
       321
       +
       3.1.  Examples

     

       322
       322
       +
       

     

       323
       323
       +
          Using the Set-Cookie header, a server can send the user agent a short

     

       324
       324
       +
          string in an HTTP response that the user agent will return in future

     

       325
       325
       +
          HTTP requests that are within the scope of the cookie.  For example,

     

       326
       326
       +
          the server can send the user agent a "session identifier" named SID

     

       327
       327
       +
          with the value 31d4d96e407aad42.  The user agent then returns the

     

       328
       328
       +
          session identifier in subsequent requests.

     

       329
       329
       +
       

     

       330
       330
       +
       

     

       331
       331
       +
       

     

       332
       332
       +
       

     

       333
       333
       +
       

     

       334
       334
       +
       

     

       335
       335
       +
       

     

       336
       336
       +
       

     

       337
       337
       +
       

     

       338
       338
       +
       Barth                        Standards Track                    [Page 6]

     

       339
       339
       +
       

     

       340
       340
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       341
       341
       +
       

     

       342
       342
       +
       

     

       343
       343
       +
          == Server -> User Agent ==

     

       344
       344
       +
       

     

       345
       345
       +
          Set-Cookie: SID=31d4d96e407aad42

     

       346
       346
       +
       

     

       347
       347
       +
          == User Agent -> Server ==

     

       348
       348
       +
       

     

       349
       349
       +
          Cookie: SID=31d4d96e407aad42

     

       350
       350
       +
       

     

       351
       351
       +
          The server can alter the default scope of the cookie using the Path

     

       352
       352
       +
          and Domain attributes.  For example, the server can instruct the user

     

       353
       353
       +
          agent to return the cookie to every path and every subdomain of

     

       354
       354
       +
          example.com.

     

       355
       355
       +
       

     

       356
       356
       +
          == Server -> User Agent ==

     

       357
       357
       +
       

     

       358
       358
       +
          Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com

     

       359
       359
       +
       

     

       360
       360
       +
          == User Agent -> Server ==

     

       361
       361
       +
       

     

       362
       362
       +
          Cookie: SID=31d4d96e407aad42

     

       363
       363
       +
       

     

       364
       364
       +
          As shown in the next example, the server can store multiple cookies

     

       365
       365
       +
          at the user agent.  For example, the server can store a session

     

       366
       366
       +
          identifier as well as the user's preferred language by returning two

     

       367
       367
       +
          Set-Cookie header fields.  Notice that the server uses the Secure and

     

       368
       368
       +
          HttpOnly attributes to provide additional security protections for

     

       369
       369
       +
          the more sensitive session identifier (see Section 4.1.2.)

     

       370
       370
       +
       

     

       371
       371
       +
          == Server -> User Agent ==

     

       372
       372
       +
       

     

       373
       373
       +
          Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly

     

       374
       374
       +
          Set-Cookie: lang=en-US; Path=/; Domain=example.com

     

       375
       375
       +
       

     

       376
       376
       +
          == User Agent -> Server ==

     

       377
       377
       +
       

     

       378
       378
       +
          Cookie: SID=31d4d96e407aad42; lang=en-US

     

       379
       379
       +
       

     

       380
       380
       +
          Notice that the Cookie header above contains two cookies, one named

     

       381
       381
       +
          SID and one named lang.  If the server wishes the user agent to

     

       382
       382
       +
          persist the cookie over multiple "sessions" (e.g., user agent

     

       383
       383
       +
          restarts), the server can specify an expiration date in the Expires

     

       384
       384
       +
          attribute.  Note that the user agent might delete the cookie before

     

       385
       385
       +
          the expiration date if the user agent's cookie store exceeds its

     

       386
       386
       +
          quota or if the user manually deletes the server's cookie.

     

       387
       387
       +
       

     

       388
       388
       +
       

     

       389
       389
       +
       

     

       390
       390
       +
       

     

       391
       391
       +
       

     

       392
       392
       +
       

     

       393
       393
       +
       

     

       394
       394
       +
       Barth                        Standards Track                    [Page 7]

     

       395
       395
       +
       

     

       396
       396
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       397
       397
       +
       

     

       398
       398
       +
       

     

       399
       399
       +
          == Server -> User Agent ==

     

       400
       400
       +
       

     

       401
       401
       +
          Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT

     

       402
       402
       +
       

     

       403
       403
       +
          == User Agent -> Server ==

     

       404
       404
       +
       

     

       405
       405
       +
          Cookie: SID=31d4d96e407aad42; lang=en-US

     

       406
       406
       +
       

     

       407
       407
       +
          Finally, to remove a cookie, the server returns a Set-Cookie header

     

       408
       408
       +
          with an expiration date in the past.  The server will be successful

     

       409
       409
       +
          in removing the cookie only if the Path and the Domain attribute in

     

       410
       410
       +
          the Set-Cookie header match the values used when the cookie was

     

       411
       411
       +
          created.

     

       412
       412
       +
       

     

       413
       413
       +
          == Server -> User Agent ==

     

       414
       414
       +
       

     

       415
       415
       +
          Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT

     

       416
       416
       +
       

     

       417
       417
       +
          == User Agent -> Server ==

     

       418
       418
       +
       

     

       419
       419
       +
          Cookie: SID=31d4d96e407aad42

     

       420
       420
       +
       

     

       421
       421
       +
       4.  Server Requirements

     

       422
       422
       +
       

     

       423
       423
       +
          This section describes the syntax and semantics of a well-behaved

     

       424
       424
       +
          profile of the Cookie and Set-Cookie headers.

     

       425
       425
       +
       

     

       426
       426
       +
       4.1.  Set-Cookie

     

       427
       427
       +
       

     

       428
       428
       +
          The Set-Cookie HTTP response header is used to send cookies from the

     

       429
       429
       +
          server to the user agent.

     

       430
       430
       +
       

     

       431
       431
       +
       4.1.1.  Syntax

     

       432
       432
       +
       

     

       433
       433
       +
          Informally, the Set-Cookie response header contains the header name

     

       434
       434
       +
          "Set-Cookie" followed by a ":" and a cookie.  Each cookie begins with

     

       435
       435
       +
          a name-value-pair, followed by zero or more attribute-value pairs.

     

       436
       436
       +
          Servers SHOULD NOT send Set-Cookie headers that fail to conform to

     

       437
       437
       +
          the following grammar:

     

       438
       438
       +
       

     

       439
       439
       +
       

     

       440
       440
       +
       

     

       441
       441
       +
       

     

       442
       442
       +
       

     

       443
       443
       +
       

     

       444
       444
       +
       

     

       445
       445
       +
       

     

       446
       446
       +
       

     

       447
       447
       +
       

     

       448
       448
       +
       

     

       449
       449
       +
       

     

       450
       450
       +
       Barth                        Standards Track                    [Page 8]

     

       451
       451
       +
       

     

       452
       452
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       453
       453
       +
       

     

       454
       454
       +
       

     

       455
       455
       +
        set-cookie-header = "Set-Cookie:" SP set-cookie-string

     

       456
       456
       +
        set-cookie-string = cookie-pair *( ";" SP cookie-av )

     

       457
       457
       +
        cookie-pair       = cookie-name "=" cookie-value

     

       458
       458
       +
        cookie-name       = token

     

       459
       459
       +
        cookie-value      = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )

     

       460
       460
       +
        cookie-octet      = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E

     

       461
       461
       +
                              ; US-ASCII characters excluding CTLs,

     

       462
       462
       +
                              ; whitespace DQUOTE, comma, semicolon,

     

       463
       463
       +
                              ; and backslash

     

       464
       464
       +
        token             = <token, defined in [RFC2616], Section 2.2>

     

       465
       465
       +
       

     

       466
       466
       +
        cookie-av         = expires-av / max-age-av / domain-av /

     

       467
       467
       +
                            path-av / secure-av / httponly-av /

     

       468
       468
       +
                            extension-av

     

       469
       469
       +
        expires-av        = "Expires=" sane-cookie-date

     

       470
       470
       +
        sane-cookie-date  = <rfc1123-date, defined in [RFC2616], Section 3.3.1>

     

       471
       471
       +
        max-age-av        = "Max-Age=" non-zero-digit *DIGIT

     

       472
       472
       +
                              ; In practice, both expires-av and max-age-av

     

       473
       473
       +
                              ; are limited to dates representable by the

     

       474
       474
       +
                              ; user agent.

     

       475
       475
       +
        non-zero-digit    = %x31-39

     

       476
       476
       +
                              ; digits 1 through 9

     

       477
       477
       +
        domain-av         = "Domain=" domain-value

     

       478
       478
       +
        domain-value      = <subdomain>

     

       479
       479
       +
                              ; defined in [RFC1034], Section 3.5, as

     

       480
       480
       +
                              ; enhanced by [RFC1123], Section 2.1

     

       481
       481
       +
        path-av           = "Path=" path-value

     

       482
       482
       +
        path-value        = <any CHAR except CTLs or ";">

     

       483
       483
       +
        secure-av         = "Secure"

     

       484
       484
       +
        httponly-av       = "HttpOnly"

     

       485
       485
       +
        extension-av      = <any CHAR except CTLs or ";">

     

       486
       486
       +
       

     

       487
       487
       +
          Note that some of the grammatical terms above reference documents

     

       488
       488
       +
          that use different grammatical notations than this document (which

     

       489
       489
       +
          uses ABNF from [RFC5234]).

     

       490
       490
       +
       

     

       491
       491
       +
          The semantics of the cookie-value are not defined by this document.

     

       492
       492
       +
       

     

       493
       493
       +
          To maximize compatibility with user agents, servers that wish to

     

       494
       494
       +
          store arbitrary data in a cookie-value SHOULD encode that data, for

     

       495
       495
       +
          example, using Base64 [RFC4648].

     

       496
       496
       +
       

     

       497
       497
       +
          The portions of the set-cookie-string produced by the cookie-av term

     

       498
       498
       +
          are known as attributes.  To maximize compatibility with user agents,

     

       499
       499
       +
          servers SHOULD NOT produce two attributes with the same name in the

     

       500
       500
       +
          same set-cookie-string.  (See Section 5.3 for how user agents handle

     

       501
       501
       +
          this case.)

     

       502
       502
       +
       

     

       503
       503
       +
       

     

       504
       504
       +
       

     

       505
       505
       +
       

     

       506
       506
       +
       Barth                        Standards Track                    [Page 9]

     

       507
       507
       +
       

     

       508
       508
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       509
       509
       +
       

     

       510
       510
       +
       

     

       511
       511
       +
          Servers SHOULD NOT include more than one Set-Cookie header field in

     

       512
       512
       +
          the same response with the same cookie-name.  (See Section 5.2 for

     

       513
       513
       +
          how user agents handle this case.)

     

       514
       514
       +
       

     

       515
       515
       +
          If a server sends multiple responses containing Set-Cookie headers

     

       516
       516
       +
          concurrently to the user agent (e.g., when communicating with the

     

       517
       517
       +
          user agent over multiple sockets), these responses create a "race

     

       518
       518
       +
          condition" that can lead to unpredictable behavior.

     

       519
       519
       +
       

     

       520
       520
       +
          NOTE: Some existing user agents differ in their interpretation of

     

       521
       521
       +
          two-digit years.  To avoid compatibility issues, servers SHOULD use

     

       522
       522
       +
          the rfc1123-date format, which requires a four-digit year.

     

       523
       523
       +
       

     

       524
       524
       +
          NOTE: Some user agents store and process dates in cookies as 32-bit

     

       525
       525
       +
          UNIX time_t values.  Implementation bugs in the libraries supporting

     

       526
       526
       +
          time_t processing on some systems might cause such user agents to

     

       527
       527
       +
          process dates after the year 2038 incorrectly.

     

       528
       528
       +
       

     

       529
       529
       +
       4.1.2.  Semantics (Non-Normative)

     

       530
       530
       +
       

     

       531
       531
       +
          This section describes simplified semantics of the Set-Cookie header.

     

       532
       532
       +
          These semantics are detailed enough to be useful for understanding

     

       533
       533
       +
          the most common uses of cookies by servers.  The full semantics are

     

       534
       534
       +
          described in Section 5.

     

       535
       535
       +
       

     

       536
       536
       +
          When the user agent receives a Set-Cookie header, the user agent

     

       537
       537
       +
          stores the cookie together with its attributes.  Subsequently, when

     

       538
       538
       +
          the user agent makes an HTTP request, the user agent includes the

     

       539
       539
       +
          applicable, non-expired cookies in the Cookie header.

     

       540
       540
       +
       

     

       541
       541
       +
          If the user agent receives a new cookie with the same cookie-name,

     

       542
       542
       +
          domain-value, and path-value as a cookie that it has already stored,

     

       543
       543
       +
          the existing cookie is evicted and replaced with the new cookie.

     

       544
       544
       +
          Notice that servers can delete cookies by sending the user agent a

     

       545
       545
       +
          new cookie with an Expires attribute with a value in the past.

     

       546
       546
       +
       

     

       547
       547
       +
          Unless the cookie's attributes indicate otherwise, the cookie is

     

       548
       548
       +
          returned only to the origin server (and not, for example, to any

     

       549
       549
       +
          subdomains), and it expires at the end of the current session (as

     

       550
       550
       +
          defined by the user agent).  User agents ignore unrecognized cookie

     

       551
       551
       +
          attributes (but not the entire cookie).

     

       552
       552
       +
       

     

       553
       553
       +
       

     

       554
       554
       +
       

     

       555
       555
       +
       

     

       556
       556
       +
       

     

       557
       557
       +
       

     

       558
       558
       +
       

     

       559
       559
       +
       

     

       560
       560
       +
       

     

       561
       561
       +
       

     

       562
       562
       +
       Barth                        Standards Track                   [Page 10]

     

       563
       563
       +
       

     

       564
       564
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       565
       565
       +
       

     

       566
       566
       +
       

     

       567
       567
       +
       4.1.2.1.  The Expires Attribute

     

       568
       568
       +
       

     

       569
       569
       +
          The Expires attribute indicates the maximum lifetime of the cookie,

     

       570
       570
       +
          represented as the date and time at which the cookie expires.  The

     

       571
       571
       +
          user agent is not required to retain the cookie until the specified

     

       572
       572
       +
          date has passed.  In fact, user agents often evict cookies due to

     

       573
       573
       +
          memory pressure or privacy concerns.

     

       574
       574
       +
       

     

       575
       575
       +
       4.1.2.2.  The Max-Age Attribute

     

       576
       576
       +
       

     

       577
       577
       +
          The Max-Age attribute indicates the maximum lifetime of the cookie,

     

       578
       578
       +
          represented as the number of seconds until the cookie expires.  The

     

       579
       579
       +
          user agent is not required to retain the cookie for the specified

     

       580
       580
       +
          duration.  In fact, user agents often evict cookies due to memory

     

       581
       581
       +
          pressure or privacy concerns.

     

       582
       582
       +
       

     

       583
       583
       +
             NOTE: Some existing user agents do not support the Max-Age

     

       584
       584
       +
             attribute.  User agents that do not support the Max-Age attribute

     

       585
       585
       +
             ignore the attribute.

     

       586
       586
       +
       

     

       587
       587
       +
          If a cookie has both the Max-Age and the Expires attribute, the Max-

     

       588
       588
       +
          Age attribute has precedence and controls the expiration date of the

     

       589
       589
       +
          cookie.  If a cookie has neither the Max-Age nor the Expires

     

       590
       590
       +
          attribute, the user agent will retain the cookie until "the current

     

       591
       591
       +
          session is over" (as defined by the user agent).

     

       592
       592
       +
       

     

       593
       593
       +
       4.1.2.3.  The Domain Attribute

     

       594
       594
       +
       

     

       595
       595
       +
          The Domain attribute specifies those hosts to which the cookie will

     

       596
       596
       +
          be sent.  For example, if the value of the Domain attribute is

     

       597
       597
       +
          "example.com", the user agent will include the cookie in the Cookie

     

       598
       598
       +
          header when making HTTP requests to example.com, www.example.com, and

     

       599
       599
       +
          www.corp.example.com.  (Note that a leading %x2E ("."), if present,

     

       600
       600
       +
          is ignored even though that character is not permitted, but a

     

       601
       601
       +
          trailing %x2E ("."), if present, will cause the user agent to ignore

     

       602
       602
       +
          the attribute.)  If the server omits the Domain attribute, the user

     

       603
       603
       +
          agent will return the cookie only to the origin server.

     

       604
       604
       +
       

     

       605
       605
       +
             WARNING: Some existing user agents treat an absent Domain

     

       606
       606
       +
             attribute as if the Domain attribute were present and contained

     

       607
       607
       +
             the current host name.  For example, if example.com returns a Set-

     

       608
       608
       +
             Cookie header without a Domain attribute, these user agents will

     

       609
       609
       +
             erroneously send the cookie to www.example.com as well.

     

       610
       610
       +
       

     

       611
       611
       +
       

     

       612
       612
       +
       

     

       613
       613
       +
       

     

       614
       614
       +
       

     

       615
       615
       +
       

     

       616
       616
       +
       

     

       617
       617
       +
       

     

       618
       618
       +
       Barth                        Standards Track                   [Page 11]

     

       619
       619
       +
       

     

       620
       620
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       621
       621
       +
       

     

       622
       622
       +
       

     

       623
       623
       +
          The user agent will reject cookies unless the Domain attribute

     

       624
       624
       +
          specifies a scope for the cookie that would include the origin

     

       625
       625
       +
          server.  For example, the user agent will accept a cookie with a

     

       626
       626
       +
          Domain attribute of "example.com" or of "foo.example.com" from

     

       627
       627
       +
          foo.example.com, but the user agent will not accept a cookie with a

     

       628
       628
       +
          Domain attribute of "bar.example.com" or of "baz.foo.example.com".

     

       629
       629
       +
       

     

       630
       630
       +
          NOTE: For security reasons, many user agents are configured to reject

     

       631
       631
       +
          Domain attributes that correspond to "public suffixes".  For example,

     

       632
       632
       +
          some user agents will reject Domain attributes of "com" or "co.uk".

     

       633
       633
       +
          (See Section 5.3 for more information.)

     

       634
       634
       +
       

     

       635
       635
       +
       4.1.2.4.  The Path Attribute

     

       636
       636
       +
       

     

       637
       637
       +
          The scope of each cookie is limited to a set of paths, controlled by

     

       638
       638
       +
          the Path attribute.  If the server omits the Path attribute, the user

     

       639
       639
       +
          agent will use the "directory" of the request-uri's path component as

     

       640
       640
       +
          the default value.  (See Section 5.1.4 for more details.)

     

       641
       641
       +
       

     

       642
       642
       +
          The user agent will include the cookie in an HTTP request only if the

     

       643
       643
       +
          path portion of the request-uri matches (or is a subdirectory of) the

     

       644
       644
       +
          cookie's Path attribute, where the %x2F ("/") character is

     

       645
       645
       +
          interpreted as a directory separator.

     

       646
       646
       +
       

     

       647
       647
       +
          Although seemingly useful for isolating cookies between different

     

       648
       648
       +
          paths within a given host, the Path attribute cannot be relied upon

     

       649
       649
       +
          for security (see Section 8).

     

       650
       650
       +
       

     

       651
       651
       +
       4.1.2.5.  The Secure Attribute

     

       652
       652
       +
       

     

       653
       653
       +
          The Secure attribute limits the scope of the cookie to "secure"

     

       654
       654
       +
          channels (where "secure" is defined by the user agent).  When a

     

       655
       655
       +
          cookie has the Secure attribute, the user agent will include the

     

       656
       656
       +
          cookie in an HTTP request only if the request is transmitted over a

     

       657
       657
       +
          secure channel (typically HTTP over Transport Layer Security (TLS)

     

       658
       658
       +
          [RFC2818]).

     

       659
       659
       +
       

     

       660
       660
       +
          Although seemingly useful for protecting cookies from active network

     

       661
       661
       +
          attackers, the Secure attribute protects only the cookie's

     

       662
       662
       +
          confidentiality.  An active network attacker can overwrite Secure

     

       663
       663
       +
          cookies from an insecure channel, disrupting their integrity (see

     

       664
       664
       +
          Section 8.6 for more details).

     

       665
       665
       +
       

     

       666
       666
       +
       

     

       667
       667
       +
       

     

       668
       668
       +
       

     

       669
       669
       +
       

     

       670
       670
       +
       

     

       671
       671
       +
       

     

       672
       672
       +
       

     

       673
       673
       +
       

     

       674
       674
       +
       Barth                        Standards Track                   [Page 12]

     

       675
       675
       +
       

     

       676
       676
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       677
       677
       +
       

     

       678
       678
       +
       

     

       679
       679
       +
       4.1.2.6.  The HttpOnly Attribute

     

       680
       680
       +
       

     

       681
       681
       +
          The HttpOnly attribute limits the scope of the cookie to HTTP

     

       682
       682
       +
          requests.  In particular, the attribute instructs the user agent to

     

       683
       683
       +
          omit the cookie when providing access to cookies via "non-HTTP" APIs

     

       684
       684
       +
          (such as a web browser API that exposes cookies to scripts).

     

       685
       685
       +
       

     

       686
       686
       +
          Note that the HttpOnly attribute is independent of the Secure

     

       687
       687
       +
          attribute: a cookie can have both the HttpOnly and the Secure

     

       688
       688
       +
          attribute.

     

       689
       689
       +
       

     

       690
       690
       +
       4.2.  Cookie

     

       691
       691
       +
       

     

       692
       692
       +
       4.2.1.  Syntax

     

       693
       693
       +
       

     

       694
       694
       +
          The user agent sends stored cookies to the origin server in the

     

       695
       695
       +
          Cookie header.  If the server conforms to the requirements in

     

       696
       696
       +
          Section 4.1 (and the user agent conforms to the requirements in

     

       697
       697
       +
          Section 5), the user agent will send a Cookie header that conforms to

     

       698
       698
       +
          the following grammar:

     

       699
       699
       +
       

     

       700
       700
       +
          cookie-header = "Cookie:" OWS cookie-string OWS

     

       701
       701
       +
          cookie-string = cookie-pair *( ";" SP cookie-pair )

     

       702
       702
       +
       

     

       703
       703
       +
       4.2.2.  Semantics

     

       704
       704
       +
       

     

       705
       705
       +
          Each cookie-pair represents a cookie stored by the user agent.  The

     

       706
       706
       +
          cookie-pair contains the cookie-name and cookie-value the user agent

     

       707
       707
       +
          received in the Set-Cookie header.

     

       708
       708
       +
       

     

       709
       709
       +
          Notice that the cookie attributes are not returned.  In particular,

     

       710
       710
       +
          the server cannot determine from the Cookie header alone when a

     

       711
       711
       +
          cookie will expire, for which hosts the cookie is valid, for which

     

       712
       712
       +
          paths the cookie is valid, or whether the cookie was set with the

     

       713
       713
       +
          Secure or HttpOnly attributes.

     

       714
       714
       +
       

     

       715
       715
       +
          The semantics of individual cookies in the Cookie header are not

     

       716
       716
       +
          defined by this document.  Servers are expected to imbue these

     

       717
       717
       +
          cookies with application-specific semantics.

     

       718
       718
       +
       

     

       719
       719
       +
          Although cookies are serialized linearly in the Cookie header,

     

       720
       720
       +
          servers SHOULD NOT rely upon the serialization order.  In particular,

     

       721
       721
       +
          if the Cookie header contains two cookies with the same name (e.g.,

     

       722
       722
       +
          that were set with different Path or Domain attributes), servers

     

       723
       723
       +
          SHOULD NOT rely upon the order in which these cookies appear in the

     

       724
       724
       +
          header.

     

       725
       725
       +
       

     

       726
       726
       +
       

     

       727
       727
       +
       

     

       728
       728
       +
       

     

       729
       729
       +
       

     

       730
       730
       +
       Barth                        Standards Track                   [Page 13]

     

       731
       731
       +
       

     

       732
       732
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       733
       733
       +
       

     

       734
       734
       +
       

     

       735
       735
       +
       5.  User Agent Requirements

     

       736
       736
       +
       

     

       737
       737
       +
          This section specifies the Cookie and Set-Cookie headers in

     

       738
       738
       +
          sufficient detail that a user agent implementing these requirements

     

       739
       739
       +
          precisely can interoperate with existing servers (even those that do

     

       740
       740
       +
          not conform to the well-behaved profile described in Section 4).

     

       741
       741
       +
       

     

       742
       742
       +
          A user agent could enforce more restrictions than those specified

     

       743
       743
       +
          herein (e.g., for the sake of improved security); however,

     

       744
       744
       +
          experiments have shown that such strictness reduces the likelihood

     

       745
       745
       +
          that a user agent will be able to interoperate with existing servers.

     

       746
       746
       +
       

     

       747
       747
       +
       5.1.  Subcomponent Algorithms

     

       748
       748
       +
       

     

       749
       749
       +
          This section defines some algorithms used by user agents to process

     

       750
       750
       +
          specific subcomponents of the Cookie and Set-Cookie headers.

     

       751
       751
       +
       

     

       752
       752
       +
       5.1.1.  Dates

     

       753
       753
       +
       

     

       754
       754
       +
          The user agent MUST use an algorithm equivalent to the following

     

       755
       755
       +
          algorithm to parse a cookie-date.  Note that the various boolean

     

       756
       756
       +
          flags defined as a part of the algorithm (i.e., found-time, found-

     

       757
       757
       +
          day-of-month, found-month, found-year) are initially "not set".

     

       758
       758
       +
       

     

       759
       759
       +
          1.  Using the grammar below, divide the cookie-date into date-tokens.

     

       760
       760
       +
       

     

       761
       761
       +
          cookie-date     = *delimiter date-token-list *delimiter

     

       762
       762
       +
          date-token-list = date-token *( 1*delimiter date-token )

     

       763
       763
       +
          date-token      = 1*non-delimiter

     

       764
       764
       +
       

     

       765
       765
       +
          delimiter       = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E

     

       766
       766
       +
          non-delimiter   = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF

     

       767
       767
       +
          non-digit       = %x00-2F / %x3A-FF

     

       768
       768
       +
       

     

       769
       769
       +
          day-of-month    = 1*2DIGIT ( non-digit *OCTET )

     

       770
       770
       +
          month           = ( "jan" / "feb" / "mar" / "apr" /

     

       771
       771
       +
                              "may" / "jun" / "jul" / "aug" /

     

       772
       772
       +
                              "sep" / "oct" / "nov" / "dec" ) *OCTET

     

       773
       773
       +
          year            = 2*4DIGIT ( non-digit *OCTET )

     

       774
       774
       +
          time            = hms-time ( non-digit *OCTET )

     

       775
       775
       +
          hms-time        = time-field ":" time-field ":" time-field

     

       776
       776
       +
          time-field      = 1*2DIGIT

     

       777
       777
       +
       

     

       778
       778
       +
          2.  Process each date-token sequentially in the order the date-tokens

     

       779
       779
       +
              appear in the cookie-date:

     

       780
       780
       +
       

     

       781
       781
       +
       

     

       782
       782
       +
       

     

       783
       783
       +
       

     

       784
       784
       +
       

     

       785
       785
       +
       

     

       786
       786
       +
       Barth                        Standards Track                   [Page 14]

     

       787
       787
       +
       

     

       788
       788
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       789
       789
       +
       

     

       790
       790
       +
       

     

       791
       791
       +
              1.  If the found-time flag is not set and the token matches the

     

       792
       792
       +
                  time production, set the found-time flag and set the hour-

     

       793
       793
       +
                  value, minute-value, and second-value to the numbers denoted

     

       794
       794
       +
                  by the digits in the date-token, respectively.  Skip the

     

       795
       795
       +
                  remaining sub-steps and continue to the next date-token.

     

       796
       796
       +
       

     

       797
       797
       +
              2.  If the found-day-of-month flag is not set and the date-token

     

       798
       798
       +
                  matches the day-of-month production, set the found-day-of-

     

       799
       799
       +
                  month flag and set the day-of-month-value to the number

     

       800
       800
       +
                  denoted by the date-token.  Skip the remaining sub-steps and

     

       801
       801
       +
                  continue to the next date-token.

     

       802
       802
       +
       

     

       803
       803
       +
              3.  If the found-month flag is not set and the date-token matches

     

       804
       804
       +
                  the month production, set the found-month flag and set the

     

       805
       805
       +
                  month-value to the month denoted by the date-token.  Skip the

     

       806
       806
       +
                  remaining sub-steps and continue to the next date-token.

     

       807
       807
       +
       

     

       808
       808
       +
              4.  If the found-year flag is not set and the date-token matches

     

       809
       809
       +
                  the year production, set the found-year flag and set the

     

       810
       810
       +
                  year-value to the number denoted by the date-token.  Skip the

     

       811
       811
       +
                  remaining sub-steps and continue to the next date-token.

     

       812
       812
       +
       

     

       813
       813
       +
          3.  If the year-value is greater than or equal to 70 and less than or

     

       814
       814
       +
              equal to 99, increment the year-value by 1900.

     

       815
       815
       +
       

     

       816
       816
       +
          4.  If the year-value is greater than or equal to 0 and less than or

     

       817
       817
       +
              equal to 69, increment the year-value by 2000.

     

       818
       818
       +
       

     

       819
       819
       +
              1.  NOTE: Some existing user agents interpret two-digit years

     

       820
       820
       +
                  differently.

     

       821
       821
       +
       

     

       822
       822
       +
          5.  Abort these steps and fail to parse the cookie-date if:

     

       823
       823
       +
       

     

       824
       824
       +
              *  at least one of the found-day-of-month, found-month, found-

     

       825
       825
       +
                 year, or found-time flags is not set,

     

       826
       826
       +
       

     

       827
       827
       +
              *  the day-of-month-value is less than 1 or greater than 31,

     

       828
       828
       +
       

     

       829
       829
       +
              *  the year-value is less than 1601,

     

       830
       830
       +
       

     

       831
       831
       +
              *  the hour-value is greater than 23,

     

       832
       832
       +
       

     

       833
       833
       +
              *  the minute-value is greater than 59, or

     

       834
       834
       +
       

     

       835
       835
       +
              *  the second-value is greater than 59.

     

       836
       836
       +
       

     

       837
       837
       +
              (Note that leap seconds cannot be represented in this syntax.)

     

       838
       838
       +
       

     

       839
       839
       +
       

     

       840
       840
       +
       

     

       841
       841
       +
       

     

       842
       842
       +
       Barth                        Standards Track                   [Page 15]

     

       843
       843
       +
       

     

       844
       844
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       845
       845
       +
       

     

       846
       846
       +
       

     

       847
       847
       +
          6.  Let the parsed-cookie-date be the date whose day-of-month, month,

     

       848
       848
       +
              year, hour, minute, and second (in UTC) are the day-of-month-

     

       849
       849
       +
              value, the month-value, the year-value, the hour-value, the

     

       850
       850
       +
              minute-value, and the second-value, respectively.  If no such

     

       851
       851
       +
              date exists, abort these steps and fail to parse the cookie-date.

     

       852
       852
       +
       

     

       853
       853
       +
          7.  Return the parsed-cookie-date as the result of this algorithm.

     

       854
       854
       +
       

     

       855
       855
       +
       5.1.2.  Canonicalized Host Names

     

       856
       856
       +
       

     

       857
       857
       +
          A canonicalized host name is the string generated by the following

     

       858
       858
       +
          algorithm:

     

       859
       859
       +
       

     

       860
       860
       +
          1.  Convert the host name to a sequence of individual domain name

     

       861
       861
       +
              labels.

     

       862
       862
       +
       

     

       863
       863
       +
          2.  Convert each label that is not a Non-Reserved LDH (NR-LDH) label,

     

       864
       864
       +
              to an A-label (see Section 2.3.2.1 of [RFC5890] for the former

     

       865
       865
       +
              and latter), or to a "punycode label" (a label resulting from the

     

       866
       866
       +
              "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate

     

       867
       867
       +
              (see Section 6.3 of this specification).

     

       868
       868
       +
       

     

       869
       869
       +
          3.  Concatenate the resulting labels, separated by a %x2E (".")

     

       870
       870
       +
              character.

     

       871
       871
       +
       

     

       872
       872
       +
       5.1.3.  Domain Matching

     

       873
       873
       +
       

     

       874
       874
       +
          A string domain-matches a given domain string if at least one of the

     

       875
       875
       +
          following conditions hold:

     

       876
       876
       +
       

     

       877
       877
       +
          o  The domain string and the string are identical.  (Note that both

     

       878
       878
       +
             the domain string and the string will have been canonicalized to

     

       879
       879
       +
             lower case at this point.)

     

       880
       880
       +
       

     

       881
       881
       +
          o  All of the following conditions hold:

     

       882
       882
       +
       

     

       883
       883
       +
             *  The domain string is a suffix of the string.

     

       884
       884
       +
       

     

       885
       885
       +
             *  The last character of the string that is not included in the

     

       886
       886
       +
                domain string is a %x2E (".") character.

     

       887
       887
       +
       

     

       888
       888
       +
             *  The string is a host name (i.e., not an IP address).

     

       889
       889
       +
       

     

       890
       890
       +
       5.1.4.  Paths and Path-Match

     

       891
       891
       +
       

     

       892
       892
       +
          The user agent MUST use an algorithm equivalent to the following

     

       893
       893
       +
          algorithm to compute the default-path of a cookie:

     

       894
       894
       +
       

     

       895
       895
       +
       

     

       896
       896
       +
       

     

       897
       897
       +
       

     

       898
       898
       +
       Barth                        Standards Track                   [Page 16]

     

       899
       899
       +
       

     

       900
       900
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       901
       901
       +
       

     

       902
       902
       +
       

     

       903
       903
       +
          1.  Let uri-path be the path portion of the request-uri if such a

     

       904
       904
       +
              portion exists (and empty otherwise).  For example, if the

     

       905
       905
       +
              request-uri contains just a path (and optional query string),

     

       906
       906
       +
              then the uri-path is that path (without the %x3F ("?") character

     

       907
       907
       +
              or query string), and if the request-uri contains a full

     

       908
       908
       +
              absoluteURI, the uri-path is the path component of that URI.

     

       909
       909
       +
       

     

       910
       910
       +
          2.  If the uri-path is empty or if the first character of the uri-

     

       911
       911
       +
              path is not a %x2F ("/") character, output %x2F ("/") and skip

     

       912
       912
       +
              the remaining steps.

     

       913
       913
       +
       

     

       914
       914
       +
          3.  If the uri-path contains no more than one %x2F ("/") character,

     

       915
       915
       +
              output %x2F ("/") and skip the remaining step.

     

       916
       916
       +
       

     

       917
       917
       +
          4.  Output the characters of the uri-path from the first character up

     

       918
       918
       +
              to, but not including, the right-most %x2F ("/").

     

       919
       919
       +
       

     

       920
       920
       +
          A request-path path-matches a given cookie-path if at least one of

     

       921
       921
       +
          the following conditions holds:

     

       922
       922
       +
       

     

       923
       923
       +
          o  The cookie-path and the request-path are identical.

     

       924
       924
       +
       

     

       925
       925
       +
          o  The cookie-path is a prefix of the request-path, and the last

     

       926
       926
       +
             character of the cookie-path is %x2F ("/").

     

       927
       927
       +
       

     

       928
       928
       +
          o  The cookie-path is a prefix of the request-path, and the first

     

       929
       929
       +
             character of the request-path that is not included in the cookie-

     

       930
       930
       +
             path is a %x2F ("/") character.

     

       931
       931
       +
       

     

       932
       932
       +
       5.2.  The Set-Cookie Header

     

       933
       933
       +
       

     

       934
       934
       +
          When a user agent receives a Set-Cookie header field in an HTTP

     

       935
       935
       +
          response, the user agent MAY ignore the Set-Cookie header field in

     

       936
       936
       +
          its entirety.  For example, the user agent might wish to block

     

       937
       937
       +
          responses to "third-party" requests from setting cookies (see

     

       938
       938
       +
          Section 7.1).

     

       939
       939
       +
       

     

       940
       940
       +
          If the user agent does not ignore the Set-Cookie header field in its

     

       941
       941
       +
          entirety, the user agent MUST parse the field-value of the Set-Cookie

     

       942
       942
       +
          header field as a set-cookie-string (defined below).

     

       943
       943
       +
       

     

       944
       944
       +
          NOTE: The algorithm below is more permissive than the grammar in

     

       945
       945
       +
          Section 4.1.  For example, the algorithm strips leading and trailing

     

       946
       946
       +
          whitespace from the cookie name and value (but maintains internal

     

       947
       947
       +
          whitespace), whereas the grammar in Section 4.1 forbids whitespace in

     

       948
       948
       +
          these positions.  User agents use this algorithm so as to

     

       949
       949
       +
          interoperate with servers that do not follow the recommendations in

     

       950
       950
       +
          Section 4.

     

       951
       951
       +
       

     

       952
       952
       +
       

     

       953
       953
       +
       

     

       954
       954
       +
       Barth                        Standards Track                   [Page 17]

     

       955
       955
       +
       

     

       956
       956
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       957
       957
       +
       

     

       958
       958
       +
       

     

       959
       959
       +
          A user agent MUST use an algorithm equivalent to the following

     

       960
       960
       +
          algorithm to parse a "set-cookie-string":

     

       961
       961
       +
       

     

       962
       962
       +
          1.  If the set-cookie-string contains a %x3B (";") character:

     

       963
       963
       +
       

     

       964
       964
       +
                 The name-value-pair string consists of the characters up to,

     

       965
       965
       +
                 but not including, the first %x3B (";"), and the unparsed-

     

       966
       966
       +
                 attributes consist of the remainder of the set-cookie-string

     

       967
       967
       +
                 (including the %x3B (";") in question).

     

       968
       968
       +
       

     

       969
       969
       +
              Otherwise:

     

       970
       970
       +
       

     

       971
       971
       +
                 The name-value-pair string consists of all the characters

     

       972
       972
       +
                 contained in the set-cookie-string, and the unparsed-

     

       973
       973
       +
                 attributes is the empty string.

     

       974
       974
       +
       

     

       975
       975
       +
          2.  If the name-value-pair string lacks a %x3D ("=") character,

     

       976
       976
       +
              ignore the set-cookie-string entirely.

     

       977
       977
       +
       

     

       978
       978
       +
          3.  The (possibly empty) name string consists of the characters up

     

       979
       979
       +
              to, but not including, the first %x3D ("=") character, and the

     

       980
       980
       +
              (possibly empty) value string consists of the characters after

     

       981
       981
       +
              the first %x3D ("=") character.

     

       982
       982
       +
       

     

       983
       983
       +
          4.  Remove any leading or trailing WSP characters from the name

     

       984
       984
       +
              string and the value string.

     

       985
       985
       +
       

     

       986
       986
       +
          5.  If the name string is empty, ignore the set-cookie-string

     

       987
       987
       +
              entirely.

     

       988
       988
       +
       

     

       989
       989
       +
          6.  The cookie-name is the name string, and the cookie-value is the

     

       990
       990
       +
              value string.

     

       991
       991
       +
       

     

       992
       992
       +
          The user agent MUST use an algorithm equivalent to the following

     

       993
       993
       +
          algorithm to parse the unparsed-attributes:

     

       994
       994
       +
       

     

       995
       995
       +
          1.  If the unparsed-attributes string is empty, skip the rest of

     

       996
       996
       +
              these steps.

     

       997
       997
       +
       

     

       998
       998
       +
          2.  Discard the first character of the unparsed-attributes (which

     

       999
       999
       +
              will be a %x3B (";") character).

     

       1000
       1000
       +
       

     

       1001
       1001
       +
          3.  If the remaining unparsed-attributes contains a %x3B (";")

     

       1002
       1002
       +
              character:

     

       1003
       1003
       +
       

     

       1004
       1004
       +
                 Consume the characters of the unparsed-attributes up to, but

     

       1005
       1005
       +
                 not including, the first %x3B (";") character.

     

       1006
       1006
       +
       

     

       1007
       1007
       +
       

     

       1008
       1008
       +
       

     

       1009
       1009
       +
       

     

       1010
       1010
       +
       Barth                        Standards Track                   [Page 18]

     

       1011
       1011
       +
       

     

       1012
       1012
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1013
       1013
       +
       

     

       1014
       1014
       +
       

     

       1015
       1015
       +
              Otherwise:

     

       1016
       1016
       +
       

     

       1017
       1017
       +
                 Consume the remainder of the unparsed-attributes.

     

       1018
       1018
       +
       

     

       1019
       1019
       +
              Let the cookie-av string be the characters consumed in this step.

     

       1020
       1020
       +
       

     

       1021
       1021
       +
          4.  If the cookie-av string contains a %x3D ("=") character:

     

       1022
       1022
       +
       

     

       1023
       1023
       +
                 The (possibly empty) attribute-name string consists of the

     

       1024
       1024
       +
                 characters up to, but not including, the first %x3D ("=")

     

       1025
       1025
       +
                 character, and the (possibly empty) attribute-value string

     

       1026
       1026
       +
                 consists of the characters after the first %x3D ("=")

     

       1027
       1027
       +
                 character.

     

       1028
       1028
       +
       

     

       1029
       1029
       +
              Otherwise:

     

       1030
       1030
       +
       

     

       1031
       1031
       +
                 The attribute-name string consists of the entire cookie-av

     

       1032
       1032
       +
                 string, and the attribute-value string is empty.

     

       1033
       1033
       +
       

     

       1034
       1034
       +
          5.  Remove any leading or trailing WSP characters from the attribute-

     

       1035
       1035
       +
              name string and the attribute-value string.

     

       1036
       1036
       +
       

     

       1037
       1037
       +
          6.  Process the attribute-name and attribute-value according to the

     

       1038
       1038
       +
              requirements in the following subsections.  (Notice that

     

       1039
       1039
       +
              attributes with unrecognized attribute-names are ignored.)

     

       1040
       1040
       +
       

     

       1041
       1041
       +
          7.  Return to Step 1 of this algorithm.

     

       1042
       1042
       +
       

     

       1043
       1043
       +
          When the user agent finishes parsing the set-cookie-string, the user

     

       1044
       1044
       +
          agent is said to "receive a cookie" from the request-uri with name

     

       1045
       1045
       +
          cookie-name, value cookie-value, and attributes cookie-attribute-

     

       1046
       1046
       +
          list.  (See Section 5.3 for additional requirements triggered by

     

       1047
       1047
       +
          receiving a cookie.)

     

       1048
       1048
       +
       

     

       1049
       1049
       +
       5.2.1.  The Expires Attribute

     

       1050
       1050
       +
       

     

       1051
       1051
       +
          If the attribute-name case-insensitively matches the string

     

       1052
       1052
       +
          "Expires", the user agent MUST process the cookie-av as follows.

     

       1053
       1053
       +
       

     

       1054
       1054
       +
          Let the expiry-time be the result of parsing the attribute-value as

     

       1055
       1055
       +
          cookie-date (see Section 5.1.1).

     

       1056
       1056
       +
       

     

       1057
       1057
       +
          If the attribute-value failed to parse as a cookie date, ignore the

     

       1058
       1058
       +
          cookie-av.

     

       1059
       1059
       +
       

     

       1060
       1060
       +
          If the expiry-time is later than the last date the user agent can

     

       1061
       1061
       +
          represent, the user agent MAY replace the expiry-time with the last

     

       1062
       1062
       +
          representable date.

     

       1063
       1063
       +
       

     

       1064
       1064
       +
       

     

       1065
       1065
       +
       

     

       1066
       1066
       +
       Barth                        Standards Track                   [Page 19]

     

       1067
       1067
       +
       

     

       1068
       1068
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1069
       1069
       +
       

     

       1070
       1070
       +
       

     

       1071
       1071
       +
          If the expiry-time is earlier than the earliest date the user agent

     

       1072
       1072
       +
          can represent, the user agent MAY replace the expiry-time with the

     

       1073
       1073
       +
          earliest representable date.

     

       1074
       1074
       +
       

     

       1075
       1075
       +
          Append an attribute to the cookie-attribute-list with an attribute-

     

       1076
       1076
       +
          name of Expires and an attribute-value of expiry-time.

     

       1077
       1077
       +
       

     

       1078
       1078
       +
       5.2.2.  The Max-Age Attribute

     

       1079
       1079
       +
       

     

       1080
       1080
       +
          If the attribute-name case-insensitively matches the string "Max-

     

       1081
       1081
       +
          Age", the user agent MUST process the cookie-av as follows.

     

       1082
       1082
       +
       

     

       1083
       1083
       +
          If the first character of the attribute-value is not a DIGIT or a "-"

     

       1084
       1084
       +
          character, ignore the cookie-av.

     

       1085
       1085
       +
       

     

       1086
       1086
       +
          If the remainder of attribute-value contains a non-DIGIT character,

     

       1087
       1087
       +
          ignore the cookie-av.

     

       1088
       1088
       +
       

     

       1089
       1089
       +
          Let delta-seconds be the attribute-value converted to an integer.

     

       1090
       1090
       +
       

     

       1091
       1091
       +
          If delta-seconds is less than or equal to zero (0), let expiry-time

     

       1092
       1092
       +
          be the earliest representable date and time.  Otherwise, let the

     

       1093
       1093
       +
          expiry-time be the current date and time plus delta-seconds seconds.

     

       1094
       1094
       +
       

     

       1095
       1095
       +
          Append an attribute to the cookie-attribute-list with an attribute-

     

       1096
       1096
       +
          name of Max-Age and an attribute-value of expiry-time.

     

       1097
       1097
       +
       

     

       1098
       1098
       +
       5.2.3.  The Domain Attribute

     

       1099
       1099
       +
       

     

       1100
       1100
       +
          If the attribute-name case-insensitively matches the string "Domain",

     

       1101
       1101
       +
          the user agent MUST process the cookie-av as follows.

     

       1102
       1102
       +
       

     

       1103
       1103
       +
          If the attribute-value is empty, the behavior is undefined.  However,

     

       1104
       1104
       +
          the user agent SHOULD ignore the cookie-av entirely.

     

       1105
       1105
       +
       

     

       1106
       1106
       +
          If the first character of the attribute-value string is %x2E ("."):

     

       1107
       1107
       +
       

     

       1108
       1108
       +
             Let cookie-domain be the attribute-value without the leading %x2E

     

       1109
       1109
       +
             (".") character.

     

       1110
       1110
       +
       

     

       1111
       1111
       +
          Otherwise:

     

       1112
       1112
       +
       

     

       1113
       1113
       +
             Let cookie-domain be the entire attribute-value.

     

       1114
       1114
       +
       

     

       1115
       1115
       +
          Convert the cookie-domain to lower case.

     

       1116
       1116
       +
       

     

       1117
       1117
       +
          Append an attribute to the cookie-attribute-list with an attribute-

     

       1118
       1118
       +
          name of Domain and an attribute-value of cookie-domain.

     

       1119
       1119
       +
       

     

       1120
       1120
       +
       

     

       1121
       1121
       +
       

     

       1122
       1122
       +
       Barth                        Standards Track                   [Page 20]

     

       1123
       1123
       +
       

     

       1124
       1124
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1125
       1125
       +
       

     

       1126
       1126
       +
       

     

       1127
       1127
       +
       5.2.4.  The Path Attribute

     

       1128
       1128
       +
       

     

       1129
       1129
       +
          If the attribute-name case-insensitively matches the string "Path",

     

       1130
       1130
       +
          the user agent MUST process the cookie-av as follows.

     

       1131
       1131
       +
       

     

       1132
       1132
       +
          If the attribute-value is empty or if the first character of the

     

       1133
       1133
       +
          attribute-value is not %x2F ("/"):

     

       1134
       1134
       +
       

     

       1135
       1135
       +
             Let cookie-path be the default-path.

     

       1136
       1136
       +
       

     

       1137
       1137
       +
          Otherwise:

     

       1138
       1138
       +
       

     

       1139
       1139
       +
             Let cookie-path be the attribute-value.

     

       1140
       1140
       +
       

     

       1141
       1141
       +
          Append an attribute to the cookie-attribute-list with an attribute-

     

       1142
       1142
       +
          name of Path and an attribute-value of cookie-path.

     

       1143
       1143
       +
       

     

       1144
       1144
       +
       5.2.5.  The Secure Attribute

     

       1145
       1145
       +
       

     

       1146
       1146
       +
          If the attribute-name case-insensitively matches the string "Secure",

     

       1147
       1147
       +
          the user agent MUST append an attribute to the cookie-attribute-list

     

       1148
       1148
       +
          with an attribute-name of Secure and an empty attribute-value.

     

       1149
       1149
       +
       

     

       1150
       1150
       +
       5.2.6.  The HttpOnly Attribute

     

       1151
       1151
       +
       

     

       1152
       1152
       +
          If the attribute-name case-insensitively matches the string

     

       1153
       1153
       +
          "HttpOnly", the user agent MUST append an attribute to the cookie-

     

       1154
       1154
       +
          attribute-list with an attribute-name of HttpOnly and an empty

     

       1155
       1155
       +
          attribute-value.

     

       1156
       1156
       +
       

     

       1157
       1157
       +
       5.3.  Storage Model

     

       1158
       1158
       +
       

     

       1159
       1159
       +
          The user agent stores the following fields about each cookie: name,

     

       1160
       1160
       +
          value, expiry-time, domain, path, creation-time, last-access-time,

     

       1161
       1161
       +
          persistent-flag, host-only-flag, secure-only-flag, and http-only-

     

       1162
       1162
       +
          flag.

     

       1163
       1163
       +
       

     

       1164
       1164
       +
          When the user agent "receives a cookie" from a request-uri with name

     

       1165
       1165
       +
          cookie-name, value cookie-value, and attributes cookie-attribute-

     

       1166
       1166
       +
          list, the user agent MUST process the cookie as follows:

     

       1167
       1167
       +
       

     

       1168
       1168
       +
          1.   A user agent MAY ignore a received cookie in its entirety.  For

     

       1169
       1169
       +
               example, the user agent might wish to block receiving cookies

     

       1170
       1170
       +
               from "third-party" responses or the user agent might not wish to

     

       1171
       1171
       +
               store cookies that exceed some size.

     

       1172
       1172
       +
       

     

       1173
       1173
       +
       

     

       1174
       1174
       +
       

     

       1175
       1175
       +
       

     

       1176
       1176
       +
       

     

       1177
       1177
       +
       

     

       1178
       1178
       +
       Barth                        Standards Track                   [Page 21]

     

       1179
       1179
       +
       

     

       1180
       1180
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1181
       1181
       +
       

     

       1182
       1182
       +
       

     

       1183
       1183
       +
          2.   Create a new cookie with name cookie-name, value cookie-value.

     

       1184
       1184
       +
               Set the creation-time and the last-access-time to the current

     

       1185
       1185
       +
               date and time.

     

       1186
       1186
       +
       

     

       1187
       1187
       +
          3.   If the cookie-attribute-list contains an attribute with an

     

       1188
       1188
       +
               attribute-name of "Max-Age":

     

       1189
       1189
       +
       

     

       1190
       1190
       +
                  Set the cookie's persistent-flag to true.

     

       1191
       1191
       +
       

     

       1192
       1192
       +
                  Set the cookie's expiry-time to attribute-value of the last

     

       1193
       1193
       +
                  attribute in the cookie-attribute-list with an attribute-name

     

       1194
       1194
       +
                  of "Max-Age".

     

       1195
       1195
       +
       

     

       1196
       1196
       +
               Otherwise, if the cookie-attribute-list contains an attribute

     

       1197
       1197
       +
               with an attribute-name of "Expires" (and does not contain an

     

       1198
       1198
       +
               attribute with an attribute-name of "Max-Age"):

     

       1199
       1199
       +
       

     

       1200
       1200
       +
                  Set the cookie's persistent-flag to true.

     

       1201
       1201
       +
       

     

       1202
       1202
       +
                  Set the cookie's expiry-time to attribute-value of the last

     

       1203
       1203
       +
                  attribute in the cookie-attribute-list with an attribute-name

     

       1204
       1204
       +
                  of "Expires".

     

       1205
       1205
       +
       

     

       1206
       1206
       +
               Otherwise:

     

       1207
       1207
       +
       

     

       1208
       1208
       +
                  Set the cookie's persistent-flag to false.

     

       1209
       1209
       +
       

     

       1210
       1210
       +
                  Set the cookie's expiry-time to the latest representable

     

       1211
       1211
       +
                  date.

     

       1212
       1212
       +
       

     

       1213
       1213
       +
          4.   If the cookie-attribute-list contains an attribute with an

     

       1214
       1214
       +
               attribute-name of "Domain":

     

       1215
       1215
       +
       

     

       1216
       1216
       +
                  Let the domain-attribute be the attribute-value of the last

     

       1217
       1217
       +
                  attribute in the cookie-attribute-list with an attribute-name

     

       1218
       1218
       +
                  of "Domain".

     

       1219
       1219
       +
       

     

       1220
       1220
       +
               Otherwise:

     

       1221
       1221
       +
       

     

       1222
       1222
       +
                  Let the domain-attribute be the empty string.

     

       1223
       1223
       +
       

     

       1224
       1224
       +
          5.   If the user agent is configured to reject "public suffixes" and

     

       1225
       1225
       +
               the domain-attribute is a public suffix:

     

       1226
       1226
       +
       

     

       1227
       1227
       +
                  If the domain-attribute is identical to the canonicalized

     

       1228
       1228
       +
                  request-host:

     

       1229
       1229
       +
       

     

       1230
       1230
       +
                     Let the domain-attribute be the empty string.

     

       1231
       1231
       +
       

     

       1232
       1232
       +
       

     

       1233
       1233
       +
       

     

       1234
       1234
       +
       Barth                        Standards Track                   [Page 22]

     

       1235
       1235
       +
       

     

       1236
       1236
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1237
       1237
       +
       

     

       1238
       1238
       +
       

     

       1239
       1239
       +
                  Otherwise:

     

       1240
       1240
       +
       

     

       1241
       1241
       +
                     Ignore the cookie entirely and abort these steps.

     

       1242
       1242
       +
       

     

       1243
       1243
       +
                  NOTE: A "public suffix" is a domain that is controlled by a

     

       1244
       1244
       +
                  public registry, such as "com", "co.uk", and "pvt.k12.wy.us".

     

       1245
       1245
       +
                  This step is essential for preventing attacker.com from

     

       1246
       1246
       +
                  disrupting the integrity of example.com by setting a cookie

     

       1247
       1247
       +
                  with a Domain attribute of "com".  Unfortunately, the set of

     

       1248
       1248
       +
                  public suffixes (also known as "registry controlled domains")

     

       1249
       1249
       +
                  changes over time.  If feasible, user agents SHOULD use an

     

       1250
       1250
       +
                  up-to-date public suffix list, such as the one maintained by

     

       1251
       1251
       +
                  the Mozilla project at <http://publicsuffix.org/>.

     

       1252
       1252
       +
       

     

       1253
       1253
       +
          6.   If the domain-attribute is non-empty:

     

       1254
       1254
       +
       

     

       1255
       1255
       +
                  If the canonicalized request-host does not domain-match the

     

       1256
       1256
       +
                  domain-attribute:

     

       1257
       1257
       +
       

     

       1258
       1258
       +
                     Ignore the cookie entirely and abort these steps.

     

       1259
       1259
       +
       

     

       1260
       1260
       +
                  Otherwise:

     

       1261
       1261
       +
       

     

       1262
       1262
       +
                     Set the cookie's host-only-flag to false.

     

       1263
       1263
       +
       

     

       1264
       1264
       +
                     Set the cookie's domain to the domain-attribute.

     

       1265
       1265
       +
       

     

       1266
       1266
       +
               Otherwise:

     

       1267
       1267
       +
       

     

       1268
       1268
       +
                  Set the cookie's host-only-flag to true.

     

       1269
       1269
       +
       

     

       1270
       1270
       +
                  Set the cookie's domain to the canonicalized request-host.

     

       1271
       1271
       +
       

     

       1272
       1272
       +
          7.   If the cookie-attribute-list contains an attribute with an

     

       1273
       1273
       +
               attribute-name of "Path", set the cookie's path to attribute-

     

       1274
       1274
       +
               value of the last attribute in the cookie-attribute-list with an

     

       1275
       1275
       +
               attribute-name of "Path".  Otherwise, set the cookie's path to

     

       1276
       1276
       +
               the default-path of the request-uri.

     

       1277
       1277
       +
       

     

       1278
       1278
       +
          8.   If the cookie-attribute-list contains an attribute with an

     

       1279
       1279
       +
               attribute-name of "Secure", set the cookie's secure-only-flag to

     

       1280
       1280
       +
               true.  Otherwise, set the cookie's secure-only-flag to false.

     

       1281
       1281
       +
       

     

       1282
       1282
       +
          9.   If the cookie-attribute-list contains an attribute with an

     

       1283
       1283
       +
               attribute-name of "HttpOnly", set the cookie's http-only-flag to

     

       1284
       1284
       +
               true.  Otherwise, set the cookie's http-only-flag to false.

     

       1285
       1285
       +
       

     

       1286
       1286
       +
       

     

       1287
       1287
       +
       

     

       1288
       1288
       +
       

     

       1289
       1289
       +
       

     

       1290
       1290
       +
       Barth                        Standards Track                   [Page 23]

     

       1291
       1291
       +
       

     

       1292
       1292
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1293
       1293
       +
       

     

       1294
       1294
       +
       

     

       1295
       1295
       +
          10.  If the cookie was received from a "non-HTTP" API and the

     

       1296
       1296
       +
               cookie's http-only-flag is set, abort these steps and ignore the

     

       1297
       1297
       +
               cookie entirely.

     

       1298
       1298
       +
       

     

       1299
       1299
       +
          11.  If the cookie store contains a cookie with the same name,

     

       1300
       1300
       +
               domain, and path as the newly created cookie:

     

       1301
       1301
       +
       

     

       1302
       1302
       +
               1.  Let old-cookie be the existing cookie with the same name,

     

       1303
       1303
       +
                   domain, and path as the newly created cookie.  (Notice that

     

       1304
       1304
       +
                   this algorithm maintains the invariant that there is at most

     

       1305
       1305
       +
                   one such cookie.)

     

       1306
       1306
       +
       

     

       1307
       1307
       +
               2.  If the newly created cookie was received from a "non-HTTP"

     

       1308
       1308
       +
                   API and the old-cookie's http-only-flag is set, abort these

     

       1309
       1309
       +
                   steps and ignore the newly created cookie entirely.

     

       1310
       1310
       +
       

     

       1311
       1311
       +
               3.  Update the creation-time of the newly created cookie to

     

       1312
       1312
       +
                   match the creation-time of the old-cookie.

     

       1313
       1313
       +
       

     

       1314
       1314
       +
               4.  Remove the old-cookie from the cookie store.

     

       1315
       1315
       +
       

     

       1316
       1316
       +
          12.  Insert the newly created cookie into the cookie store.

     

       1317
       1317
       +
       

     

       1318
       1318
       +
          A cookie is "expired" if the cookie has an expiry date in the past.

     

       1319
       1319
       +
       

     

       1320
       1320
       +
          The user agent MUST evict all expired cookies from the cookie store

     

       1321
       1321
       +
          if, at any time, an expired cookie exists in the cookie store.

     

       1322
       1322
       +
       

     

       1323
       1323
       +
          At any time, the user agent MAY "remove excess cookies" from the

     

       1324
       1324
       +
          cookie store if the number of cookies sharing a domain field exceeds

     

       1325
       1325
       +
          some implementation-defined upper bound (such as 50 cookies).

     

       1326
       1326
       +
       

     

       1327
       1327
       +
          At any time, the user agent MAY "remove excess cookies" from the

     

       1328
       1328
       +
          cookie store if the cookie store exceeds some predetermined upper

     

       1329
       1329
       +
          bound (such as 3000 cookies).

     

       1330
       1330
       +
       

     

       1331
       1331
       +
          When the user agent removes excess cookies from the cookie store, the

     

       1332
       1332
       +
          user agent MUST evict cookies in the following priority order:

     

       1333
       1333
       +
       

     

       1334
       1334
       +
          1.  Expired cookies.

     

       1335
       1335
       +
       

     

       1336
       1336
       +
          2.  Cookies that share a domain field with more than a predetermined

     

       1337
       1337
       +
              number of other cookies.

     

       1338
       1338
       +
       

     

       1339
       1339
       +
          3.  All cookies.

     

       1340
       1340
       +
       

     

       1341
       1341
       +
          If two cookies have the same removal priority, the user agent MUST

     

       1342
       1342
       +
          evict the cookie with the earliest last-access date first.

     

       1343
       1343
       +
       

     

       1344
       1344
       +
       

     

       1345
       1345
       +
       

     

       1346
       1346
       +
       Barth                        Standards Track                   [Page 24]

     

       1347
       1347
       +
       

     

       1348
       1348
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1349
       1349
       +
       

     

       1350
       1350
       +
       

     

       1351
       1351
       +
          When "the current session is over" (as defined by the user agent),

     

       1352
       1352
       +
          the user agent MUST remove from the cookie store all cookies with the

     

       1353
       1353
       +
          persistent-flag set to false.

     

       1354
       1354
       +
       

     

       1355
       1355
       +
       5.4.  The Cookie Header

     

       1356
       1356
       +
       

     

       1357
       1357
       +
          The user agent includes stored cookies in the Cookie HTTP request

     

       1358
       1358
       +
          header.

     

       1359
       1359
       +
       

     

       1360
       1360
       +
          When the user agent generates an HTTP request, the user agent MUST

     

       1361
       1361
       +
          NOT attach more than one Cookie header field.

     

       1362
       1362
       +
       

     

       1363
       1363
       +
          A user agent MAY omit the Cookie header in its entirety.  For

     

       1364
       1364
       +
          example, the user agent might wish to block sending cookies during

     

       1365
       1365
       +
          "third-party" requests from setting cookies (see Section 7.1).

     

       1366
       1366
       +
       

     

       1367
       1367
       +
          If the user agent does attach a Cookie header field to an HTTP

     

       1368
       1368
       +
          request, the user agent MUST send the cookie-string (defined below)

     

       1369
       1369
       +
          as the value of the header field.

     

       1370
       1370
       +
       

     

       1371
       1371
       +
          The user agent MUST use an algorithm equivalent to the following

     

       1372
       1372
       +
          algorithm to compute the "cookie-string" from a cookie store and a

     

       1373
       1373
       +
          request-uri:

     

       1374
       1374
       +
       

     

       1375
       1375
       +
          1.  Let cookie-list be the set of cookies from the cookie store that

     

       1376
       1376
       +
              meets all of the following requirements:

     

       1377
       1377
       +
       

     

       1378
       1378
       +
              *  Either:

     

       1379
       1379
       +
       

     

       1380
       1380
       +
                    The cookie's host-only-flag is true and the canonicalized

     

       1381
       1381
       +
                    request-host is identical to the cookie's domain.

     

       1382
       1382
       +
       

     

       1383
       1383
       +
                 Or:

     

       1384
       1384
       +
       

     

       1385
       1385
       +
                    The cookie's host-only-flag is false and the canonicalized

     

       1386
       1386
       +
                    request-host domain-matches the cookie's domain.

     

       1387
       1387
       +
       

     

       1388
       1388
       +
              *  The request-uri's path path-matches the cookie's path.

     

       1389
       1389
       +
       

     

       1390
       1390
       +
              *  If the cookie's secure-only-flag is true, then the request-

     

       1391
       1391
       +
                 uri's scheme must denote a "secure" protocol (as defined by

     

       1392
       1392
       +
                 the user agent).

     

       1393
       1393
       +
       

     

       1394
       1394
       +
                    NOTE: The notion of a "secure" protocol is not defined by

     

       1395
       1395
       +
                    this document.  Typically, user agents consider a protocol

     

       1396
       1396
       +
                    secure if the protocol makes use of transport-layer

     

       1397
       1397
       +
       

     

       1398
       1398
       +
       

     

       1399
       1399
       +
       

     

       1400
       1400
       +
       

     

       1401
       1401
       +
       

     

       1402
       1402
       +
       Barth                        Standards Track                   [Page 25]

     

       1403
       1403
       +
       

     

       1404
       1404
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1405
       1405
       +
       

     

       1406
       1406
       +
       

     

       1407
       1407
       +
                    security, such as SSL or TLS.  For example, most user

     

       1408
       1408
       +
                    agents consider "https" to be a scheme that denotes a

     

       1409
       1409
       +
                    secure protocol.

     

       1410
       1410
       +
       

     

       1411
       1411
       +
              *  If the cookie's http-only-flag is true, then exclude the

     

       1412
       1412
       +
                 cookie if the cookie-string is being generated for a "non-

     

       1413
       1413
       +
                 HTTP" API (as defined by the user agent).

     

       1414
       1414
       +
       

     

       1415
       1415
       +
          2.  The user agent SHOULD sort the cookie-list in the following

     

       1416
       1416
       +
              order:

     

       1417
       1417
       +
       

     

       1418
       1418
       +
              *  Cookies with longer paths are listed before cookies with

     

       1419
       1419
       +
                 shorter paths.

     

       1420
       1420
       +
       

     

       1421
       1421
       +
              *  Among cookies that have equal-length path fields, cookies with

     

       1422
       1422
       +
                 earlier creation-times are listed before cookies with later

     

       1423
       1423
       +
                 creation-times.

     

       1424
       1424
       +
       

     

       1425
       1425
       +
              NOTE: Not all user agents sort the cookie-list in this order, but

     

       1426
       1426
       +
              this order reflects common practice when this document was

     

       1427
       1427
       +
              written, and, historically, there have been servers that

     

       1428
       1428
       +
              (erroneously) depended on this order.

     

       1429
       1429
       +
       

     

       1430
       1430
       +
          3.  Update the last-access-time of each cookie in the cookie-list to

     

       1431
       1431
       +
              the current date and time.

     

       1432
       1432
       +
       

     

       1433
       1433
       +
          4.  Serialize the cookie-list into a cookie-string by processing each

     

       1434
       1434
       +
              cookie in the cookie-list in order:

     

       1435
       1435
       +
       

     

       1436
       1436
       +
              1.  Output the cookie's name, the %x3D ("=") character, and the

     

       1437
       1437
       +
                  cookie's value.

     

       1438
       1438
       +
       

     

       1439
       1439
       +
              2.  If there is an unprocessed cookie in the cookie-list, output

     

       1440
       1440
       +
                  the characters %x3B and %x20 ("; ").

     

       1441
       1441
       +
       

     

       1442
       1442
       +
          NOTE: Despite its name, the cookie-string is actually a sequence of

     

       1443
       1443
       +
          octets, not a sequence of characters.  To convert the cookie-string

     

       1444
       1444
       +
          (or components thereof) into a sequence of characters (e.g., for

     

       1445
       1445
       +
          presentation to the user), the user agent might wish to try using the

     

       1446
       1446
       +
          UTF-8 character encoding [RFC3629] to decode the octet sequence.

     

       1447
       1447
       +
          This decoding might fail, however, because not every sequence of

     

       1448
       1448
       +
          octets is valid UTF-8.

     

       1449
       1449
       +
       

     

       1450
       1450
       +
       

     

       1451
       1451
       +
       

     

       1452
       1452
       +
       

     

       1453
       1453
       +
       

     

       1454
       1454
       +
       

     

       1455
       1455
       +
       

     

       1456
       1456
       +
       

     

       1457
       1457
       +
       

     

       1458
       1458
       +
       Barth                        Standards Track                   [Page 26]

     

       1459
       1459
       +
       

     

       1460
       1460
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1461
       1461
       +
       

     

       1462
       1462
       +
       

     

       1463
       1463
       +
       6.  Implementation Considerations

     

       1464
       1464
       +
       

     

       1465
       1465
       +
       6.1.  Limits

     

       1466
       1466
       +
       

     

       1467
       1467
       +
          Practical user agent implementations have limits on the number and

     

       1468
       1468
       +
          size of cookies that they can store.  General-use user agents SHOULD

     

       1469
       1469
       +
          provide each of the following minimum capabilities:

     

       1470
       1470
       +
       

     

       1471
       1471
       +
          o  At least 4096 bytes per cookie (as measured by the sum of the

     

       1472
       1472
       +
             length of the cookie's name, value, and attributes).

     

       1473
       1473
       +
       

     

       1474
       1474
       +
          o  At least 50 cookies per domain.

     

       1475
       1475
       +
       

     

       1476
       1476
       +
          o  At least 3000 cookies total.

     

       1477
       1477
       +
       

     

       1478
       1478
       +
          Servers SHOULD use as few and as small cookies as possible to avoid

     

       1479
       1479
       +
          reaching these implementation limits and to minimize network

     

       1480
       1480
       +
          bandwidth due to the Cookie header being included in every request.

     

       1481
       1481
       +
       

     

       1482
       1482
       +
          Servers SHOULD gracefully degrade if the user agent fails to return

     

       1483
       1483
       +
          one or more cookies in the Cookie header because the user agent might

     

       1484
       1484
       +
          evict any cookie at any time on orders from the user.

     

       1485
       1485
       +
       

     

       1486
       1486
       +
       6.2.  Application Programming Interfaces

     

       1487
       1487
       +
       

     

       1488
       1488
       +
          One reason the Cookie and Set-Cookie headers use such esoteric syntax

     

       1489
       1489
       +
          is that many platforms (both in servers and user agents) provide a

     

       1490
       1490
       +
          string-based application programming interface (API) to cookies,

     

       1491
       1491
       +
          requiring application-layer programmers to generate and parse the

     

       1492
       1492
       +
          syntax used by the Cookie and Set-Cookie headers, which many

     

       1493
       1493
       +
          programmers have done incorrectly, resulting in interoperability

     

       1494
       1494
       +
          problems.

     

       1495
       1495
       +
       

     

       1496
       1496
       +
          Instead of providing string-based APIs to cookies, platforms would be

     

       1497
       1497
       +
          well-served by providing more semantic APIs.  It is beyond the scope

     

       1498
       1498
       +
          of this document to recommend specific API designs, but there are

     

       1499
       1499
       +
          clear benefits to accepting an abstract "Date" object instead of a

     

       1500
       1500
       +
          serialized date string.

     

       1501
       1501
       +
       

     

       1502
       1502
       +
       6.3.  IDNA Dependency and Migration

     

       1503
       1503
       +
       

     

       1504
       1504
       +
          IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490].  However, there are

     

       1505
       1505
       +
          differences between the two specifications, and thus there can be

     

       1506
       1506
       +
          differences in processing (e.g., converting) domain name labels that

     

       1507
       1507
       +
          have been registered under one from those registered under the other.

     

       1508
       1508
       +
          There will be a transition period of some time during which IDNA2003-

     

       1509
       1509
       +
          based domain name labels will exist in the wild.  User agents SHOULD

     

       1510
       1510
       +
          implement IDNA2008 [RFC5890] and MAY implement [UTS46] or [RFC5895]

     

       1511
       1511
       +
       

     

       1512
       1512
       +
       

     

       1513
       1513
       +
       

     

       1514
       1514
       +
       Barth                        Standards Track                   [Page 27]

     

       1515
       1515
       +
       

     

       1516
       1516
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1517
       1517
       +
       

     

       1518
       1518
       +
       

     

       1519
       1519
       +
          in order to facilitate their IDNA transition.  If a user agent does

     

       1520
       1520
       +
          not implement IDNA2008, the user agent MUST implement IDNA2003

     

       1521
       1521
       +
          [RFC3490].

     

       1522
       1522
       +
       

     

       1523
       1523
       +
       7.  Privacy Considerations

     

       1524
       1524
       +
       

     

       1525
       1525
       +
          Cookies are often criticized for letting servers track users.  For

     

       1526
       1526
       +
          example, a number of "web analytics" companies use cookies to

     

       1527
       1527
       +
          recognize when a user returns to a web site or visits another web

     

       1528
       1528
       +
          site.  Although cookies are not the only mechanism servers can use to

     

       1529
       1529
       +
          track users across HTTP requests, cookies facilitate tracking because

     

       1530
       1530
       +
          they are persistent across user agent sessions and can be shared

     

       1531
       1531
       +
          between hosts.

     

       1532
       1532
       +
       

     

       1533
       1533
       +
       7.1.  Third-Party Cookies

     

       1534
       1534
       +
       

     

       1535
       1535
       +
          Particularly worrisome are so-called "third-party" cookies.  In

     

       1536
       1536
       +
          rendering an HTML document, a user agent often requests resources

     

       1537
       1537
       +
          from other servers (such as advertising networks).  These third-party

     

       1538
       1538
       +
          servers can use cookies to track the user even if the user never

     

       1539
       1539
       +
          visits the server directly.  For example, if a user visits a site

     

       1540
       1540
       +
          that contains content from a third party and then later visits

     

       1541
       1541
       +
          another site that contains content from the same third party, the

     

       1542
       1542
       +
          third party can track the user between the two sites.

     

       1543
       1543
       +
       

     

       1544
       1544
       +
          Some user agents restrict how third-party cookies behave.  For

     

       1545
       1545
       +
          example, some of these user agents refuse to send the Cookie header

     

       1546
       1546
       +
          in third-party requests.  Others refuse to process the Set-Cookie

     

       1547
       1547
       +
          header in responses to third-party requests.  User agents vary widely

     

       1548
       1548
       +
          in their third-party cookie policies.  This document grants user

     

       1549
       1549
       +
          agents wide latitude to experiment with third-party cookie policies

     

       1550
       1550
       +
          that balance the privacy and compatibility needs of their users.

     

       1551
       1551
       +
          However, this document does not endorse any particular third-party

     

       1552
       1552
       +
          cookie policy.

     

       1553
       1553
       +
       

     

       1554
       1554
       +
          Third-party cookie blocking policies are often ineffective at

     

       1555
       1555
       +
          achieving their privacy goals if servers attempt to work around their

     

       1556
       1556
       +
          restrictions to track users.  In particular, two collaborating

     

       1557
       1557
       +
          servers can often track users without using cookies at all by

     

       1558
       1558
       +
          injecting identifying information into dynamic URLs.

     

       1559
       1559
       +
       

     

       1560
       1560
       +
       7.2.  User Controls

     

       1561
       1561
       +
       

     

       1562
       1562
       +
          User agents SHOULD provide users with a mechanism for managing the

     

       1563
       1563
       +
          cookies stored in the cookie store.  For example, a user agent might

     

       1564
       1564
       +
          let users delete all cookies received during a specified time period

     

       1565
       1565
       +
       

     

       1566
       1566
       +
       

     

       1567
       1567
       +
       

     

       1568
       1568
       +
       

     

       1569
       1569
       +
       

     

       1570
       1570
       +
       Barth                        Standards Track                   [Page 28]

     

       1571
       1571
       +
       

     

       1572
       1572
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1573
       1573
       +
       

     

       1574
       1574
       +
       

     

       1575
       1575
       +
          or all the cookies related to a particular domain.  In addition, many

     

       1576
       1576
       +
          user agents include a user interface element that lets users examine

     

       1577
       1577
       +
          the cookies stored in their cookie store.

     

       1578
       1578
       +
       

     

       1579
       1579
       +
          User agents SHOULD provide users with a mechanism for disabling

     

       1580
       1580
       +
          cookies.  When cookies are disabled, the user agent MUST NOT include

     

       1581
       1581
       +
          a Cookie header in outbound HTTP requests and the user agent MUST NOT

     

       1582
       1582
       +
          process Set-Cookie headers in inbound HTTP responses.

     

       1583
       1583
       +
       

     

       1584
       1584
       +
          Some user agents provide users the option of preventing persistent

     

       1585
       1585
       +
          storage of cookies across sessions.  When configured thusly, user

     

       1586
       1586
       +
          agents MUST treat all received cookies as if the persistent-flag were

     

       1587
       1587
       +
          set to false.  Some popular user agents expose this functionality via

     

       1588
       1588
       +
          "private browsing" mode [Aggarwal2010].

     

       1589
       1589
       +
       

     

       1590
       1590
       +
          Some user agents provide users with the ability to approve individual

     

       1591
       1591
       +
          writes to the cookie store.  In many common usage scenarios, these

     

       1592
       1592
       +
          controls generate a large number of prompts.  However, some privacy-

     

       1593
       1593
       +
          conscious users find these controls useful nonetheless.

     

       1594
       1594
       +
       

     

       1595
       1595
       +
       7.3.  Expiration Dates

     

       1596
       1596
       +
       

     

       1597
       1597
       +
          Although servers can set the expiration date for cookies to the

     

       1598
       1598
       +
          distant future, most user agents do not actually retain cookies for

     

       1599
       1599
       +
          multiple decades.  Rather than choosing gratuitously long expiration

     

       1600
       1600
       +
          periods, servers SHOULD promote user privacy by selecting reasonable

     

       1601
       1601
       +
          cookie expiration periods based on the purpose of the cookie.  For

     

       1602
       1602
       +
          example, a typical session identifier might reasonably be set to

     

       1603
       1603
       +
          expire in two weeks.

     

       1604
       1604
       +
       

     

       1605
       1605
       +
       8.  Security Considerations

     

       1606
       1606
       +
       

     

       1607
       1607
       +
       8.1.  Overview

     

       1608
       1608
       +
       

     

       1609
       1609
       +
          Cookies have a number of security pitfalls.  This section overviews a

     

       1610
       1610
       +
          few of the more salient issues.

     

       1611
       1611
       +
       

     

       1612
       1612
       +
          In particular, cookies encourage developers to rely on ambient

     

       1613
       1613
       +
          authority for authentication, often becoming vulnerable to attacks

     

       1614
       1614
       +
          such as cross-site request forgery [CSRF].  Also, when storing

     

       1615
       1615
       +
          session identifiers in cookies, developers often create session

     

       1616
       1616
       +
          fixation vulnerabilities.

     

       1617
       1617
       +
       

     

       1618
       1618
       +
          Transport-layer encryption, such as that employed in HTTPS, is

     

       1619
       1619
       +
          insufficient to prevent a network attacker from obtaining or altering

     

       1620
       1620
       +
          a victim's cookies because the cookie protocol itself has various

     

       1621
       1621
       +
          vulnerabilities (see "Weak Confidentiality" and "Weak Integrity",

     

       1622
       1622
       +
       

     

       1623
       1623
       +
       

     

       1624
       1624
       +
       

     

       1625
       1625
       +
       

     

       1626
       1626
       +
       Barth                        Standards Track                   [Page 29]

     

       1627
       1627
       +
       

     

       1628
       1628
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1629
       1629
       +
       

     

       1630
       1630
       +
       

     

       1631
       1631
       +
          below).  In addition, by default, cookies do not provide

     

       1632
       1632
       +
          confidentiality or integrity from network attackers, even when used

     

       1633
       1633
       +
          in conjunction with HTTPS.

     

       1634
       1634
       +
       

     

       1635
       1635
       +
       8.2.  Ambient Authority

     

       1636
       1636
       +
       

     

       1637
       1637
       +
          A server that uses cookies to authenticate users can suffer security

     

       1638
       1638
       +
          vulnerabilities because some user agents let remote parties issue

     

       1639
       1639
       +
          HTTP requests from the user agent (e.g., via HTTP redirects or HTML

     

       1640
       1640
       +
          forms).  When issuing those requests, user agents attach cookies even

     

       1641
       1641
       +
          if the remote party does not know the contents of the cookies,

     

       1642
       1642
       +
          potentially letting the remote party exercise authority at an unwary

     

       1643
       1643
       +
          server.

     

       1644
       1644
       +
       

     

       1645
       1645
       +
          Although this security concern goes by a number of names (e.g.,

     

       1646
       1646
       +
          cross-site request forgery, confused deputy), the issue stems from

     

       1647
       1647
       +
          cookies being a form of ambient authority.  Cookies encourage server

     

       1648
       1648
       +
          operators to separate designation (in the form of URLs) from

     

       1649
       1649
       +
          authorization (in the form of cookies).  Consequently, the user agent

     

       1650
       1650
       +
          might supply the authorization for a resource designated by the

     

       1651
       1651
       +
          attacker, possibly causing the server or its clients to undertake

     

       1652
       1652
       +
          actions designated by the attacker as though they were authorized by

     

       1653
       1653
       +
          the user.

     

       1654
       1654
       +
       

     

       1655
       1655
       +
          Instead of using cookies for authorization, server operators might

     

       1656
       1656
       +
          wish to consider entangling designation and authorization by treating

     

       1657
       1657
       +
          URLs as capabilities.  Instead of storing secrets in cookies, this

     

       1658
       1658
       +
          approach stores secrets in URLs, requiring the remote entity to

     

       1659
       1659
       +
          supply the secret itself.  Although this approach is not a panacea,

     

       1660
       1660
       +
          judicious application of these principles can lead to more robust

     

       1661
       1661
       +
          security.

     

       1662
       1662
       +
       

     

       1663
       1663
       +
       8.3.  Clear Text

     

       1664
       1664
       +
       

     

       1665
       1665
       +
          Unless sent over a secure channel (such as TLS), the information in

     

       1666
       1666
       +
          the Cookie and Set-Cookie headers is transmitted in the clear.

     

       1667
       1667
       +
       

     

       1668
       1668
       +
          1.  All sensitive information conveyed in these headers is exposed to

     

       1669
       1669
       +
              an eavesdropper.

     

       1670
       1670
       +
       

     

       1671
       1671
       +
          2.  A malicious intermediary could alter the headers as they travel

     

       1672
       1672
       +
              in either direction, with unpredictable results.

     

       1673
       1673
       +
       

     

       1674
       1674
       +
          3.  A malicious client could alter the Cookie header before

     

       1675
       1675
       +
              transmission, with unpredictable results.

     

       1676
       1676
       +
       

     

       1677
       1677
       +
       

     

       1678
       1678
       +
       

     

       1679
       1679
       +
       

     

       1680
       1680
       +
       

     

       1681
       1681
       +
       

     

       1682
       1682
       +
       Barth                        Standards Track                   [Page 30]

     

       1683
       1683
       +
       

     

       1684
       1684
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1685
       1685
       +
       

     

       1686
       1686
       +
       

     

       1687
       1687
       +
          Servers SHOULD encrypt and sign the contents of cookies (using

     

       1688
       1688
       +
          whatever format the server desires) when transmitting them to the

     

       1689
       1689
       +
          user agent (even when sending the cookies over a secure channel).

     

       1690
       1690
       +
          However, encrypting and signing cookie contents does not prevent an

     

       1691
       1691
       +
          attacker from transplanting a cookie from one user agent to another

     

       1692
       1692
       +
          or from replaying the cookie at a later time.

     

       1693
       1693
       +
       

     

       1694
       1694
       +
          In addition to encrypting and signing the contents of every cookie,

     

       1695
       1695
       +
          servers that require a higher level of security SHOULD use the Cookie

     

       1696
       1696
       +
          and Set-Cookie headers only over a secure channel.  When using

     

       1697
       1697
       +
          cookies over a secure channel, servers SHOULD set the Secure

     

       1698
       1698
       +
          attribute (see Section 4.1.2.5) for every cookie.  If a server does

     

       1699
       1699
       +
          not set the Secure attribute, the protection provided by the secure

     

       1700
       1700
       +
          channel will be largely moot.

     

       1701
       1701
       +
       

     

       1702
       1702
       +
          For example, consider a webmail server that stores a session

     

       1703
       1703
       +
          identifier in a cookie and is typically accessed over HTTPS.  If the

     

       1704
       1704
       +
          server does not set the Secure attribute on its cookies, an active

     

       1705
       1705
       +
          network attacker can intercept any outbound HTTP request from the

     

       1706
       1706
       +
          user agent and redirect that request to the webmail server over HTTP.

     

       1707
       1707
       +
          Even if the webmail server is not listening for HTTP connections, the

     

       1708
       1708
       +
          user agent will still include cookies in the request.  The active

     

       1709
       1709
       +
          network attacker can intercept these cookies, replay them against the

     

       1710
       1710
       +
          server, and learn the contents of the user's email.  If, instead, the

     

       1711
       1711
       +
          server had set the Secure attribute on its cookies, the user agent

     

       1712
       1712
       +
          would not have included the cookies in the clear-text request.

     

       1713
       1713
       +
       

     

       1714
       1714
       +
       8.4.  Session Identifiers

     

       1715
       1715
       +
       

     

       1716
       1716
       +
          Instead of storing session information directly in a cookie (where it

     

       1717
       1717
       +
          might be exposed to or replayed by an attacker), servers commonly

     

       1718
       1718
       +
          store a nonce (or "session identifier") in a cookie.  When the server

     

       1719
       1719
       +
          receives an HTTP request with a nonce, the server can look up state

     

       1720
       1720
       +
          information associated with the cookie using the nonce as a key.

     

       1721
       1721
       +
       

     

       1722
       1722
       +
          Using session identifier cookies limits the damage an attacker can

     

       1723
       1723
       +
          cause if the attacker learns the contents of a cookie because the

     

       1724
       1724
       +
          nonce is useful only for interacting with the server (unlike non-

     

       1725
       1725
       +
          nonce cookie content, which might itself be sensitive).  Furthermore,

     

       1726
       1726
       +
          using a single nonce prevents an attacker from "splicing" together

     

       1727
       1727
       +
          cookie content from two interactions with the server, which could

     

       1728
       1728
       +
          cause the server to behave unexpectedly.

     

       1729
       1729
       +
       

     

       1730
       1730
       +
          Using session identifiers is not without risk.  For example, the

     

       1731
       1731
       +
          server SHOULD take care to avoid "session fixation" vulnerabilities.

     

       1732
       1732
       +
          A session fixation attack proceeds in three steps.  First, the

     

       1733
       1733
       +
          attacker transplants a session identifier from his or her user agent

     

       1734
       1734
       +
          to the victim's user agent.  Second, the victim uses that session

     

       1735
       1735
       +
       

     

       1736
       1736
       +
       

     

       1737
       1737
       +
       

     

       1738
       1738
       +
       Barth                        Standards Track                   [Page 31]

     

       1739
       1739
       +
       

     

       1740
       1740
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1741
       1741
       +
       

     

       1742
       1742
       +
       

     

       1743
       1743
       +
          identifier to interact with the server, possibly imbuing the session

     

       1744
       1744
       +
          identifier with the user's credentials or confidential information.

     

       1745
       1745
       +
          Third, the attacker uses the session identifier to interact with

     

       1746
       1746
       +
          server directly, possibly obtaining the user's authority or

     

       1747
       1747
       +
          confidential information.

     

       1748
       1748
       +
       

     

       1749
       1749
       +
       8.5.  Weak Confidentiality

     

       1750
       1750
       +
       

     

       1751
       1751
       +
          Cookies do not provide isolation by port.  If a cookie is readable by

     

       1752
       1752
       +
          a service running on one port, the cookie is also readable by a

     

       1753
       1753
       +
          service running on another port of the same server.  If a cookie is

     

       1754
       1754
       +
          writable by a service on one port, the cookie is also writable by a

     

       1755
       1755
       +
          service running on another port of the same server.  For this reason,

     

       1756
       1756
       +
          servers SHOULD NOT both run mutually distrusting services on

     

       1757
       1757
       +
          different ports of the same host and use cookies to store security-

     

       1758
       1758
       +
          sensitive information.

     

       1759
       1759
       +
       

     

       1760
       1760
       +
          Cookies do not provide isolation by scheme.  Although most commonly

     

       1761
       1761
       +
          used with the http and https schemes, the cookies for a given host

     

       1762
       1762
       +
          might also be available to other schemes, such as ftp and gopher.

     

       1763
       1763
       +
          Although this lack of isolation by scheme is most apparent in non-

     

       1764
       1764
       +
          HTTP APIs that permit access to cookies (e.g., HTML's document.cookie

     

       1765
       1765
       +
          API), the lack of isolation by scheme is actually present in

     

       1766
       1766
       +
          requirements for processing cookies themselves (e.g., consider

     

       1767
       1767
       +
          retrieving a URI with the gopher scheme via HTTP).

     

       1768
       1768
       +
       

     

       1769
       1769
       +
          Cookies do not always provide isolation by path.  Although the

     

       1770
       1770
       +
          network-level protocol does not send cookies stored for one path to

     

       1771
       1771
       +
          another, some user agents expose cookies via non-HTTP APIs, such as

     

       1772
       1772
       +
          HTML's document.cookie API.  Because some of these user agents (e.g.,

     

       1773
       1773
       +
          web browsers) do not isolate resources received from different paths,

     

       1774
       1774
       +
          a resource retrieved from one path might be able to access cookies

     

       1775
       1775
       +
          stored for another path.

     

       1776
       1776
       +
       

     

       1777
       1777
       +
       8.6.  Weak Integrity

     

       1778
       1778
       +
       

     

       1779
       1779
       +
          Cookies do not provide integrity guarantees for sibling domains (and

     

       1780
       1780
       +
          their subdomains).  For example, consider foo.example.com and

     

       1781
       1781
       +
          bar.example.com.  The foo.example.com server can set a cookie with a

     

       1782
       1782
       +
          Domain attribute of "example.com" (possibly overwriting an existing

     

       1783
       1783
       +
          "example.com" cookie set by bar.example.com), and the user agent will

     

       1784
       1784
       +
          include that cookie in HTTP requests to bar.example.com.  In the

     

       1785
       1785
       +
          worst case, bar.example.com will be unable to distinguish this cookie

     

       1786
       1786
       +
          from a cookie it set itself.  The foo.example.com server might be

     

       1787
       1787
       +
          able to leverage this ability to mount an attack against

     

       1788
       1788
       +
          bar.example.com.

     

       1789
       1789
       +
       

     

       1790
       1790
       +
       

     

       1791
       1791
       +
       

     

       1792
       1792
       +
       

     

       1793
       1793
       +
       

     

       1794
       1794
       +
       Barth                        Standards Track                   [Page 32]

     

       1795
       1795
       +
       

     

       1796
       1796
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1797
       1797
       +
       

     

       1798
       1798
       +
       

     

       1799
       1799
       +
          Even though the Set-Cookie header supports the Path attribute, the

     

       1800
       1800
       +
          Path attribute does not provide any integrity protection because the

     

       1801
       1801
       +
          user agent will accept an arbitrary Path attribute in a Set-Cookie

     

       1802
       1802
       +
          header.  For example, an HTTP response to a request for

     

       1803
       1803
       +
          http://example.com/foo/bar can set a cookie with a Path attribute of

     

       1804
       1804
       +
          "/qux".  Consequently, servers SHOULD NOT both run mutually

     

       1805
       1805
       +
          distrusting services on different paths of the same host and use

     

       1806
       1806
       +
          cookies to store security-sensitive information.

     

       1807
       1807
       +
       

     

       1808
       1808
       +
          An active network attacker can also inject cookies into the Cookie

     

       1809
       1809
       +
          header sent to https://example.com/ by impersonating a response from

     

       1810
       1810
       +
          http://example.com/ and injecting a Set-Cookie header.  The HTTPS

     

       1811
       1811
       +
          server at example.com will be unable to distinguish these cookies

     

       1812
       1812
       +
          from cookies that it set itself in an HTTPS response.  An active

     

       1813
       1813
       +
          network attacker might be able to leverage this ability to mount an

     

       1814
       1814
       +
          attack against example.com even if example.com uses HTTPS

     

       1815
       1815
       +
          exclusively.

     

       1816
       1816
       +
       

     

       1817
       1817
       +
          Servers can partially mitigate these attacks by encrypting and

     

       1818
       1818
       +
          signing the contents of their cookies.  However, using cryptography

     

       1819
       1819
       +
          does not mitigate the issue completely because an attacker can replay

     

       1820
       1820
       +
          a cookie he or she received from the authentic example.com server in

     

       1821
       1821
       +
          the user's session, with unpredictable results.

     

       1822
       1822
       +
       

     

       1823
       1823
       +
          Finally, an attacker might be able to force the user agent to delete

     

       1824
       1824
       +
          cookies by storing a large number of cookies.  Once the user agent

     

       1825
       1825
       +
          reaches its storage limit, the user agent will be forced to evict

     

       1826
       1826
       +
          some cookies.  Servers SHOULD NOT rely upon user agents retaining

     

       1827
       1827
       +
          cookies.

     

       1828
       1828
       +
       

     

       1829
       1829
       +
       8.7.  Reliance on DNS

     

       1830
       1830
       +
       

     

       1831
       1831
       +
          Cookies rely upon the Domain Name System (DNS) for security.  If the

     

       1832
       1832
       +
          DNS is partially or fully compromised, the cookie protocol might fail

     

       1833
       1833
       +
          to provide the security properties required by applications.

     

       1834
       1834
       +
       

     

       1835
       1835
       +
       9.  IANA Considerations

     

       1836
       1836
       +
       

     

       1837
       1837
       +
          The permanent message header field registry (see [RFC3864]) has been

     

       1838
       1838
       +
          updated with the following registrations.

     

       1839
       1839
       +
       

     

       1840
       1840
       +
       

     

       1841
       1841
       +
       

     

       1842
       1842
       +
       

     

       1843
       1843
       +
       

     

       1844
       1844
       +
       

     

       1845
       1845
       +
       

     

       1846
       1846
       +
       

     

       1847
       1847
       +
       

     

       1848
       1848
       +
       

     

       1849
       1849
       +
       

     

       1850
       1850
       +
       Barth                        Standards Track                   [Page 33]

     

       1851
       1851
       +
       

     

       1852
       1852
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1853
       1853
       +
       

     

       1854
       1854
       +
       

     

       1855
       1855
       +
       9.1.  Cookie

     

       1856
       1856
       +
       

     

       1857
       1857
       +
          Header field name: Cookie

     

       1858
       1858
       +
       

     

       1859
       1859
       +
          Applicable protocol: http

     

       1860
       1860
       +
       

     

       1861
       1861
       +
          Status: standard

     

       1862
       1862
       +
       

     

       1863
       1863
       +
          Author/Change controller: IETF

     

       1864
       1864
       +
       

     

       1865
       1865
       +
          Specification document: this specification (Section 5.4)

     

       1866
       1866
       +
       

     

       1867
       1867
       +
       9.2.  Set-Cookie

     

       1868
       1868
       +
       

     

       1869
       1869
       +
          Header field name: Set-Cookie

     

       1870
       1870
       +
       

     

       1871
       1871
       +
          Applicable protocol: http

     

       1872
       1872
       +
       

     

       1873
       1873
       +
          Status: standard

     

       1874
       1874
       +
       

     

       1875
       1875
       +
          Author/Change controller: IETF

     

       1876
       1876
       +
       

     

       1877
       1877
       +
          Specification document: this specification (Section 5.2)

     

       1878
       1878
       +
       

     

       1879
       1879
       +
       9.3.  Cookie2

     

       1880
       1880
       +
       

     

       1881
       1881
       +
          Header field name: Cookie2

     

       1882
       1882
       +
       

     

       1883
       1883
       +
          Applicable protocol: http

     

       1884
       1884
       +
       

     

       1885
       1885
       +
          Status: obsoleted

     

       1886
       1886
       +
       

     

       1887
       1887
       +
          Author/Change controller: IETF

     

       1888
       1888
       +
       

     

       1889
       1889
       +
          Specification document: [RFC2965]

     

       1890
       1890
       +
       

     

       1891
       1891
       +
       9.4.  Set-Cookie2

     

       1892
       1892
       +
       

     

       1893
       1893
       +
          Header field name: Set-Cookie2

     

       1894
       1894
       +
       

     

       1895
       1895
       +
          Applicable protocol: http

     

       1896
       1896
       +
       

     

       1897
       1897
       +
          Status: obsoleted

     

       1898
       1898
       +
       

     

       1899
       1899
       +
          Author/Change controller: IETF

     

       1900
       1900
       +
       

     

       1901
       1901
       +
          Specification document: [RFC2965]

     

       1902
       1902
       +
       

     

       1903
       1903
       +
       

     

       1904
       1904
       +
       

     

       1905
       1905
       +
       

     

       1906
       1906
       +
       Barth                        Standards Track                   [Page 34]

     

       1907
       1907
       +
       

     

       1908
       1908
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1909
       1909
       +
       

     

       1910
       1910
       +
       

     

       1911
       1911
       +
       10.  References

     

       1912
       1912
       +
       

     

       1913
       1913
       +
       10.1.  Normative References

     

       1914
       1914
       +
       

     

       1915
       1915
       +
          [RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",

     

       1916
       1916
       +
                     STD 13, RFC 1034, November 1987.

     

       1917
       1917
       +
       

     

       1918
       1918
       +
          [RFC1123]  Braden, R., "Requirements for Internet Hosts - Application

     

       1919
       1919
       +
                     and Support", STD 3, RFC 1123, October 1989.

     

       1920
       1920
       +
       

     

       1921
       1921
       +
          [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate

     

       1922
       1922
       +
                     Requirement Levels", BCP 14, RFC 2119, March 1997.

     

       1923
       1923
       +
       

     

       1924
       1924
       +
          [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,

     

       1925
       1925
       +
                     Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext

     

       1926
       1926
       +
                     Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

     

       1927
       1927
       +
       

     

       1928
       1928
       +
          [RFC3490]  Faltstrom, P., Hoffman, P., and A. Costello,

     

       1929
       1929
       +
                     "Internationalizing Domain Names in Applications (IDNA)",

     

       1930
       1930
       +
                     RFC 3490, March 2003.

     

       1931
       1931
       +
       

     

       1932
       1932
       +
                     See Section 6.3 for an explanation why the normative

     

       1933
       1933
       +
                     reference to an obsoleted specification is needed.

     

       1934
       1934
       +
       

     

       1935
       1935
       +
          [RFC4790]  Newman, C., Duerst, M., and A. Gulbrandsen, "Internet

     

       1936
       1936
       +
                     Application Protocol Collation Registry", RFC 4790,

     

       1937
       1937
       +
                     March 2007.

     

       1938
       1938
       +
       

     

       1939
       1939
       +
          [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax

     

       1940
       1940
       +
                     Specifications: ABNF", STD 68, RFC 5234, January 2008.

     

       1941
       1941
       +
       

     

       1942
       1942
       +
          [RFC5890]  Klensin, J., "Internationalized Domain Names for

     

       1943
       1943
       +
                     Applications (IDNA): Definitions and Document Framework",

     

       1944
       1944
       +
                     RFC 5890, August 2010.

     

       1945
       1945
       +
       

     

       1946
       1946
       +
          [USASCII]  American National Standards Institute, "Coded Character

     

       1947
       1947
       +
                     Set -- 7-bit American Standard Code for Information

     

       1948
       1948
       +
                     Interchange", ANSI X3.4, 1986.

     

       1949
       1949
       +
       

     

       1950
       1950
       +
       10.2.  Informative References

     

       1951
       1951
       +
       

     

       1952
       1952
       +
          [RFC2109]  Kristol, D. and L. Montulli, "HTTP State Management

     

       1953
       1953
       +
                     Mechanism", RFC 2109, February 1997.

     

       1954
       1954
       +
       

     

       1955
       1955
       +
          [RFC2965]  Kristol, D. and L. Montulli, "HTTP State Management

     

       1956
       1956
       +
                     Mechanism", RFC 2965, October 2000.

     

       1957
       1957
       +
       

     

       1958
       1958
       +
       

     

       1959
       1959
       +
       

     

       1960
       1960
       +
       

     

       1961
       1961
       +
       

     

       1962
       1962
       +
       Barth                        Standards Track                   [Page 35]

     

       1963
       1963
       +
       

     

       1964
       1964
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       1965
       1965
       +
       

     

       1966
       1966
       +
       

     

       1967
       1967
       +
          [RFC2818]  Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.

     

       1968
       1968
       +
       

     

       1969
       1969
       +
          [Netscape] Netscape Communications Corp., "Persistent Client State --

     

       1970
       1970
       +
                     HTTP Cookies", 1999, <http://web.archive.org/web/

     

       1971
       1971
       +
                     20020803110822/http://wp.netscape.com/newsref/std/

     

       1972
       1972
       +
                     cookie_spec.html>.

     

       1973
       1973
       +
       

     

       1974
       1974
       +
          [Kri2001]  Kristol, D., "HTTP Cookies: Standards, Privacy, and

     

       1975
       1975
       +
                     Politics", ACM Transactions on Internet Technology Vol. 1,

     

       1976
       1976
       +
                     #2, November 2001, <http://arxiv.org/abs/cs.SE/0105018>.

     

       1977
       1977
       +
       

     

       1978
       1978
       +
          [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO

     

       1979
       1979
       +
                     10646", STD 63, RFC 3629, November 2003.

     

       1980
       1980
       +
       

     

       1981
       1981
       +
          [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data

     

       1982
       1982
       +
                     Encodings", RFC 4648, October 2006.

     

       1983
       1983
       +
       

     

       1984
       1984
       +
          [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration

     

       1985
       1985
       +
                     Procedures for Message Header Fields", BCP 90, RFC 3864,

     

       1986
       1986
       +
                     September 2004.

     

       1987
       1987
       +
       

     

       1988
       1988
       +
          [RFC5895]  Resnick, P. and P. Hoffman, "Mapping Characters for

     

       1989
       1989
       +
                     Internationalized Domain Names in Applications (IDNA)

     

       1990
       1990
       +
                     2008", RFC 5895, September 2010.

     

       1991
       1991
       +
       

     

       1992
       1992
       +
          [UTS46]    Davis, M. and M. Suignard, "Unicode IDNA Compatibility

     

       1993
       1993
       +
                     Processing", Unicode Technical Standards # 46, 2010,

     

       1994
       1994
       +
                     <http://unicode.org/reports/tr46/>.

     

       1995
       1995
       +
       

     

       1996
       1996
       +
          [CSRF]     Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses

     

       1997
       1997
       +
                     for Cross-Site Request Forgery", 2008,

     

       1998
       1998
       +
                     <http://portal.acm.org/citation.cfm?id=1455770.1455782>.

     

       1999
       1999
       +
       

     

       2000
       2000
       +
          [Aggarwal2010]

     

       2001
       2001
       +
                     Aggarwal, G., Burzstein, E., Jackson, C., and D. Boneh,

     

       2002
       2002
       +
                     "An Analysis of Private Browsing Modes in Modern

     

       2003
       2003
       +
                     Browsers", 2010, <http://www.usenix.org/events/sec10/tech/

     

       2004
       2004
       +
                     full_papers/Aggarwal.pdf>.

     

       2005
       2005
       +
       

     

       2006
       2006
       +
       

     

       2007
       2007
       +
       

     

       2008
       2008
       +
       

     

       2009
       2009
       +
       

     

       2010
       2010
       +
       

     

       2011
       2011
       +
       

     

       2012
       2012
       +
       

     

       2013
       2013
       +
       

     

       2014
       2014
       +
       

     

       2015
       2015
       +
       

     

       2016
       2016
       +
       

     

       2017
       2017
       +
       

     

       2018
       2018
       +
       Barth                        Standards Track                   [Page 36]

     

       2019
       2019
       +
       

     

       2020
       2020
       +
       RFC 6265             HTTP State Management Mechanism          April 2011

     

       2021
       2021
       +
       

     

       2022
       2022
       +
       

     

       2023
       2023
       +
       Appendix A.  Acknowledgements

     

       2024
       2024
       +
       

     

       2025
       2025
       +
          This document borrows heavily from RFC 2109 [RFC2109].  We are

     

       2026
       2026
       +
          indebted to David M. Kristol and Lou Montulli for their efforts to

     

       2027
       2027
       +
          specify cookies.  David M. Kristol, in particular, provided

     

       2028
       2028
       +
          invaluable advice on navigating the IETF process.  We would also like

     

       2029
       2029
       +
          to thank Thomas Broyer, Tyler Close, Alissa Cooper, Bil Corry,

     

       2030
       2030
       +
          corvid, Lisa Dusseault, Roy T. Fielding, Blake Frantz, Anne van

     

       2031
       2031
       +
          Kesteren, Eran Hammer-Lahav, Jeff Hodges, Bjoern Hoehrmann, Achim

     

       2032
       2032
       +
          Hoffmann, Georg Koppen, Dean McNamee, Alexey Melnikov, Mark Miller,

     

       2033
       2033
       +
          Mark Pauley, Yngve N. Pettersen, Julian Reschke, Peter Saint-Andre,

     

       2034
       2034
       +
          Mark Seaborn, Maciej Stachowiak, Daniel Stenberg, Tatsuhiro

     

       2035
       2035
       +
          Tsujikawa, David Wagner, Dan Winship, and Dan Witte for their

     

       2036
       2036
       +
          valuable feedback on this document.

     

       2037
       2037
       +
       

     

       2038
       2038
       +
       Author's Address

     

       2039
       2039
       +
       

     

       2040
       2040
       +
          Adam Barth

     

       2041
       2041
       +
          University of California, Berkeley

     

       2042
       2042
       +
       

     

       2043
       2043
       +
          EMail: abarth@eecs.berkeley.edu

     

       2044
       2044
       +
          URI:   http://www.adambarth.com/

     

       2045
       2045
       +
       

     

       2046
       2046
       +
       

     

       2047
       2047
       +
       

     

       2048
       2048
       +
       

     

       2049
       2049
       +
       

     

       2050
       2050
       +
       

     

       2051
       2051
       +
       

     

       2052
       2052
       +
       

     

       2053
       2053
       +
       

     

       2054
       2054
       +
       

     

       2055
       2055
       +
       

     

       2056
       2056
       +
       

     

       2057
       2057
       +
       

     

       2058
       2058
       +
       

     

       2059
       2059
       +
       

     

       2060
       2060
       +
       

     

       2061
       2061
       +
       

     

       2062
       2062
       +
       

     

       2063
       2063
       +
       

     

       2064
       2064
       +
       

     

       2065
       2065
       +
       

     

       2066
       2066
       +
       

     

       2067
       2067
       +
       

     

       2068
       2068
       +
       

     

       2069
       2069
       +
       

     

       2070
       2070
       +
       

     

       2071
       2071
       +
       

     

       2072
       2072
       +
       

     

       2073
       2073
       +
       

     

       2074
       2074
       +
       Barth                        Standards Track                   [Page 37]

     

       2075
       2075
       +

+10 -1

test/dune

···

       1
       1
        
       (test

     

       2
       2
        
        (name test_cookeio)

     

       3
       3
       -
        (libraries cookeio alcotest eio eio.unix eio_main ptime)

     

       3
       3
       +
        (libraries

     

       4
       4
       +
         cookeio

     

       5
       5
       +
         cookeio_jar

     

       6
       6
       +
         alcotest

     

       7
       7
       +
         eio

     

       8
       8
       +
         eio.unix

     

       9
       9
       +
         eio_main

     

       10
       10
       +
         eio.mock

     

       11
       11
       +
         ptime

     

       12
       12
       +
         str)

     

       4
       13
        
        (deps cookies.txt))

+3040 -45

test/test_cookeio.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
         Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.

     

       3
       3
       +
         SPDX-License-Identifier: ISC

     

       4
       4
       +
        ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       open Cookeio

     

       7
       7
       +
       open Cookeio_jar

     

       8
       8
       +
       

     

       9
       9
       +
       (* Testable helpers for Priority 2 types *)

     

       10
       10
       +
       let expiration_testable : Cookeio.Expiration.t Alcotest.testable =

     

       11
       11
       +
         Alcotest.testable Cookeio.Expiration.pp Cookeio.Expiration.equal

     

       12
       12
       +
       

     

       13
       13
       +
       let span_testable : Ptime.Span.t Alcotest.testable =

     

       14
       14
       +
         Alcotest.testable Ptime.Span.pp Ptime.Span.equal

     

       15
       15
       +
       

     

       16
       16
       +
       let same_site_testable : Cookeio.SameSite.t Alcotest.testable =

     

       17
       17
       +
         Alcotest.testable Cookeio.SameSite.pp Cookeio.SameSite.equal

     

       2
       18
        
       

     

       3
       19
        
       let cookie_testable : Cookeio.t Alcotest.testable =

     

       4
       20
        
         Alcotest.testable

     

       5
       21
        
           (fun ppf c ->

     

       6
       22
        
             Format.fprintf ppf

     

       7
       23
        
               "{ name=%S; value=%S; domain=%S; path=%S; secure=%b; http_only=%b; \

     

       8
       8
       -
                expires=%a; same_site=%a }"

     

       9
       9
       -
               (Cookeio.name c) (Cookeio.value c) (Cookeio.domain c) (Cookeio.path c) (Cookeio.secure c) (Cookeio.http_only c)

     

       10
       10
       -
               (Format.pp_print_option Ptime.pp)

     

       24
       24
       +
                partitioned=%b; expires=%a; max_age=%a; same_site=%a }"

     

       25
       25
       +
               (Cookeio.name c) (Cookeio.value c) (Cookeio.domain c) (Cookeio.path c)

     

       26
       26
       +
               (Cookeio.secure c) (Cookeio.http_only c) (Cookeio.partitioned c)

     

       27
       27
       +
               (Format.pp_print_option (fun ppf e ->

     

       28
       28
       +
                    match e with

     

       29
       29
       +
                    | `Session -> Format.pp_print_string ppf "Session"

     

       30
       30
       +
                    | `DateTime t -> Format.fprintf ppf "DateTime(%a)" Ptime.pp t))

     

       11
       31
        
               (Cookeio.expires c)

     

       32
       32
       +
               (Format.pp_print_option Ptime.Span.pp)

     

       33
       33
       +
               (Cookeio.max_age c)

     

       12
       34
        
               (Format.pp_print_option (fun ppf -> function

     

       13
       35
        
                 | `Strict -> Format.pp_print_string ppf "Strict"

     

       14
       36
        
                 | `Lax -> Format.pp_print_string ppf "Lax"

     

       15
       37
        
                 | `None -> Format.pp_print_string ppf "None"))

     

       16
       38
        
               (Cookeio.same_site c))

     

       17
       39
        
           (fun c1 c2 ->

     

       18
       18
       -
             Cookeio.name c1 = Cookeio.name c2 && Cookeio.value c1 = Cookeio.value c2 && Cookeio.domain c1 = Cookeio.domain c2

     

       19
       19
       -
             && Cookeio.path c1 = Cookeio.path c2 && Cookeio.secure c1 = Cookeio.secure c2

     

       40
       40
       +
             let expires_equal e1 e2 =

     

       41
       41
       +
               match (e1, e2) with

     

       42
       42
       +
               | None, None -> true

     

       43
       43
       +
               | Some `Session, Some `Session -> true

     

       44
       44
       +
               | Some (`DateTime t1), Some (`DateTime t2) -> Ptime.equal t1 t2

     

       45
       45
       +
               | _ -> false

     

       46
       46
       +
             in

     

       47
       47
       +
             Cookeio.name c1 = Cookeio.name c2

     

       48
       48
       +
             && Cookeio.value c1 = Cookeio.value c2

     

       49
       49
       +
             && Cookeio.domain c1 = Cookeio.domain c2

     

       50
       50
       +
             && Cookeio.path c1 = Cookeio.path c2

     

       51
       51
       +
             && Cookeio.secure c1 = Cookeio.secure c2

     

       20
       52
        
             && Cookeio.http_only c1 = Cookeio.http_only c2

     

       21
       21
       -
             && Option.equal Ptime.equal (Cookeio.expires c1) (Cookeio.expires c2)

     

       53
       53
       +
             && Cookeio.partitioned c1 = Cookeio.partitioned c2

     

       54
       54
       +
             && expires_equal (Cookeio.expires c1) (Cookeio.expires c2)

     

       55
       55
       +
             && Option.equal Ptime.Span.equal (Cookeio.max_age c1) (Cookeio.max_age c2)

     

       22
       56
        
             && Option.equal ( = ) (Cookeio.same_site c1) (Cookeio.same_site c2))

     

       23
       57
        
       

     

       24
       58
        
       let test_load_mozilla_cookies env =

     
···

       49
       83
        
       

     

       50
       84
        
         (* Test cookie-1: session cookie on exact domain *)

     

       51
       85
        
         let cookie1 = find_cookie "cookie-1" in

     

       52
       52
       -
         Alcotest.(check string) "cookie-1 domain" "example.com" (Cookeio.domain cookie1);

     

       86
       86
       +
         Alcotest.(check string)

     

       87
       87
       +
           "cookie-1 domain" "example.com" (Cookeio.domain cookie1);

     

       53
       88
        
         Alcotest.(check string) "cookie-1 path" "/foo/" (Cookeio.path cookie1);

     

       54
       89
        
         Alcotest.(check string) "cookie-1 name" "cookie-1" (Cookeio.name cookie1);

     

       55
       90
        
         Alcotest.(check string) "cookie-1 value" "v$1" (Cookeio.value cookie1);

     

       56
       91
        
         Alcotest.(check bool) "cookie-1 secure" false (Cookeio.secure cookie1);

     

       57
       92
        
         Alcotest.(check bool) "cookie-1 http_only" false (Cookeio.http_only cookie1);

     

       58
       58
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       93
       93
       +
         Alcotest.(check (option expiration_testable))

     

       59
       94
        
           "cookie-1 expires" None (Cookeio.expires cookie1);

     

       60
       95
        
         Alcotest.(

     

       61
       96
        
           check

     
···

       66
       101
        
                     | `Lax -> Format.pp_print_string ppf "Lax"

     

       67
       102
        
                     | `None -> Format.pp_print_string ppf "None")

     

       68
       103
        
                   ( = ))))

     

       69
       69
       -
           "cookie-1 same_site" None (Cookeio.same_site cookie1);

     

       104
       104
       +
           "cookie-1 same_site" None

     

       105
       105
       +
           (Cookeio.same_site cookie1);

     

       70
       106
        
       

     

       71
       107
        
         (* Test cookie-2: session cookie on subdomain pattern *)

     

       72
       108
        
         let cookie2 = find_cookie "cookie-2" in

     

       73
       73
       -
         Alcotest.(check string) "cookie-2 domain" ".example.com" (Cookeio.domain cookie2);

     

       109
       109
       +
         Alcotest.(check string)

     

       110
       110
       +
           "cookie-2 domain" "example.com" (Cookeio.domain cookie2);

     

       74
       111
        
         Alcotest.(check string) "cookie-2 path" "/foo/" (Cookeio.path cookie2);

     

       75
       112
        
         Alcotest.(check string) "cookie-2 name" "cookie-2" (Cookeio.name cookie2);

     

       76
       113
        
         Alcotest.(check string) "cookie-2 value" "v$2" (Cookeio.value cookie2);

     

       77
       114
        
         Alcotest.(check bool) "cookie-2 secure" false (Cookeio.secure cookie2);

     

       78
       115
        
         Alcotest.(check bool) "cookie-2 http_only" false (Cookeio.http_only cookie2);

     

       79
       79
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       116
       116
       +
         Alcotest.(check (option expiration_testable))

     

       80
       117
        
           "cookie-2 expires" None (Cookeio.expires cookie2);

     

       81
       118
        
       

     

       82
       119
        
         (* Test cookie-3: non-session cookie with expiry *)

     

       83
       120
        
         let cookie3 = find_cookie "cookie-3" in

     

       84
       121
        
         let expected_expiry = Ptime.of_float_s 1257894000.0 in

     

       85
       85
       -
         Alcotest.(check string) "cookie-3 domain" "example.com" (Cookeio.domain cookie3);

     

       122
       122
       +
         Alcotest.(check string)

     

       123
       123
       +
           "cookie-3 domain" "example.com" (Cookeio.domain cookie3);

     

       86
       124
        
         Alcotest.(check string) "cookie-3 path" "/foo/" (Cookeio.path cookie3);

     

       87
       125
        
         Alcotest.(check string) "cookie-3 name" "cookie-3" (Cookeio.name cookie3);

     

       88
       126
        
         Alcotest.(check string) "cookie-3 value" "v$3" (Cookeio.value cookie3);

     

       89
       127
        
         Alcotest.(check bool) "cookie-3 secure" false (Cookeio.secure cookie3);

     

       90
       128
        
         Alcotest.(check bool) "cookie-3 http_only" false (Cookeio.http_only cookie3);

     

       91
       91
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       92
       92
       -
           "cookie-3 expires" expected_expiry (Cookeio.expires cookie3);

     

       129
       129
       +
         begin match expected_expiry with

     

       130
       130
       +
         | Some t ->

     

       131
       131
       +
             Alcotest.(check (option expiration_testable))

     

       132
       132
       +
               "cookie-3 expires"

     

       133
       133
       +
               (Some (`DateTime t))

     

       134
       134
       +
               (Cookeio.expires cookie3)

     

       135
       135
       +
         | None -> Alcotest.fail "Expected expiry time for cookie-3"

     

       136
       136
       +
         end;

     

       93
       137
        
       

     

       94
       138
        
         (* Test cookie-4: another non-session cookie *)

     

       95
       139
        
         let cookie4 = find_cookie "cookie-4" in

     

       96
       96
       -
         Alcotest.(check string) "cookie-4 domain" "example.com" (Cookeio.domain cookie4);

     

       140
       140
       +
         Alcotest.(check string)

     

       141
       141
       +
           "cookie-4 domain" "example.com" (Cookeio.domain cookie4);

     

       97
       142
        
         Alcotest.(check string) "cookie-4 path" "/foo/" (Cookeio.path cookie4);

     

       98
       143
        
         Alcotest.(check string) "cookie-4 name" "cookie-4" (Cookeio.name cookie4);

     

       99
       144
        
         Alcotest.(check string) "cookie-4 value" "v$4" (Cookeio.value cookie4);

     

       100
       145
        
         Alcotest.(check bool) "cookie-4 secure" false (Cookeio.secure cookie4);

     

       101
       146
        
         Alcotest.(check bool) "cookie-4 http_only" false (Cookeio.http_only cookie4);

     

       102
       102
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       103
       103
       -
           "cookie-4 expires" expected_expiry (Cookeio.expires cookie4);

     

       147
       147
       +
         begin match expected_expiry with

     

       148
       148
       +
         | Some t ->

     

       149
       149
       +
             Alcotest.(check (option expiration_testable))

     

       150
       150
       +
               "cookie-4 expires"

     

       151
       151
       +
               (Some (`DateTime t))

     

       152
       152
       +
               (Cookeio.expires cookie4)

     

       153
       153
       +
         | None -> Alcotest.fail "Expected expiry time for cookie-4"

     

       154
       154
       +
         end;

     

       104
       155
        
       

     

       105
       156
        
         (* Test cookie-5: secure cookie *)

     

       106
       157
        
         let cookie5 = find_cookie "cookie-5" in

     

       107
       107
       -
         Alcotest.(check string) "cookie-5 domain" "example.com" (Cookeio.domain cookie5);

     

       158
       158
       +
         Alcotest.(check string)

     

       159
       159
       +
           "cookie-5 domain" "example.com" (Cookeio.domain cookie5);

     

       108
       160
        
         Alcotest.(check string) "cookie-5 path" "/foo/" (Cookeio.path cookie5);

     

       109
       161
        
         Alcotest.(check string) "cookie-5 name" "cookie-5" (Cookeio.name cookie5);

     

       110
       162
        
         Alcotest.(check string) "cookie-5 value" "v$5" (Cookeio.value cookie5);

     

       111
       163
        
         Alcotest.(check bool) "cookie-5 secure" true (Cookeio.secure cookie5);

     

       112
       164
        
         Alcotest.(check bool) "cookie-5 http_only" false (Cookeio.http_only cookie5);

     

       113
       113
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       114
       114
       -
           "cookie-5 expires" expected_expiry (Cookeio.expires cookie5)

     

       165
       165
       +
         begin match expected_expiry with

     

       166
       166
       +
         | Some t ->

     

       167
       167
       +
             Alcotest.(check (option expiration_testable))

     

       168
       168
       +
               "cookie-5 expires"

     

       169
       169
       +
               (Some (`DateTime t))

     

       170
       170
       +
               (Cookeio.expires cookie5)

     

       171
       171
       +
         | None -> Alcotest.fail "Expected expiry time for cookie-5"

     

       172
       172
       +
         end

     

       115
       173
        
       

     

       116
       174
        
       let test_load_from_file env =

     

       117
       175
        
         (* This test loads from the actual test/cookies.txt file using the load function *)

     
···

       129
       187
        
         (* Verify a few key cookies are loaded correctly *)

     

       130
       188
        
         let cookie1 = find_cookie "cookie-1" in

     

       131
       189
        
         Alcotest.(check string) "file cookie-1 value" "v$1" (Cookeio.value cookie1);

     

       132
       132
       -
         Alcotest.(check string) "file cookie-1 domain" "example.com" (Cookeio.domain cookie1);

     

       190
       190
       +
         Alcotest.(check string)

     

       191
       191
       +
           "file cookie-1 domain" "example.com" (Cookeio.domain cookie1);

     

       133
       192
        
         Alcotest.(check bool) "file cookie-1 secure" false (Cookeio.secure cookie1);

     

       134
       134
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       193
       193
       +
         Alcotest.(check (option expiration_testable))

     

       135
       194
        
           "file cookie-1 expires" None (Cookeio.expires cookie1);

     

       136
       195
        
       

     

       137
       196
        
         let cookie5 = find_cookie "cookie-5" in

     

       138
       197
        
         Alcotest.(check string) "file cookie-5 value" "v$5" (Cookeio.value cookie5);

     

       139
       198
        
         Alcotest.(check bool) "file cookie-5 secure" true (Cookeio.secure cookie5);

     

       140
       199
        
         let expected_expiry = Ptime.of_float_s 1257894000.0 in

     

       141
       141
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       142
       142
       -
           "file cookie-5 expires" expected_expiry (Cookeio.expires cookie5);

     

       200
       200
       +
         begin match expected_expiry with

     

       201
       201
       +
         | Some t ->

     

       202
       202
       +
             Alcotest.(check (option expiration_testable))

     

       203
       203
       +
               "file cookie-5 expires"

     

       204
       204
       +
               (Some (`DateTime t))

     

       205
       205
       +
               (Cookeio.expires cookie5)

     

       206
       206
       +
         | None -> Alcotest.fail "Expected expiry time for cookie-5"

     

       207
       207
       +
         end;

     

       143
       208
        
       

     

       144
       209
        
         (* Verify subdomain cookie *)

     

       145
       210
        
         let cookie2 = find_cookie "cookie-2" in

     

       146
       146
       -
         Alcotest.(check string) "file cookie-2 domain" ".example.com" (Cookeio.domain cookie2);

     

       147
       147
       -
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       211
       211
       +
         Alcotest.(check string)

     

       212
       212
       +
           "file cookie-2 domain" "example.com" (Cookeio.domain cookie2);

     

       213
       213
       +
         Alcotest.(check (option expiration_testable))

     

       148
       214
        
           "file cookie-2 expires" None (Cookeio.expires cookie2)

     

       149
       215
        
       

     

       150
       216
        
       let test_cookie_matching env =

     
···

       154
       220
        
         (* Add test cookies with different domain patterns *)

     

       155
       221
        
         let exact_cookie =

     

       156
       222
        
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"exact" ~value:"test1"

     

       157
       157
       -
             ~secure:false ~http_only:false ?expires:None ?same_site:None

     

       223
       223
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       158
       224
        
             ~creation_time:Ptime.epoch ~last_access:Ptime.epoch ()

     

       159
       225
        
         in

     

       160
       226
        
         let subdomain_cookie =

     

       161
       161
       -
           Cookeio.make ~domain:".example.com" ~path:"/" ~name:"subdomain" ~value:"test2"

     

       162
       162
       -
             ~secure:false ~http_only:false ?expires:None ?same_site:None

     

       163
       163
       -
             ~creation_time:Ptime.epoch ~last_access:Ptime.epoch ()

     

       227
       227
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"subdomain"

     

       228
       228
       +
             ~value:"test2" ~secure:false ~http_only:false ?expires:None

     

       229
       229
       +
             ?same_site:None ?max_age:None ~creation_time:Ptime.epoch

     

       230
       230
       +
             ~last_access:Ptime.epoch ()

     

       164
       231
        
         in

     

       165
       232
        
         let secure_cookie =

     

       166
       233
        
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"secure" ~value:"test3"

     

       167
       167
       -
             ~secure:true ~http_only:false ?expires:None ?same_site:None

     

       234
       234
       +
             ~secure:true ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       168
       235
        
             ~creation_time:Ptime.epoch ~last_access:Ptime.epoch ()

     

       169
       236
        
         in

     

       170
       237
        
       

     
···

       172
       239
        
         add_cookie jar subdomain_cookie;

     

       173
       240
        
         add_cookie jar secure_cookie;

     

       174
       241
        
       

     

       175
       175
       -
         (* Test exact domain matching *)

     

       242
       242
       +
         (* Test exact domain matching - all three cookies should match example.com *)

     

       176
       243
        
         let cookies_http =

     

       177
       244
        
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       178
       245
        
         in

     
···

       183
       250
        
         in

     

       184
       251
        
         Alcotest.(check int) "https cookies count" 3 (List.length cookies_https);

     

       185
       252
        
       

     

       186
       186
       -
         (* Test subdomain matching *)

     

       253
       253
       +
         (* Test subdomain matching - all cookies should match subdomains now *)

     

       187
       254
        
         let cookies_sub =

     

       188
       255
        
           get_cookies jar ~clock ~domain:"sub.example.com" ~path:"/" ~is_secure:false

     

       189
       256
        
         in

     

       190
       190
       -
         Alcotest.(check int) "subdomain cookies count" 1 (List.length cookies_sub);

     

       191
       191
       -
         let sub_cookie = List.hd cookies_sub in

     

       192
       192
       -
         Alcotest.(check string) "subdomain cookie name" "subdomain" (Cookeio.name sub_cookie)

     

       257
       257
       +
         Alcotest.(check int) "subdomain cookies count" 2 (List.length cookies_sub)

     

       193
       258
        
       

     

       194
       259
        
       let test_empty_jar env =

     

       195
       260
        
         let clock = Eio.Stdenv.clock env in

     
···

       209
       274
        
         let jar = create () in

     

       210
       275
        
       

     

       211
       276
        
         let test_cookie =

     

       212
       212
       -
           Cookeio.make ~domain:"example.com" ~path:"/test/" ~name:"test" ~value:"value"

     

       213
       213
       -
             ~secure:true ~http_only:false ?expires:(Ptime.of_float_s 1257894000.0)

     

       214
       214
       -
             ~same_site:`Strict ~creation_time:Ptime.epoch ~last_access:Ptime.epoch ()

     

       277
       277
       +
           let expires =

     

       278
       278
       +
             match Ptime.of_float_s 1257894000.0 with

     

       279
       279
       +
             | Some t -> Some (`DateTime t)

     

       280
       280
       +
             | None -> None

     

       281
       281
       +
           in

     

       282
       282
       +
           Cookeio.make ~domain:"example.com" ~path:"/test/" ~name:"test"

     

       283
       283
       +
             ~value:"value" ~secure:true ~http_only:false ?expires ~same_site:`Strict

     

       284
       284
       +
             ?max_age:None ~creation_time:Ptime.epoch ~last_access:Ptime.epoch ()

     

       215
       285
        
         in

     

       216
       286
        
       

     

       217
       287
        
         add_cookie jar test_cookie;

     
···

       225
       295
        
         let cookie2 = List.hd cookies2 in

     

       226
       296
        
         Alcotest.(check string) "round trip name" "test" (Cookeio.name cookie2);

     

       227
       297
        
         Alcotest.(check string) "round trip value" "value" (Cookeio.value cookie2);

     

       228
       228
       -
         Alcotest.(check string) "round trip domain" "example.com" (Cookeio.domain cookie2);

     

       298
       298
       +
         Alcotest.(check string)

     

       299
       299
       +
           "round trip domain" "example.com" (Cookeio.domain cookie2);

     

       229
       300
        
         Alcotest.(check string) "round trip path" "/test/" (Cookeio.path cookie2);

     

       230
       301
        
         Alcotest.(check bool) "round trip secure" true (Cookeio.secure cookie2);

     

       231
       302
        
         (* Note: http_only and same_site are lost in Mozilla format *)

     

       303
       303
       +
         begin match Ptime.of_float_s 1257894000.0 with

     

       304
       304
       +
         | Some t ->

     

       305
       305
       +
             Alcotest.(check (option expiration_testable))

     

       306
       306
       +
               "round trip expires"

     

       307
       307
       +
               (Some (`DateTime t))

     

       308
       308
       +
               (Cookeio.expires cookie2)

     

       309
       309
       +
         | None -> Alcotest.fail "Expected expiry time"

     

       310
       310
       +
         end

     

       311
       311
       +
       

     

       312
       312
       +
       let test_cookie_expiry_with_mock_clock () =

     

       313
       313
       +
         Eio_mock.Backend.run @@ fun () ->

     

       314
       314
       +
         let clock = Eio_mock.Clock.make () in

     

       315
       315
       +
       

     

       316
       316
       +
         (* Start at time 1000.0 for convenience *)

     

       317
       317
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       318
       318
       +
       

     

       319
       319
       +
         let jar = create () in

     

       320
       320
       +
       

     

       321
       321
       +
         (* Add a cookie that expires at time 1500.0 (expires in 500 seconds) *)

     

       322
       322
       +
         let expires_soon = Ptime.of_float_s 1500.0 |> Option.get in

     

       323
       323
       +
         let cookie1 =

     

       324
       324
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"expires_soon"

     

       325
       325
       +
             ~value:"value1" ~secure:false ~http_only:false

     

       326
       326
       +
             ~expires:(`DateTime expires_soon) ?same_site:None ?max_age:None

     

       327
       327
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       328
       328
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       329
       329
       +
             ()

     

       330
       330
       +
         in

     

       331
       331
       +
       

     

       332
       332
       +
         (* Add a cookie that expires at time 2000.0 (expires in 1000 seconds) *)

     

       333
       333
       +
         let expires_later = Ptime.of_float_s 2000.0 |> Option.get in

     

       334
       334
       +
         let cookie2 =

     

       335
       335
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"expires_later"

     

       336
       336
       +
             ~value:"value2" ~secure:false ~http_only:false

     

       337
       337
       +
             ~expires:(`DateTime expires_later) ?same_site:None ?max_age:None

     

       338
       338
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       339
       339
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       340
       340
       +
             ()

     

       341
       341
       +
         in

     

       342
       342
       +
       

     

       343
       343
       +
         (* Add a session cookie (no expiry) *)

     

       344
       344
       +
         let cookie3 =

     

       345
       345
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"session" ~value:"value3"

     

       346
       346
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       347
       347
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       348
       348
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       349
       349
       +
             ()

     

       350
       350
       +
         in

     

       351
       351
       +
       

     

       352
       352
       +
         add_cookie jar cookie1;

     

       353
       353
       +
         add_cookie jar cookie2;

     

       354
       354
       +
         add_cookie jar cookie3;

     

       355
       355
       +
       

     

       356
       356
       +
         Alcotest.(check int) "initial count" 3 (count jar);

     

       357
       357
       +
       

     

       358
       358
       +
         (* Advance time to 1600.0 - first cookie should expire *)

     

       359
       359
       +
         Eio_mock.Clock.set_time clock 1600.0;

     

       360
       360
       +
         clear_expired jar ~clock;

     

       361
       361
       +
       

     

       362
       362
       +
         Alcotest.(check int) "after first expiry" 2 (count jar);

     

       363
       363
       +
       

     

       364
       364
       +
         let cookies = get_all_cookies jar in

     

       365
       365
       +
         let names = List.map Cookeio.name cookies |> List.sort String.compare in

     

       366
       366
       +
         Alcotest.(check (list string))

     

       367
       367
       +
           "remaining cookies after 1600s"

     

       368
       368
       +
           [ "expires_later"; "session" ]

     

       369
       369
       +
           names;

     

       370
       370
       +
       

     

       371
       371
       +
         (* Advance time to 2100.0 - second cookie should expire *)

     

       372
       372
       +
         Eio_mock.Clock.set_time clock 2100.0;

     

       373
       373
       +
         clear_expired jar ~clock;

     

       374
       374
       +
       

     

       375
       375
       +
         Alcotest.(check int) "after second expiry" 1 (count jar);

     

       376
       376
       +
       

     

       377
       377
       +
         let remaining = get_all_cookies jar in

     

       378
       378
       +
         Alcotest.(check string)

     

       379
       379
       +
           "only session cookie remains" "session"

     

       380
       380
       +
           (Cookeio.name (List.hd remaining))

     

       381
       381
       +
       

     

       382
       382
       +
       let test_get_cookies_filters_expired () =

     

       383
       383
       +
         Eio_mock.Backend.run @@ fun () ->

     

       384
       384
       +
         let clock = Eio_mock.Clock.make () in

     

       385
       385
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       386
       386
       +
       

     

       387
       387
       +
         let jar = create () in

     

       388
       388
       +
       

     

       389
       389
       +
         (* Add an expired cookie (expired at time 500) *)

     

       390
       390
       +
         let expired = Ptime.of_float_s 500.0 |> Option.get in

     

       391
       391
       +
         let cookie_expired =

     

       392
       392
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"expired"

     

       393
       393
       +
             ~value:"old" ~secure:false ~http_only:false

     

       394
       394
       +
             ~expires:(`DateTime expired)

     

       395
       395
       +
             ~creation_time:(Ptime.of_float_s 100.0 |> Option.get)

     

       396
       396
       +
             ~last_access:(Ptime.of_float_s 100.0 |> Option.get)

     

       397
       397
       +
             ()

     

       398
       398
       +
         in

     

       399
       399
       +
       

     

       400
       400
       +
         (* Add a valid cookie (expires at time 2000) *)

     

       401
       401
       +
         let valid_time = Ptime.of_float_s 2000.0 |> Option.get in

     

       402
       402
       +
         let cookie_valid =

     

       403
       403
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"valid"

     

       404
       404
       +
             ~value:"current" ~secure:false ~http_only:false

     

       405
       405
       +
             ~expires:(`DateTime valid_time)

     

       406
       406
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       407
       407
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       408
       408
       +
             ()

     

       409
       409
       +
         in

     

       410
       410
       +
       

     

       411
       411
       +
         (* Add a session cookie (no expiry) *)

     

       412
       412
       +
         let cookie_session =

     

       413
       413
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"session"

     

       414
       414
       +
             ~value:"sess" ~secure:false ~http_only:false

     

       415
       415
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       416
       416
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       417
       417
       +
             ()

     

       418
       418
       +
         in

     

       419
       419
       +
       

     

       420
       420
       +
         add_cookie jar cookie_expired;

     

       421
       421
       +
         add_cookie jar cookie_valid;

     

       422
       422
       +
         add_cookie jar cookie_session;

     

       423
       423
       +
       

     

       424
       424
       +
         (* get_all_cookies returns all including expired (for inspection) *)

     

       425
       425
       +
         Alcotest.(check int) "get_all_cookies includes expired" 3

     

       426
       426
       +
           (List.length (get_all_cookies jar));

     

       427
       427
       +
       

     

       428
       428
       +
         (* get_cookies should automatically filter out expired cookies *)

     

       429
       429
       +
         let cookies =

     

       430
       430
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       431
       431
       +
         in

     

       432
       432
       +
         Alcotest.(check int) "get_cookies filters expired" 2 (List.length cookies);

     

       433
       433
       +
       

     

       434
       434
       +
         let names = List.map Cookeio.name cookies |> List.sort String.compare in

     

       435
       435
       +
         Alcotest.(check (list string))

     

       436
       436
       +
           "only non-expired cookies returned"

     

       437
       437
       +
           [ "session"; "valid" ]

     

       438
       438
       +
           names

     

       439
       439
       +
       

     

       440
       440
       +
       let test_max_age_parsing_with_mock_clock () =

     

       441
       441
       +
         Eio_mock.Backend.run @@ fun () ->

     

       442
       442
       +
         let clock = Eio_mock.Clock.make () in

     

       443
       443
       +
       

     

       444
       444
       +
         (* Start at a known time *)

     

       445
       445
       +
         Eio_mock.Clock.set_time clock 5000.0;

     

       446
       446
       +
       

     

       447
       447
       +
         (* Parse a Set-Cookie header with Max-Age *)

     

       448
       448
       +
         let header = "session=abc123; Max-Age=3600; Secure; HttpOnly" in

     

       449
       449
       +
         let cookie_opt =

     

       450
       450
       +
           of_set_cookie_header

     

       451
       451
       +
             ~now:(fun () ->

     

       452
       452
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       453
       453
       +
               |> Option.value ~default:Ptime.epoch)

     

       454
       454
       +
             ~domain:"example.com" ~path:"/" header

     

       455
       455
       +
         in

     

       456
       456
       +
       

     

       457
       457
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       458
       458
       +
       

     

       459
       459
       +
         let cookie = Result.get_ok cookie_opt in

     

       460
       460
       +
         Alcotest.(check string) "cookie name" "session" (Cookeio.name cookie);

     

       461
       461
       +
         Alcotest.(check string) "cookie value" "abc123" (Cookeio.value cookie);

     

       462
       462
       +
         Alcotest.(check bool) "cookie secure" true (Cookeio.secure cookie);

     

       463
       463
       +
         Alcotest.(check bool) "cookie http_only" true (Cookeio.http_only cookie);

     

       464
       464
       +
       

     

       465
       465
       +
         (* Verify the expiry time is set correctly (5000.0 + 3600 = 8600.0) *)

     

       466
       466
       +
         let expected_expiry = Ptime.of_float_s 8600.0 in

     

       467
       467
       +
         begin match expected_expiry with

     

       468
       468
       +
         | Some t ->

     

       469
       469
       +
             Alcotest.(check (option expiration_testable))

     

       470
       470
       +
               "expires set from max-age"

     

       471
       471
       +
               (Some (`DateTime t))

     

       472
       472
       +
               (Cookeio.expires cookie)

     

       473
       473
       +
         | None -> Alcotest.fail "Expected expiry time"

     

       474
       474
       +
         end;

     

       475
       475
       +
       

     

       476
       476
       +
         (* Verify creation time matches clock time *)

     

       477
       477
       +
         let expected_creation = Ptime.of_float_s 5000.0 in

     

       232
       478
        
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       233
       233
       -
           "round trip expires"

     

       234
       234
       -
           (Ptime.of_float_s 1257894000.0)

     

       235
       235
       -
           (Cookeio.expires cookie2)

     

       479
       479
       +
           "creation time" expected_creation

     

       480
       480
       +
           (Some (Cookeio.creation_time cookie))

     

       481
       481
       +
       

     

       482
       482
       +
       let test_last_access_time_with_mock_clock () =

     

       483
       483
       +
         Eio_mock.Backend.run @@ fun () ->

     

       484
       484
       +
         let clock = Eio_mock.Clock.make () in

     

       485
       485
       +
       

     

       486
       486
       +
         (* Start at time 3000.0 *)

     

       487
       487
       +
         Eio_mock.Clock.set_time clock 3000.0;

     

       488
       488
       +
       

     

       489
       489
       +
         let jar = create () in

     

       490
       490
       +
       

     

       491
       491
       +
         (* Add a cookie *)

     

       492
       492
       +
         let cookie =

     

       493
       493
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       494
       494
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       495
       495
       +
             ~creation_time:(Ptime.of_float_s 3000.0 |> Option.get)

     

       496
       496
       +
             ~last_access:(Ptime.of_float_s 3000.0 |> Option.get)

     

       497
       497
       +
             ()

     

       498
       498
       +
         in

     

       499
       499
       +
         add_cookie jar cookie;

     

       500
       500
       +
       

     

       501
       501
       +
         (* Verify initial last access time *)

     

       502
       502
       +
         let cookies1 = get_all_cookies jar in

     

       503
       503
       +
         let cookie1 = List.hd cookies1 in

     

       504
       504
       +
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       505
       505
       +
           "initial last access" (Ptime.of_float_s 3000.0)

     

       506
       506
       +
           (Some (Cookeio.last_access cookie1));

     

       507
       507
       +
       

     

       508
       508
       +
         (* Advance time to 4000.0 *)

     

       509
       509
       +
         Eio_mock.Clock.set_time clock 4000.0;

     

       510
       510
       +
       

     

       511
       511
       +
         (* Get cookies, which should update last access time to current clock time *)

     

       512
       512
       +
         let _retrieved =

     

       513
       513
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       514
       514
       +
         in

     

       515
       515
       +
       

     

       516
       516
       +
         (* Verify last access time was updated to the new clock time *)

     

       517
       517
       +
         let cookies2 = get_all_cookies jar in

     

       518
       518
       +
         let cookie2 = List.hd cookies2 in

     

       519
       519
       +
         Alcotest.(check (option (Alcotest.testable Ptime.pp Ptime.equal)))

     

       520
       520
       +
           "updated last access" (Ptime.of_float_s 4000.0)

     

       521
       521
       +
           (Some (Cookeio.last_access cookie2))

     

       522
       522
       +
       

     

       523
       523
       +
       let test_of_set_cookie_header_with_expires () =

     

       524
       524
       +
         Eio_mock.Backend.run @@ fun () ->

     

       525
       525
       +
         let clock = Eio_mock.Clock.make () in

     

       526
       526
       +
       

     

       527
       527
       +
         (* Start at a known time *)

     

       528
       528
       +
         Eio_mock.Clock.set_time clock 6000.0;

     

       529
       529
       +
       

     

       530
       530
       +
         (* Use RFC3339 format which is what Ptime.of_rfc3339 expects *)

     

       531
       531
       +
         let header =

     

       532
       532
       +
           "id=xyz789; Expires=2025-10-21T07:28:00Z; Path=/; Domain=.example.com"

     

       533
       533
       +
         in

     

       534
       534
       +
         let cookie_opt =

     

       535
       535
       +
           of_set_cookie_header

     

       536
       536
       +
             ~now:(fun () ->

     

       537
       537
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       538
       538
       +
               |> Option.value ~default:Ptime.epoch)

     

       539
       539
       +
             ~domain:"example.com" ~path:"/" header

     

       540
       540
       +
         in

     

       541
       541
       +
       

     

       542
       542
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       543
       543
       +
       

     

       544
       544
       +
         let cookie = Result.get_ok cookie_opt in

     

       545
       545
       +
         Alcotest.(check string) "cookie name" "id" (Cookeio.name cookie);

     

       546
       546
       +
         Alcotest.(check string) "cookie value" "xyz789" (Cookeio.value cookie);

     

       547
       547
       +
         Alcotest.(check string) "cookie domain" "example.com" (Cookeio.domain cookie);

     

       548
       548
       +
         Alcotest.(check string) "cookie path" "/" (Cookeio.path cookie);

     

       549
       549
       +
       

     

       550
       550
       +
         (* Verify expires is parsed correctly *)

     

       551
       551
       +
         Alcotest.(check bool)

     

       552
       552
       +
           "has expiry" true

     

       553
       553
       +
           (Option.is_some (Cookeio.expires cookie));

     

       554
       554
       +
       

     

       555
       555
       +
         (* Verify the specific expiry time parsed from the RFC3339 date *)

     

       556
       556
       +
         let expected_expiry = Ptime.of_rfc3339 "2025-10-21T07:28:00Z" in

     

       557
       557
       +
         match expected_expiry with

     

       558
       558
       +
         | Ok (time, _, _) ->

     

       559
       559
       +
             Alcotest.(check (option expiration_testable))

     

       560
       560
       +
               "expires matches parsed value"

     

       561
       561
       +
               (Some (`DateTime time))

     

       562
       562
       +
               (Cookeio.expires cookie)

     

       563
       563
       +
         | Error _ -> Alcotest.fail "Failed to parse expected expiry time"

     

       564
       564
       +
       

     

       565
       565
       +
       let test_samesite_none_validation () =

     

       566
       566
       +
         Eio_mock.Backend.run @@ fun () ->

     

       567
       567
       +
         let clock = Eio_mock.Clock.make () in

     

       568
       568
       +
       

     

       569
       569
       +
         (* Start at a known time *)

     

       570
       570
       +
         Eio_mock.Clock.set_time clock 7000.0;

     

       571
       571
       +
       

     

       572
       572
       +
         (* This should be rejected: SameSite=None without Secure *)

     

       573
       573
       +
         let invalid_header = "token=abc; SameSite=None" in

     

       574
       574
       +
         let cookie_opt =

     

       575
       575
       +
           of_set_cookie_header

     

       576
       576
       +
             ~now:(fun () ->

     

       577
       577
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       578
       578
       +
               |> Option.value ~default:Ptime.epoch)

     

       579
       579
       +
             ~domain:"example.com" ~path:"/" invalid_header

     

       580
       580
       +
         in

     

       581
       581
       +
       

     

       582
       582
       +
         Alcotest.(check bool)

     

       583
       583
       +
           "invalid cookie rejected" true

     

       584
       584
       +
           (Result.is_error cookie_opt);

     

       585
       585
       +
       

     

       586
       586
       +
         (* This should be accepted: SameSite=None with Secure *)

     

       587
       587
       +
         let valid_header = "token=abc; SameSite=None; Secure" in

     

       588
       588
       +
         let cookie_opt2 =

     

       589
       589
       +
           of_set_cookie_header

     

       590
       590
       +
             ~now:(fun () ->

     

       591
       591
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       592
       592
       +
               |> Option.value ~default:Ptime.epoch)

     

       593
       593
       +
             ~domain:"example.com" ~path:"/" valid_header

     

       594
       594
       +
         in

     

       595
       595
       +
       

     

       596
       596
       +
         Alcotest.(check bool)

     

       597
       597
       +
           "valid cookie accepted" true

     

       598
       598
       +
           (Result.is_ok cookie_opt2);

     

       599
       599
       +
       

     

       600
       600
       +
         let cookie = Result.get_ok cookie_opt2 in

     

       601
       601
       +
         Alcotest.(check bool) "cookie is secure" true (Cookeio.secure cookie);

     

       602
       602
       +
         Alcotest.(

     

       603
       603
       +
           check

     

       604
       604
       +
             (option

     

       605
       605
       +
                (Alcotest.testable

     

       606
       606
       +
                   (fun ppf -> function

     

       607
       607
       +
                     | `Strict -> Format.pp_print_string ppf "Strict"

     

       608
       608
       +
                     | `Lax -> Format.pp_print_string ppf "Lax"

     

       609
       609
       +
                     | `None -> Format.pp_print_string ppf "None")

     

       610
       610
       +
                   ( = ))))

     

       611
       611
       +
           "samesite is None" (Some `None) (Cookeio.same_site cookie)

     

       612
       612
       +
       

     

       613
       613
       +
       let test_domain_normalization () =

     

       614
       614
       +
         Eio_mock.Backend.run @@ fun () ->

     

       615
       615
       +
         let clock = Eio_mock.Clock.make () in

     

       616
       616
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       617
       617
       +
       

     

       618
       618
       +
         (* Test parsing ".example.com" stores as "example.com" *)

     

       619
       619
       +
         let header = "test=value; Domain=.example.com" in

     

       620
       620
       +
         let cookie_opt =

     

       621
       621
       +
           of_set_cookie_header

     

       622
       622
       +
             ~now:(fun () ->

     

       623
       623
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       624
       624
       +
               |> Option.value ~default:Ptime.epoch)

     

       625
       625
       +
             ~domain:"example.com" ~path:"/" header

     

       626
       626
       +
         in

     

       627
       627
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       628
       628
       +
         let cookie = Result.get_ok cookie_opt in

     

       629
       629
       +
         Alcotest.(check string)

     

       630
       630
       +
           "domain normalized" "example.com" (Cookeio.domain cookie);

     

       631
       631
       +
       

     

       632
       632
       +
         (* Test round-trip through Mozilla format normalizes domains *)

     

       633
       633
       +
         let jar = create () in

     

       634
       634
       +
         let test_cookie =

     

       635
       635
       +
           Cookeio.make ~domain:".example.com" ~path:"/" ~name:"test" ~value:"val"

     

       636
       636
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       637
       637
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       638
       638
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       639
       639
       +
             ()

     

       640
       640
       +
         in

     

       641
       641
       +
         add_cookie jar test_cookie;

     

       642
       642
       +
       

     

       643
       643
       +
         let mozilla_format = to_mozilla_format jar in

     

       644
       644
       +
         let jar2 = from_mozilla_format ~clock mozilla_format in

     

       645
       645
       +
         let cookies2 = get_all_cookies jar2 in

     

       646
       646
       +
         Alcotest.(check int) "one cookie" 1 (List.length cookies2);

     

       647
       647
       +
         Alcotest.(check string)

     

       648
       648
       +
           "domain normalized after round-trip" "example.com"

     

       649
       649
       +
           (Cookeio.domain (List.hd cookies2))

     

       650
       650
       +
       

     

       651
       651
       +
       let test_max_age_stored_separately () =

     

       652
       652
       +
         Eio_mock.Backend.run @@ fun () ->

     

       653
       653
       +
         let clock = Eio_mock.Clock.make () in

     

       654
       654
       +
         Eio_mock.Clock.set_time clock 5000.0;

     

       655
       655
       +
       

     

       656
       656
       +
         (* Parse a Set-Cookie header with Max-Age *)

     

       657
       657
       +
         let header = "session=abc123; Max-Age=3600" in

     

       658
       658
       +
         let cookie_opt =

     

       659
       659
       +
           of_set_cookie_header

     

       660
       660
       +
             ~now:(fun () ->

     

       661
       661
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       662
       662
       +
               |> Option.value ~default:Ptime.epoch)

     

       663
       663
       +
             ~domain:"example.com" ~path:"/" header

     

       664
       664
       +
         in

     

       665
       665
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       666
       666
       +
       

     

       667
       667
       +
         let cookie = Result.get_ok cookie_opt in

     

       668
       668
       +
       

     

       669
       669
       +
         (* Verify max_age is stored as a Ptime.Span *)

     

       670
       670
       +
         Alcotest.(check bool)

     

       671
       671
       +
           "max_age is set" true

     

       672
       672
       +
           (Option.is_some (Cookeio.max_age cookie));

     

       673
       673
       +
         let max_age_span = Option.get (Cookeio.max_age cookie) in

     

       674
       674
       +
         Alcotest.(check (option int))

     

       675
       675
       +
           "max_age is 3600 seconds" (Some 3600)

     

       676
       676
       +
           (Ptime.Span.to_int_s max_age_span);

     

       677
       677
       +
       

     

       678
       678
       +
         (* Verify expires is also computed correctly *)

     

       679
       679
       +
         let expected_expiry = Ptime.of_float_s 8600.0 in

     

       680
       680
       +
         begin match expected_expiry with

     

       681
       681
       +
         | Some t ->

     

       682
       682
       +
             Alcotest.(check (option expiration_testable))

     

       683
       683
       +
               "expires computed from max-age"

     

       684
       684
       +
               (Some (`DateTime t))

     

       685
       685
       +
               (Cookeio.expires cookie)

     

       686
       686
       +
         | None -> Alcotest.fail "Expected expiry time"

     

       687
       687
       +
         end

     

       688
       688
       +
       

     

       689
       689
       +
       let test_max_age_negative_becomes_zero () =

     

       690
       690
       +
         Eio_mock.Backend.run @@ fun () ->

     

       691
       691
       +
         let clock = Eio_mock.Clock.make () in

     

       692
       692
       +
         Eio_mock.Clock.set_time clock 5000.0;

     

       693
       693
       +
       

     

       694
       694
       +
         (* Parse a Set-Cookie header with negative Max-Age *)

     

       695
       695
       +
         let header = "session=abc123; Max-Age=-100" in

     

       696
       696
       +
         let cookie_opt =

     

       697
       697
       +
           of_set_cookie_header

     

       698
       698
       +
             ~now:(fun () ->

     

       699
       699
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       700
       700
       +
               |> Option.value ~default:Ptime.epoch)

     

       701
       701
       +
             ~domain:"example.com" ~path:"/" header

     

       702
       702
       +
         in

     

       703
       703
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       704
       704
       +
       

     

       705
       705
       +
         let cookie = Result.get_ok cookie_opt in

     

       706
       706
       +
       

     

       707
       707
       +
         (* Verify max_age is stored as 0 per RFC 6265 *)

     

       708
       708
       +
         Alcotest.(check bool)

     

       709
       709
       +
           "max_age is set" true

     

       710
       710
       +
           (Option.is_some (Cookeio.max_age cookie));

     

       711
       711
       +
         let max_age_span = Option.get (Cookeio.max_age cookie) in

     

       712
       712
       +
         Alcotest.(check (option int))

     

       713
       713
       +
           "negative max_age becomes 0" (Some 0)

     

       714
       714
       +
           (Ptime.Span.to_int_s max_age_span);

     

       715
       715
       +
       

     

       716
       716
       +
         (* Verify expires is computed with 0 seconds *)

     

       717
       717
       +
         let expected_expiry = Ptime.of_float_s 5000.0 in

     

       718
       718
       +
         begin match expected_expiry with

     

       719
       719
       +
         | Some t ->

     

       720
       720
       +
             Alcotest.(check (option expiration_testable))

     

       721
       721
       +
               "expires computed with 0 seconds"

     

       722
       722
       +
               (Some (`DateTime t))

     

       723
       723
       +
               (Cookeio.expires cookie)

     

       724
       724
       +
         | None -> Alcotest.fail "Expected expiry time"

     

       725
       725
       +
         end

     

       726
       726
       +
       

     

       727
       727
       +
       let string_contains_substring s sub =

     

       728
       728
       +
         try

     

       729
       729
       +
           let len = String.length sub in

     

       730
       730
       +
           let rec search i =

     

       731
       731
       +
             if i + len > String.length s then false

     

       732
       732
       +
             else if String.sub s i len = sub then true

     

       733
       733
       +
             else search (i + 1)

     

       734
       734
       +
           in

     

       735
       735
       +
           search 0

     

       736
       736
       +
         with _ -> false

     

       737
       737
       +
       

     

       738
       738
       +
       let test_make_set_cookie_header_includes_max_age () =

     

       739
       739
       +
         Eio_mock.Backend.run @@ fun () ->

     

       740
       740
       +
         let clock = Eio_mock.Clock.make () in

     

       741
       741
       +
         Eio_mock.Clock.set_time clock 5000.0;

     

       742
       742
       +
       

     

       743
       743
       +
         (* Create a cookie with max_age *)

     

       744
       744
       +
         let max_age_span = Ptime.Span.of_int_s 3600 in

     

       745
       745
       +
         let expires_time = Ptime.of_float_s 8600.0 |> Option.get in

     

       746
       746
       +
         let cookie =

     

       747
       747
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"session" ~value:"abc123"

     

       748
       748
       +
             ~secure:true ~http_only:true

     

       749
       749
       +
             ?expires:(Some (`DateTime expires_time))

     

       750
       750
       +
             ?max_age:(Some max_age_span) ?same_site:(Some `Strict)

     

       751
       751
       +
             ~creation_time:(Ptime.of_float_s 5000.0 |> Option.get)

     

       752
       752
       +
             ~last_access:(Ptime.of_float_s 5000.0 |> Option.get)

     

       753
       753
       +
             ()

     

       754
       754
       +
         in

     

       755
       755
       +
       

     

       756
       756
       +
         let header = make_set_cookie_header cookie in

     

       757
       757
       +
       

     

       758
       758
       +
         (* Verify the header includes Max-Age *)

     

       759
       759
       +
         Alcotest.(check bool)

     

       760
       760
       +
           "header includes Max-Age" true

     

       761
       761
       +
           (string_contains_substring header "Max-Age=3600");

     

       762
       762
       +
       

     

       763
       763
       +
         (* Verify the header includes Expires *)

     

       764
       764
       +
         Alcotest.(check bool)

     

       765
       765
       +
           "header includes Expires" true

     

       766
       766
       +
           (string_contains_substring header "Expires=");

     

       767
       767
       +
       

     

       768
       768
       +
         (* Verify the header includes other attributes *)

     

       769
       769
       +
         Alcotest.(check bool)

     

       770
       770
       +
           "header includes Secure" true

     

       771
       771
       +
           (string_contains_substring header "Secure");

     

       772
       772
       +
         Alcotest.(check bool)

     

       773
       773
       +
           "header includes HttpOnly" true

     

       774
       774
       +
           (string_contains_substring header "HttpOnly");

     

       775
       775
       +
         Alcotest.(check bool)

     

       776
       776
       +
           "header includes SameSite" true

     

       777
       777
       +
           (string_contains_substring header "SameSite=Strict")

     

       778
       778
       +
       

     

       779
       779
       +
       let test_max_age_round_trip () =

     

       780
       780
       +
         Eio_mock.Backend.run @@ fun () ->

     

       781
       781
       +
         let clock = Eio_mock.Clock.make () in

     

       782
       782
       +
         Eio_mock.Clock.set_time clock 5000.0;

     

       783
       783
       +
       

     

       784
       784
       +
         (* Parse a cookie with Max-Age *)

     

       785
       785
       +
         let header = "session=xyz; Max-Age=7200; Secure; HttpOnly" in

     

       786
       786
       +
         let cookie_opt =

     

       787
       787
       +
           of_set_cookie_header

     

       788
       788
       +
             ~now:(fun () ->

     

       789
       789
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       790
       790
       +
               |> Option.value ~default:Ptime.epoch)

     

       791
       791
       +
             ~domain:"example.com" ~path:"/" header

     

       792
       792
       +
         in

     

       793
       793
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       794
       794
       +
         let cookie = Result.get_ok cookie_opt in

     

       795
       795
       +
       

     

       796
       796
       +
         (* Generate Set-Cookie header from the cookie *)

     

       797
       797
       +
         let set_cookie_header = make_set_cookie_header cookie in

     

       798
       798
       +
       

     

       799
       799
       +
         (* Parse it back *)

     

       800
       800
       +
         Eio_mock.Clock.set_time clock 5000.0;

     

       801
       801
       +
         (* Reset clock to same time *)

     

       802
       802
       +
         let cookie2_opt =

     

       803
       803
       +
           of_set_cookie_header

     

       804
       804
       +
             ~now:(fun () ->

     

       805
       805
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       806
       806
       +
               |> Option.value ~default:Ptime.epoch)

     

       807
       807
       +
             ~domain:"example.com" ~path:"/" set_cookie_header

     

       808
       808
       +
         in

     

       809
       809
       +
         Alcotest.(check bool) "cookie re-parsed" true (Result.is_ok cookie2_opt);

     

       810
       810
       +
         let cookie2 = Result.get_ok cookie2_opt in

     

       811
       811
       +
       

     

       812
       812
       +
         (* Verify max_age is preserved *)

     

       813
       813
       +
         Alcotest.(check (option int))

     

       814
       814
       +
           "max_age preserved"

     

       815
       815
       +
           (Ptime.Span.to_int_s (Option.get (Cookeio.max_age cookie)))

     

       816
       816
       +
           (Ptime.Span.to_int_s (Option.get (Cookeio.max_age cookie2)))

     

       817
       817
       +
       

     

       818
       818
       +
       let test_domain_matching () =

     

       819
       819
       +
         Eio_mock.Backend.run @@ fun () ->

     

       820
       820
       +
         let clock = Eio_mock.Clock.make () in

     

       821
       821
       +
         Eio_mock.Clock.set_time clock 2000.0;

     

       822
       822
       +
       

     

       823
       823
       +
         let jar = create () in

     

       824
       824
       +
       

     

       825
       825
       +
         (* Create a cookie with domain "example.com" *)

     

       826
       826
       +
         let cookie =

     

       827
       827
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       828
       828
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       829
       829
       +
             ~creation_time:(Ptime.of_float_s 2000.0 |> Option.get)

     

       830
       830
       +
             ~last_access:(Ptime.of_float_s 2000.0 |> Option.get)

     

       831
       831
       +
             ()

     

       832
       832
       +
         in

     

       833
       833
       +
         add_cookie jar cookie;

     

       834
       834
       +
       

     

       835
       835
       +
         (* Test "example.com" cookie matches "example.com" request *)

     

       836
       836
       +
         let cookies1 =

     

       837
       837
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       838
       838
       +
         in

     

       839
       839
       +
         Alcotest.(check int) "matches exact domain" 1 (List.length cookies1);

     

       840
       840
       +
       

     

       841
       841
       +
         (* Test "example.com" cookie matches "sub.example.com" request *)

     

       842
       842
       +
         let cookies2 =

     

       843
       843
       +
           get_cookies jar ~clock ~domain:"sub.example.com" ~path:"/" ~is_secure:false

     

       844
       844
       +
         in

     

       845
       845
       +
         Alcotest.(check int) "matches subdomain" 1 (List.length cookies2);

     

       846
       846
       +
       

     

       847
       847
       +
         (* Test "example.com" cookie matches "deep.sub.example.com" request *)

     

       848
       848
       +
         let cookies3 =

     

       849
       849
       +
           get_cookies jar ~clock ~domain:"deep.sub.example.com" ~path:"/"

     

       850
       850
       +
             ~is_secure:false

     

       851
       851
       +
         in

     

       852
       852
       +
         Alcotest.(check int) "matches deep subdomain" 1 (List.length cookies3);

     

       853
       853
       +
       

     

       854
       854
       +
         (* Test "example.com" cookie doesn't match "notexample.com" *)

     

       855
       855
       +
         let cookies4 =

     

       856
       856
       +
           get_cookies jar ~clock ~domain:"notexample.com" ~path:"/" ~is_secure:false

     

       857
       857
       +
         in

     

       858
       858
       +
         Alcotest.(check int) "doesn't match different domain" 0 (List.length cookies4);

     

       859
       859
       +
       

     

       860
       860
       +
         (* Test "example.com" cookie doesn't match "fakeexample.com" *)

     

       861
       861
       +
         let cookies5 =

     

       862
       862
       +
           get_cookies jar ~clock ~domain:"fakeexample.com" ~path:"/" ~is_secure:false

     

       863
       863
       +
         in

     

       864
       864
       +
         Alcotest.(check int) "doesn't match prefix domain" 0 (List.length cookies5)

     

       865
       865
       +
       

     

       866
       866
       +
       (** {1 HTTP Date Parsing Tests} *)

     

       867
       867
       +
       

     

       868
       868
       +
       let test_http_date_fmt1 () =

     

       869
       869
       +
         Eio_mock.Backend.run @@ fun () ->

     

       870
       870
       +
         let clock = Eio_mock.Clock.make () in

     

       871
       871
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       872
       872
       +
       

     

       873
       873
       +
         (* Test FMT1: "Wed, 21 Oct 2015 07:28:00 GMT" (RFC 1123) *)

     

       874
       874
       +
         let header = "session=abc; Expires=Wed, 21 Oct 2015 07:28:00 GMT" in

     

       875
       875
       +
         let cookie_opt =

     

       876
       876
       +
           of_set_cookie_header

     

       877
       877
       +
             ~now:(fun () ->

     

       878
       878
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       879
       879
       +
               |> Option.value ~default:Ptime.epoch)

     

       880
       880
       +
             ~domain:"example.com" ~path:"/" header

     

       881
       881
       +
         in

     

       882
       882
       +
         Alcotest.(check bool) "FMT1 cookie parsed" true (Result.is_ok cookie_opt);

     

       883
       883
       +
       

     

       884
       884
       +
         let cookie = Result.get_ok cookie_opt in

     

       885
       885
       +
         Alcotest.(check bool)

     

       886
       886
       +
           "FMT1 has expiry" true

     

       887
       887
       +
           (Option.is_some (Cookeio.expires cookie));

     

       888
       888
       +
       

     

       889
       889
       +
         (* Verify the parsed time matches expected value *)

     

       890
       890
       +
         let expected = Ptime.of_date_time ((2015, 10, 21), ((07, 28, 00), 0)) in

     

       891
       891
       +
         begin match expected with

     

       892
       892
       +
         | Some t ->

     

       893
       893
       +
             Alcotest.(check (option expiration_testable))

     

       894
       894
       +
               "FMT1 expiry correct"

     

       895
       895
       +
               (Some (`DateTime t))

     

       896
       896
       +
               (Cookeio.expires cookie)

     

       897
       897
       +
         | None -> Alcotest.fail "Expected expiry time for FMT1"

     

       898
       898
       +
         end

     

       899
       899
       +
       

     

       900
       900
       +
       let test_http_date_fmt2 () =

     

       901
       901
       +
         Eio_mock.Backend.run @@ fun () ->

     

       902
       902
       +
         let clock = Eio_mock.Clock.make () in

     

       903
       903
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       904
       904
       +
       

     

       905
       905
       +
         (* Test FMT2: "Wednesday, 21-Oct-15 07:28:00 GMT" (RFC 850 with abbreviated year) *)

     

       906
       906
       +
         let header = "session=abc; Expires=Wednesday, 21-Oct-15 07:28:00 GMT" in

     

       907
       907
       +
         let cookie_opt =

     

       908
       908
       +
           of_set_cookie_header

     

       909
       909
       +
             ~now:(fun () ->

     

       910
       910
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       911
       911
       +
               |> Option.value ~default:Ptime.epoch)

     

       912
       912
       +
             ~domain:"example.com" ~path:"/" header

     

       913
       913
       +
         in

     

       914
       914
       +
         Alcotest.(check bool) "FMT2 cookie parsed" true (Result.is_ok cookie_opt);

     

       915
       915
       +
       

     

       916
       916
       +
         let cookie = Result.get_ok cookie_opt in

     

       917
       917
       +
         Alcotest.(check bool)

     

       918
       918
       +
           "FMT2 has expiry" true

     

       919
       919
       +
           (Option.is_some (Cookeio.expires cookie));

     

       920
       920
       +
       

     

       921
       921
       +
         (* Year 15 should be normalized to 2015 *)

     

       922
       922
       +
         let expected = Ptime.of_date_time ((2015, 10, 21), ((07, 28, 00), 0)) in

     

       923
       923
       +
         begin match expected with

     

       924
       924
       +
         | Some t ->

     

       925
       925
       +
             Alcotest.(check (option expiration_testable))

     

       926
       926
       +
               "FMT2 expiry correct with year normalization"

     

       927
       927
       +
               (Some (`DateTime t))

     

       928
       928
       +
               (Cookeio.expires cookie)

     

       929
       929
       +
         | None -> Alcotest.fail "Expected expiry time for FMT2"

     

       930
       930
       +
         end

     

       931
       931
       +
       

     

       932
       932
       +
       let test_http_date_fmt3 () =

     

       933
       933
       +
         Eio_mock.Backend.run @@ fun () ->

     

       934
       934
       +
         let clock = Eio_mock.Clock.make () in

     

       935
       935
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       936
       936
       +
       

     

       937
       937
       +
         (* Test FMT3: "Wed Oct 21 07:28:00 2015" (asctime) *)

     

       938
       938
       +
         let header = "session=abc; Expires=Wed Oct 21 07:28:00 2015" in

     

       939
       939
       +
         let cookie_opt =

     

       940
       940
       +
           of_set_cookie_header

     

       941
       941
       +
             ~now:(fun () ->

     

       942
       942
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       943
       943
       +
               |> Option.value ~default:Ptime.epoch)

     

       944
       944
       +
             ~domain:"example.com" ~path:"/" header

     

       945
       945
       +
         in

     

       946
       946
       +
         Alcotest.(check bool) "FMT3 cookie parsed" true (Result.is_ok cookie_opt);

     

       947
       947
       +
       

     

       948
       948
       +
         let cookie = Result.get_ok cookie_opt in

     

       949
       949
       +
         Alcotest.(check bool)

     

       950
       950
       +
           "FMT3 has expiry" true

     

       951
       951
       +
           (Option.is_some (Cookeio.expires cookie));

     

       952
       952
       +
       

     

       953
       953
       +
         let expected = Ptime.of_date_time ((2015, 10, 21), ((07, 28, 00), 0)) in

     

       954
       954
       +
         begin match expected with

     

       955
       955
       +
         | Some t ->

     

       956
       956
       +
             Alcotest.(check (option expiration_testable))

     

       957
       957
       +
               "FMT3 expiry correct"

     

       958
       958
       +
               (Some (`DateTime t))

     

       959
       959
       +
               (Cookeio.expires cookie)

     

       960
       960
       +
         | None -> Alcotest.fail "Expected expiry time for FMT3"

     

       961
       961
       +
         end

     

       962
       962
       +
       

     

       963
       963
       +
       let test_http_date_fmt4 () =

     

       964
       964
       +
         Eio_mock.Backend.run @@ fun () ->

     

       965
       965
       +
         let clock = Eio_mock.Clock.make () in

     

       966
       966
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       967
       967
       +
       

     

       968
       968
       +
         (* Test FMT4: "Wed, 21-Oct-2015 07:28:00 GMT" (variant) *)

     

       969
       969
       +
         let header = "session=abc; Expires=Wed, 21-Oct-2015 07:28:00 GMT" in

     

       970
       970
       +
         let cookie_opt =

     

       971
       971
       +
           of_set_cookie_header

     

       972
       972
       +
             ~now:(fun () ->

     

       973
       973
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       974
       974
       +
               |> Option.value ~default:Ptime.epoch)

     

       975
       975
       +
             ~domain:"example.com" ~path:"/" header

     

       976
       976
       +
         in

     

       977
       977
       +
         Alcotest.(check bool) "FMT4 cookie parsed" true (Result.is_ok cookie_opt);

     

       978
       978
       +
       

     

       979
       979
       +
         let cookie = Result.get_ok cookie_opt in

     

       980
       980
       +
         Alcotest.(check bool)

     

       981
       981
       +
           "FMT4 has expiry" true

     

       982
       982
       +
           (Option.is_some (Cookeio.expires cookie));

     

       983
       983
       +
       

     

       984
       984
       +
         let expected = Ptime.of_date_time ((2015, 10, 21), ((07, 28, 00), 0)) in

     

       985
       985
       +
         begin match expected with

     

       986
       986
       +
         | Some t ->

     

       987
       987
       +
             Alcotest.(check (option expiration_testable))

     

       988
       988
       +
               "FMT4 expiry correct"

     

       989
       989
       +
               (Some (`DateTime t))

     

       990
       990
       +
               (Cookeio.expires cookie)

     

       991
       991
       +
         | None -> Alcotest.fail "Expected expiry time for FMT4"

     

       992
       992
       +
         end

     

       993
       993
       +
       

     

       994
       994
       +
       let test_abbreviated_year_69_to_99 () =

     

       995
       995
       +
         Eio_mock.Backend.run @@ fun () ->

     

       996
       996
       +
         let clock = Eio_mock.Clock.make () in

     

       997
       997
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       998
       998
       +
       

     

       999
       999
       +
         (* Year 95 should become 1995 *)

     

       1000
       1000
       +
         let header = "session=abc; Expires=Wed, 21-Oct-95 07:28:00 GMT" in

     

       1001
       1001
       +
         let cookie_opt =

     

       1002
       1002
       +
           of_set_cookie_header

     

       1003
       1003
       +
             ~now:(fun () ->

     

       1004
       1004
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1005
       1005
       +
               |> Option.value ~default:Ptime.epoch)

     

       1006
       1006
       +
             ~domain:"example.com" ~path:"/" header

     

       1007
       1007
       +
         in

     

       1008
       1008
       +
         let cookie = Result.get_ok cookie_opt in

     

       1009
       1009
       +
         let expected = Ptime.of_date_time ((1995, 10, 21), ((07, 28, 00), 0)) in

     

       1010
       1010
       +
         begin match expected with

     

       1011
       1011
       +
         | Some t ->

     

       1012
       1012
       +
             Alcotest.(check (option expiration_testable))

     

       1013
       1013
       +
               "year 95 becomes 1995"

     

       1014
       1014
       +
               (Some (`DateTime t))

     

       1015
       1015
       +
               (Cookeio.expires cookie)

     

       1016
       1016
       +
         | None -> Alcotest.fail "Expected expiry time for year 95"

     

       1017
       1017
       +
         end;

     

       1018
       1018
       +
       

     

       1019
       1019
       +
         (* Year 69 should become 1969 *)

     

       1020
       1020
       +
         let header2 = "session=abc; Expires=Wed, 10-Sep-69 20:00:00 GMT" in

     

       1021
       1021
       +
         let cookie_opt2 =

     

       1022
       1022
       +
           of_set_cookie_header

     

       1023
       1023
       +
             ~now:(fun () ->

     

       1024
       1024
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1025
       1025
       +
               |> Option.value ~default:Ptime.epoch)

     

       1026
       1026
       +
             ~domain:"example.com" ~path:"/" header2

     

       1027
       1027
       +
         in

     

       1028
       1028
       +
         let cookie2 = Result.get_ok cookie_opt2 in

     

       1029
       1029
       +
         let expected2 = Ptime.of_date_time ((1969, 9, 10), ((20, 0, 0), 0)) in

     

       1030
       1030
       +
         begin match expected2 with

     

       1031
       1031
       +
         | Some t ->

     

       1032
       1032
       +
             Alcotest.(check (option expiration_testable))

     

       1033
       1033
       +
               "year 69 becomes 1969"

     

       1034
       1034
       +
               (Some (`DateTime t))

     

       1035
       1035
       +
               (Cookeio.expires cookie2)

     

       1036
       1036
       +
         | None -> Alcotest.fail "Expected expiry time for year 69"

     

       1037
       1037
       +
         end;

     

       1038
       1038
       +
       

     

       1039
       1039
       +
         (* Year 99 should become 1999 *)

     

       1040
       1040
       +
         let header3 = "session=abc; Expires=Thu, 10-Sep-99 20:00:00 GMT" in

     

       1041
       1041
       +
         let cookie_opt3 =

     

       1042
       1042
       +
           of_set_cookie_header

     

       1043
       1043
       +
             ~now:(fun () ->

     

       1044
       1044
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1045
       1045
       +
               |> Option.value ~default:Ptime.epoch)

     

       1046
       1046
       +
             ~domain:"example.com" ~path:"/" header3

     

       1047
       1047
       +
         in

     

       1048
       1048
       +
         let cookie3 = Result.get_ok cookie_opt3 in

     

       1049
       1049
       +
         let expected3 = Ptime.of_date_time ((1999, 9, 10), ((20, 0, 0), 0)) in

     

       1050
       1050
       +
         begin match expected3 with

     

       1051
       1051
       +
         | Some t ->

     

       1052
       1052
       +
             Alcotest.(check (option expiration_testable))

     

       1053
       1053
       +
               "year 99 becomes 1999"

     

       1054
       1054
       +
               (Some (`DateTime t))

     

       1055
       1055
       +
               (Cookeio.expires cookie3)

     

       1056
       1056
       +
         | None -> Alcotest.fail "Expected expiry time for year 99"

     

       1057
       1057
       +
         end

     

       1058
       1058
       +
       

     

       1059
       1059
       +
       let test_abbreviated_year_0_to_68 () =

     

       1060
       1060
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1061
       1061
       +
         let clock = Eio_mock.Clock.make () in

     

       1062
       1062
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1063
       1063
       +
       

     

       1064
       1064
       +
         (* Year 25 should become 2025 *)

     

       1065
       1065
       +
         let header = "session=abc; Expires=Wed, 21-Oct-25 07:28:00 GMT" in

     

       1066
       1066
       +
         let cookie_opt =

     

       1067
       1067
       +
           of_set_cookie_header

     

       1068
       1068
       +
             ~now:(fun () ->

     

       1069
       1069
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1070
       1070
       +
               |> Option.value ~default:Ptime.epoch)

     

       1071
       1071
       +
             ~domain:"example.com" ~path:"/" header

     

       1072
       1072
       +
         in

     

       1073
       1073
       +
         let cookie = Result.get_ok cookie_opt in

     

       1074
       1074
       +
         let expected = Ptime.of_date_time ((2025, 10, 21), ((07, 28, 00), 0)) in

     

       1075
       1075
       +
         begin match expected with

     

       1076
       1076
       +
         | Some t ->

     

       1077
       1077
       +
             Alcotest.(check (option expiration_testable))

     

       1078
       1078
       +
               "year 25 becomes 2025"

     

       1079
       1079
       +
               (Some (`DateTime t))

     

       1080
       1080
       +
               (Cookeio.expires cookie)

     

       1081
       1081
       +
         | None -> Alcotest.fail "Expected expiry time for year 25"

     

       1082
       1082
       +
         end;

     

       1083
       1083
       +
       

     

       1084
       1084
       +
         (* Year 0 should become 2000 *)

     

       1085
       1085
       +
         let header2 = "session=abc; Expires=Fri, 01-Jan-00 00:00:00 GMT" in

     

       1086
       1086
       +
         let cookie_opt2 =

     

       1087
       1087
       +
           of_set_cookie_header

     

       1088
       1088
       +
             ~now:(fun () ->

     

       1089
       1089
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1090
       1090
       +
               |> Option.value ~default:Ptime.epoch)

     

       1091
       1091
       +
             ~domain:"example.com" ~path:"/" header2

     

       1092
       1092
       +
         in

     

       1093
       1093
       +
         let cookie2 = Result.get_ok cookie_opt2 in

     

       1094
       1094
       +
         let expected2 = Ptime.of_date_time ((2000, 1, 1), ((0, 0, 0), 0)) in

     

       1095
       1095
       +
         begin match expected2 with

     

       1096
       1096
       +
         | Some t ->

     

       1097
       1097
       +
             Alcotest.(check (option expiration_testable))

     

       1098
       1098
       +
               "year 0 becomes 2000"

     

       1099
       1099
       +
               (Some (`DateTime t))

     

       1100
       1100
       +
               (Cookeio.expires cookie2)

     

       1101
       1101
       +
         | None -> Alcotest.fail "Expected expiry time for year 0"

     

       1102
       1102
       +
         end;

     

       1103
       1103
       +
       

     

       1104
       1104
       +
         (* Year 68 should become 2068 *)

     

       1105
       1105
       +
         let header3 = "session=abc; Expires=Thu, 10-Sep-68 20:00:00 GMT" in

     

       1106
       1106
       +
         let cookie_opt3 =

     

       1107
       1107
       +
           of_set_cookie_header

     

       1108
       1108
       +
             ~now:(fun () ->

     

       1109
       1109
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1110
       1110
       +
               |> Option.value ~default:Ptime.epoch)

     

       1111
       1111
       +
             ~domain:"example.com" ~path:"/" header3

     

       1112
       1112
       +
         in

     

       1113
       1113
       +
         let cookie3 = Result.get_ok cookie_opt3 in

     

       1114
       1114
       +
         let expected3 = Ptime.of_date_time ((2068, 9, 10), ((20, 0, 0), 0)) in

     

       1115
       1115
       +
         begin match expected3 with

     

       1116
       1116
       +
         | Some t ->

     

       1117
       1117
       +
             Alcotest.(check (option expiration_testable))

     

       1118
       1118
       +
               "year 68 becomes 2068"

     

       1119
       1119
       +
               (Some (`DateTime t))

     

       1120
       1120
       +
               (Cookeio.expires cookie3)

     

       1121
       1121
       +
         | None -> Alcotest.fail "Expected expiry time for year 68"

     

       1122
       1122
       +
         end

     

       1123
       1123
       +
       

     

       1124
       1124
       +
       let test_rfc3339_still_works () =

     

       1125
       1125
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1126
       1126
       +
         let clock = Eio_mock.Clock.make () in

     

       1127
       1127
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1128
       1128
       +
       

     

       1129
       1129
       +
         (* Ensure RFC 3339 format still works for backward compatibility *)

     

       1130
       1130
       +
         let header = "session=abc; Expires=2025-10-21T07:28:00Z" in

     

       1131
       1131
       +
         let cookie_opt =

     

       1132
       1132
       +
           of_set_cookie_header

     

       1133
       1133
       +
             ~now:(fun () ->

     

       1134
       1134
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1135
       1135
       +
               |> Option.value ~default:Ptime.epoch)

     

       1136
       1136
       +
             ~domain:"example.com" ~path:"/" header

     

       1137
       1137
       +
         in

     

       1138
       1138
       +
         Alcotest.(check bool)

     

       1139
       1139
       +
           "RFC 3339 cookie parsed" true

     

       1140
       1140
       +
           (Result.is_ok cookie_opt);

     

       1141
       1141
       +
       

     

       1142
       1142
       +
         let cookie = Result.get_ok cookie_opt in

     

       1143
       1143
       +
         Alcotest.(check bool)

     

       1144
       1144
       +
           "RFC 3339 has expiry" true

     

       1145
       1145
       +
           (Option.is_some (Cookeio.expires cookie));

     

       1146
       1146
       +
       

     

       1147
       1147
       +
         (* Verify the time was parsed correctly *)

     

       1148
       1148
       +
         let expected = Ptime.of_rfc3339 "2025-10-21T07:28:00Z" in

     

       1149
       1149
       +
         match expected with

     

       1150
       1150
       +
         | Ok (time, _, _) ->

     

       1151
       1151
       +
             Alcotest.(check (option expiration_testable))

     

       1152
       1152
       +
               "RFC 3339 expiry correct"

     

       1153
       1153
       +
               (Some (`DateTime time))

     

       1154
       1154
       +
               (Cookeio.expires cookie)

     

       1155
       1155
       +
         | Error _ -> Alcotest.fail "Failed to parse expected RFC 3339 time"

     

       1156
       1156
       +
       

     

       1157
       1157
       +
       let test_invalid_date_format_logs_warning () =

     

       1158
       1158
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1159
       1159
       +
         let clock = Eio_mock.Clock.make () in

     

       1160
       1160
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1161
       1161
       +
       

     

       1162
       1162
       +
         (* Invalid date format should log a warning but still parse the cookie *)

     

       1163
       1163
       +
         let header = "session=abc; Expires=InvalidDate" in

     

       1164
       1164
       +
         let cookie_opt =

     

       1165
       1165
       +
           of_set_cookie_header

     

       1166
       1166
       +
             ~now:(fun () ->

     

       1167
       1167
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1168
       1168
       +
               |> Option.value ~default:Ptime.epoch)

     

       1169
       1169
       +
             ~domain:"example.com" ~path:"/" header

     

       1170
       1170
       +
         in

     

       1171
       1171
       +
       

     

       1172
       1172
       +
         (* Cookie should still be parsed, just without expires *)

     

       1173
       1173
       +
         Alcotest.(check bool)

     

       1174
       1174
       +
           "cookie parsed despite invalid date" true

     

       1175
       1175
       +
           (Result.is_ok cookie_opt);

     

       1176
       1176
       +
         let cookie = Result.get_ok cookie_opt in

     

       1177
       1177
       +
         Alcotest.(check string) "cookie name correct" "session" (Cookeio.name cookie);

     

       1178
       1178
       +
         Alcotest.(check string) "cookie value correct" "abc" (Cookeio.value cookie);

     

       1179
       1179
       +
         (* expires should be None since date was invalid *)

     

       1180
       1180
       +
         Alcotest.(check (option expiration_testable))

     

       1181
       1181
       +
           "expires is None for invalid date" None (Cookeio.expires cookie)

     

       1182
       1182
       +
       

     

       1183
       1183
       +
       let test_case_insensitive_month_parsing () =

     

       1184
       1184
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1185
       1185
       +
         let clock = Eio_mock.Clock.make () in

     

       1186
       1186
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1187
       1187
       +
       

     

       1188
       1188
       +
         (* Test various case combinations for month names *)

     

       1189
       1189
       +
         let test_cases =

     

       1190
       1190
       +
           [

     

       1191
       1191
       +
             ("session=abc; Expires=Wed, 21 oct 2015 07:28:00 GMT", "lowercase month");

     

       1192
       1192
       +
             ("session=abc; Expires=Wed, 21 OCT 2015 07:28:00 GMT", "uppercase month");

     

       1193
       1193
       +
             ("session=abc; Expires=Wed, 21 OcT 2015 07:28:00 GMT", "mixed case month");

     

       1194
       1194
       +
             ("session=abc; Expires=Wed, 21 oCt 2015 07:28:00 GMT", "weird case month");

     

       1195
       1195
       +
           ]

     

       1196
       1196
       +
         in

     

       1197
       1197
       +
       

     

       1198
       1198
       +
         List.iter

     

       1199
       1199
       +
           (fun (header, description) ->

     

       1200
       1200
       +
             let cookie_opt =

     

       1201
       1201
       +
               of_set_cookie_header

     

       1202
       1202
       +
                 ~now:(fun () ->

     

       1203
       1203
       +
                   Ptime.of_float_s (Eio.Time.now clock)

     

       1204
       1204
       +
                   |> Option.value ~default:Ptime.epoch)

     

       1205
       1205
       +
                 ~domain:"example.com" ~path:"/" header

     

       1206
       1206
       +
             in

     

       1207
       1207
       +
             Alcotest.(check bool)

     

       1208
       1208
       +
               (description ^ " parsed") true

     

       1209
       1209
       +
               (Result.is_ok cookie_opt);

     

       1210
       1210
       +
       

     

       1211
       1211
       +
             let cookie = Result.get_ok cookie_opt in

     

       1212
       1212
       +
             Alcotest.(check bool)

     

       1213
       1213
       +
               (description ^ " has expiry")

     

       1214
       1214
       +
               true

     

       1215
       1215
       +
               (Option.is_some (Cookeio.expires cookie));

     

       1216
       1216
       +
       

     

       1217
       1217
       +
             (* Verify the date was parsed correctly regardless of case *)

     

       1218
       1218
       +
             let expires = Option.get (Cookeio.expires cookie) in

     

       1219
       1219
       +
             match expires with

     

       1220
       1220
       +
             | `DateTime ptime ->

     

       1221
       1221
       +
                 let year, month, _ = Ptime.to_date ptime in

     

       1222
       1222
       +
                 Alcotest.(check int) (description ^ " year correct") 2015 year;

     

       1223
       1223
       +
                 Alcotest.(check int)

     

       1224
       1224
       +
                   (description ^ " month correct (October=10)")

     

       1225
       1225
       +
                   10 month

     

       1226
       1226
       +
             | `Session -> Alcotest.fail (description ^ " should not be session cookie"))

     

       1227
       1227
       +
           test_cases

     

       1228
       1228
       +
       

     

       1229
       1229
       +
       let test_case_insensitive_gmt_parsing () =

     

       1230
       1230
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1231
       1231
       +
         let clock = Eio_mock.Clock.make () in

     

       1232
       1232
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1233
       1233
       +
       

     

       1234
       1234
       +
         (* Test various case combinations for GMT timezone *)

     

       1235
       1235
       +
         let test_cases =

     

       1236
       1236
       +
           [

     

       1237
       1237
       +
             ("session=abc; Expires=Wed, 21 Oct 2015 07:28:00 GMT", "uppercase GMT");

     

       1238
       1238
       +
             ("session=abc; Expires=Wed, 21 Oct 2015 07:28:00 gmt", "lowercase gmt");

     

       1239
       1239
       +
             ("session=abc; Expires=Wed, 21 Oct 2015 07:28:00 Gmt", "mixed case Gmt");

     

       1240
       1240
       +
             ("session=abc; Expires=Wed, 21 Oct 2015 07:28:00 GmT", "weird case GmT");

     

       1241
       1241
       +
           ]

     

       1242
       1242
       +
         in

     

       1243
       1243
       +
       

     

       1244
       1244
       +
         List.iter

     

       1245
       1245
       +
           (fun (header, description) ->

     

       1246
       1246
       +
             let cookie_opt =

     

       1247
       1247
       +
               of_set_cookie_header

     

       1248
       1248
       +
                 ~now:(fun () ->

     

       1249
       1249
       +
                   Ptime.of_float_s (Eio.Time.now clock)

     

       1250
       1250
       +
                   |> Option.value ~default:Ptime.epoch)

     

       1251
       1251
       +
                 ~domain:"example.com" ~path:"/" header

     

       1252
       1252
       +
             in

     

       1253
       1253
       +
             Alcotest.(check bool)

     

       1254
       1254
       +
               (description ^ " parsed") true

     

       1255
       1255
       +
               (Result.is_ok cookie_opt);

     

       1256
       1256
       +
       

     

       1257
       1257
       +
             let cookie = Result.get_ok cookie_opt in

     

       1258
       1258
       +
             Alcotest.(check bool)

     

       1259
       1259
       +
               (description ^ " has expiry")

     

       1260
       1260
       +
               true

     

       1261
       1261
       +
               (Option.is_some (Cookeio.expires cookie));

     

       1262
       1262
       +
       

     

       1263
       1263
       +
             (* Verify the date was parsed correctly regardless of GMT case *)

     

       1264
       1264
       +
             let expires = Option.get (Cookeio.expires cookie) in

     

       1265
       1265
       +
             match expires with

     

       1266
       1266
       +
             | `DateTime ptime ->

     

       1267
       1267
       +
                 let year, month, day = Ptime.to_date ptime in

     

       1268
       1268
       +
                 Alcotest.(check int) (description ^ " year correct") 2015 year;

     

       1269
       1269
       +
                 Alcotest.(check int)

     

       1270
       1270
       +
                   (description ^ " month correct (October=10)")

     

       1271
       1271
       +
                   10 month;

     

       1272
       1272
       +
                 Alcotest.(check int) (description ^ " day correct") 21 day

     

       1273
       1273
       +
             | `Session -> Alcotest.fail (description ^ " should not be session cookie"))

     

       1274
       1274
       +
           test_cases

     

       1275
       1275
       +
       

     

       1276
       1276
       +
       (** {1 Delta Tracking Tests} *)

     

       1277
       1277
       +
       

     

       1278
       1278
       +
       let test_add_original_not_in_delta () =

     

       1279
       1279
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1280
       1280
       +
         let clock = Eio_mock.Clock.make () in

     

       1281
       1281
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1282
       1282
       +
       

     

       1283
       1283
       +
         let jar = create () in

     

       1284
       1284
       +
         let cookie =

     

       1285
       1285
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       1286
       1286
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1287
       1287
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1288
       1288
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1289
       1289
       +
             ()

     

       1290
       1290
       +
         in

     

       1291
       1291
       +
         add_original jar cookie;

     

       1292
       1292
       +
       

     

       1293
       1293
       +
         (* Delta should be empty *)

     

       1294
       1294
       +
         let delta = delta jar in

     

       1295
       1295
       +
         Alcotest.(check int) "delta is empty" 0 (List.length delta);

     

       1296
       1296
       +
       

     

       1297
       1297
       +
         (* But the cookie should be in the jar *)

     

       1298
       1298
       +
         Alcotest.(check int) "jar count is 1" 1 (count jar)

     

       1299
       1299
       +
       

     

       1300
       1300
       +
       let test_add_cookie_appears_in_delta () =

     

       1301
       1301
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1302
       1302
       +
         let clock = Eio_mock.Clock.make () in

     

       1303
       1303
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1304
       1304
       +
       

     

       1305
       1305
       +
         let jar = create () in

     

       1306
       1306
       +
         let cookie =

     

       1307
       1307
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       1308
       1308
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1309
       1309
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1310
       1310
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1311
       1311
       +
             ()

     

       1312
       1312
       +
         in

     

       1313
       1313
       +
         add_cookie jar cookie;

     

       1314
       1314
       +
       

     

       1315
       1315
       +
         (* Delta should contain the cookie *)

     

       1316
       1316
       +
         let delta = delta jar in

     

       1317
       1317
       +
         Alcotest.(check int) "delta has 1 cookie" 1 (List.length delta);

     

       1318
       1318
       +
         let delta_cookie = List.hd delta in

     

       1319
       1319
       +
         Alcotest.(check string) "delta cookie name" "test" (Cookeio.name delta_cookie);

     

       1320
       1320
       +
         Alcotest.(check string)

     

       1321
       1321
       +
           "delta cookie value" "value"

     

       1322
       1322
       +
           (Cookeio.value delta_cookie)

     

       1323
       1323
       +
       

     

       1324
       1324
       +
       let test_remove_original_creates_removal_cookie () =

     

       1325
       1325
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1326
       1326
       +
         let clock = Eio_mock.Clock.make () in

     

       1327
       1327
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1328
       1328
       +
       

     

       1329
       1329
       +
         let jar = create () in

     

       1330
       1330
       +
         let cookie =

     

       1331
       1331
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       1332
       1332
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1333
       1333
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1334
       1334
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1335
       1335
       +
             ()

     

       1336
       1336
       +
         in

     

       1337
       1337
       +
         add_original jar cookie;

     

       1338
       1338
       +
       

     

       1339
       1339
       +
         (* Remove the cookie *)

     

       1340
       1340
       +
         remove jar ~clock cookie;

     

       1341
       1341
       +
       

     

       1342
       1342
       +
         (* Delta should contain a removal cookie *)

     

       1343
       1343
       +
         let delta = delta jar in

     

       1344
       1344
       +
         Alcotest.(check int) "delta has 1 removal cookie" 1 (List.length delta);

     

       1345
       1345
       +
         let removal_cookie = List.hd delta in

     

       1346
       1346
       +
         Alcotest.(check string)

     

       1347
       1347
       +
           "removal cookie name" "test"

     

       1348
       1348
       +
           (Cookeio.name removal_cookie);

     

       1349
       1349
       +
         Alcotest.(check string)

     

       1350
       1350
       +
           "removal cookie has empty value" ""

     

       1351
       1351
       +
           (Cookeio.value removal_cookie);

     

       1352
       1352
       +
       

     

       1353
       1353
       +
         (* Check Max-Age is 0 *)

     

       1354
       1354
       +
         match Cookeio.max_age removal_cookie with

     

       1355
       1355
       +
         | Some span ->

     

       1356
       1356
       +
             Alcotest.(check (option int))

     

       1357
       1357
       +
               "removal cookie Max-Age is 0" (Some 0) (Ptime.Span.to_int_s span)

     

       1358
       1358
       +
         | None -> Alcotest.fail "removal cookie should have Max-Age"

     

       1359
       1359
       +
       

     

       1360
       1360
       +
       let test_remove_delta_cookie_removes_it () =

     

       1361
       1361
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1362
       1362
       +
         let clock = Eio_mock.Clock.make () in

     

       1363
       1363
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1364
       1364
       +
       

     

       1365
       1365
       +
         let jar = create () in

     

       1366
       1366
       +
         let cookie =

     

       1367
       1367
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       1368
       1368
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1369
       1369
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1370
       1370
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1371
       1371
       +
             ()

     

       1372
       1372
       +
         in

     

       1373
       1373
       +
         add_cookie jar cookie;

     

       1374
       1374
       +
       

     

       1375
       1375
       +
         (* Remove the cookie *)

     

       1376
       1376
       +
         remove jar ~clock cookie;

     

       1377
       1377
       +
       

     

       1378
       1378
       +
         (* Delta should be empty *)

     

       1379
       1379
       +
         let delta = delta jar in

     

       1380
       1380
       +
         Alcotest.(check int)

     

       1381
       1381
       +
           "delta is empty after removing delta cookie" 0 (List.length delta)

     

       1382
       1382
       +
       

     

       1383
       1383
       +
       let test_get_cookies_combines_original_and_delta () =

     

       1384
       1384
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1385
       1385
       +
         let clock = Eio_mock.Clock.make () in

     

       1386
       1386
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1387
       1387
       +
       

     

       1388
       1388
       +
         let jar = create () in

     

       1389
       1389
       +
       

     

       1390
       1390
       +
         (* Add an original cookie *)

     

       1391
       1391
       +
         let original =

     

       1392
       1392
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"original"

     

       1393
       1393
       +
             ~value:"orig_val" ~secure:false ~http_only:false ?expires:None

     

       1394
       1394
       +
             ?same_site:None ?max_age:None

     

       1395
       1395
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1396
       1396
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1397
       1397
       +
             ()

     

       1398
       1398
       +
         in

     

       1399
       1399
       +
         add_original jar original;

     

       1400
       1400
       +
       

     

       1401
       1401
       +
         (* Add a delta cookie *)

     

       1402
       1402
       +
         let delta_cookie =

     

       1403
       1403
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"delta"

     

       1404
       1404
       +
             ~value:"delta_val" ~secure:false ~http_only:false ?expires:None

     

       1405
       1405
       +
             ?same_site:None ?max_age:None

     

       1406
       1406
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1407
       1407
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1408
       1408
       +
             ()

     

       1409
       1409
       +
         in

     

       1410
       1410
       +
         add_cookie jar delta_cookie;

     

       1411
       1411
       +
       

     

       1412
       1412
       +
         (* Get cookies should return both *)

     

       1413
       1413
       +
         let cookies =

     

       1414
       1414
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       1415
       1415
       +
         in

     

       1416
       1416
       +
         Alcotest.(check int) "both cookies returned" 2 (List.length cookies);

     

       1417
       1417
       +
       

     

       1418
       1418
       +
         let names = List.map Cookeio.name cookies |> List.sort String.compare in

     

       1419
       1419
       +
         Alcotest.(check (list string)) "cookie names" [ "delta"; "original" ] names

     

       1420
       1420
       +
       

     

       1421
       1421
       +
       let test_get_cookies_delta_takes_precedence () =

     

       1422
       1422
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1423
       1423
       +
         let clock = Eio_mock.Clock.make () in

     

       1424
       1424
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1425
       1425
       +
       

     

       1426
       1426
       +
         let jar = create () in

     

       1427
       1427
       +
       

     

       1428
       1428
       +
         (* Add an original cookie *)

     

       1429
       1429
       +
         let original =

     

       1430
       1430
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"orig_val"

     

       1431
       1431
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1432
       1432
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1433
       1433
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1434
       1434
       +
             ()

     

       1435
       1435
       +
         in

     

       1436
       1436
       +
         add_original jar original;

     

       1437
       1437
       +
       

     

       1438
       1438
       +
         (* Add a delta cookie with the same name/domain/path *)

     

       1439
       1439
       +
         let delta_cookie =

     

       1440
       1440
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"delta_val"

     

       1441
       1441
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1442
       1442
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1443
       1443
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1444
       1444
       +
             ()

     

       1445
       1445
       +
         in

     

       1446
       1446
       +
         add_cookie jar delta_cookie;

     

       1447
       1447
       +
       

     

       1448
       1448
       +
         (* Get cookies should return only the delta cookie *)

     

       1449
       1449
       +
         let cookies =

     

       1450
       1450
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       1451
       1451
       +
         in

     

       1452
       1452
       +
         Alcotest.(check int) "only one cookie returned" 1 (List.length cookies);

     

       1453
       1453
       +
         let cookie = List.hd cookies in

     

       1454
       1454
       +
         Alcotest.(check string)

     

       1455
       1455
       +
           "delta cookie value" "delta_val" (Cookeio.value cookie)

     

       1456
       1456
       +
       

     

       1457
       1457
       +
       let test_get_cookies_excludes_removal_cookies () =

     

       1458
       1458
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1459
       1459
       +
         let clock = Eio_mock.Clock.make () in

     

       1460
       1460
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1461
       1461
       +
       

     

       1462
       1462
       +
         let jar = create () in

     

       1463
       1463
       +
       

     

       1464
       1464
       +
         (* Add an original cookie *)

     

       1465
       1465
       +
         let original =

     

       1466
       1466
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       1467
       1467
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1468
       1468
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1469
       1469
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1470
       1470
       +
             ()

     

       1471
       1471
       +
         in

     

       1472
       1472
       +
         add_original jar original;

     

       1473
       1473
       +
       

     

       1474
       1474
       +
         (* Remove it *)

     

       1475
       1475
       +
         remove jar ~clock original;

     

       1476
       1476
       +
       

     

       1477
       1477
       +
         (* Get cookies should return nothing *)

     

       1478
       1478
       +
         let cookies =

     

       1479
       1479
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       1480
       1480
       +
         in

     

       1481
       1481
       +
         Alcotest.(check int) "no cookies returned" 0 (List.length cookies);

     

       1482
       1482
       +
       

     

       1483
       1483
       +
         (* But delta should have the removal cookie *)

     

       1484
       1484
       +
         let delta = delta jar in

     

       1485
       1485
       +
         Alcotest.(check int) "delta has removal cookie" 1 (List.length delta)

     

       1486
       1486
       +
       

     

       1487
       1487
       +
       let test_delta_returns_only_changed_cookies () =

     

       1488
       1488
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1489
       1489
       +
         let clock = Eio_mock.Clock.make () in

     

       1490
       1490
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1491
       1491
       +
       

     

       1492
       1492
       +
         let jar = create () in

     

       1493
       1493
       +
       

     

       1494
       1494
       +
         (* Add original cookies *)

     

       1495
       1495
       +
         let original1 =

     

       1496
       1496
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"orig1" ~value:"val1"

     

       1497
       1497
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1498
       1498
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1499
       1499
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1500
       1500
       +
             ()

     

       1501
       1501
       +
         in

     

       1502
       1502
       +
         add_original jar original1;

     

       1503
       1503
       +
       

     

       1504
       1504
       +
         let original2 =

     

       1505
       1505
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"orig2" ~value:"val2"

     

       1506
       1506
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1507
       1507
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1508
       1508
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1509
       1509
       +
             ()

     

       1510
       1510
       +
         in

     

       1511
       1511
       +
         add_original jar original2;

     

       1512
       1512
       +
       

     

       1513
       1513
       +
         (* Add a new delta cookie *)

     

       1514
       1514
       +
         let new_cookie =

     

       1515
       1515
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"new" ~value:"new_val"

     

       1516
       1516
       +
             ~secure:false ~http_only:false ?expires:None ?same_site:None ?max_age:None

     

       1517
       1517
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1518
       1518
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1519
       1519
       +
             ()

     

       1520
       1520
       +
         in

     

       1521
       1521
       +
         add_cookie jar new_cookie;

     

       1522
       1522
       +
       

     

       1523
       1523
       +
         (* Delta should only contain the new cookie *)

     

       1524
       1524
       +
         let delta = delta jar in

     

       1525
       1525
       +
         Alcotest.(check int) "delta has 1 cookie" 1 (List.length delta);

     

       1526
       1526
       +
         let delta_cookie = List.hd delta in

     

       1527
       1527
       +
         Alcotest.(check string) "delta cookie name" "new" (Cookeio.name delta_cookie)

     

       1528
       1528
       +
       

     

       1529
       1529
       +
       let test_removal_cookie_format () =

     

       1530
       1530
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1531
       1531
       +
         let clock = Eio_mock.Clock.make () in

     

       1532
       1532
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1533
       1533
       +
       

     

       1534
       1534
       +
         let jar = create () in

     

       1535
       1535
       +
         let cookie =

     

       1536
       1536
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"value"

     

       1537
       1537
       +
             ~secure:true ~http_only:true ?expires:None ~same_site:`Strict

     

       1538
       1538
       +
             ?max_age:None

     

       1539
       1539
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1540
       1540
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get)

     

       1541
       1541
       +
             ()

     

       1542
       1542
       +
         in

     

       1543
       1543
       +
         add_original jar cookie;

     

       1544
       1544
       +
       

     

       1545
       1545
       +
         (* Remove the cookie *)

     

       1546
       1546
       +
         remove jar ~clock cookie;

     

       1547
       1547
       +
       

     

       1548
       1548
       +
         (* Get the removal cookie *)

     

       1549
       1549
       +
         let delta = delta jar in

     

       1550
       1550
       +
         let removal = List.hd delta in

     

       1551
       1551
       +
       

     

       1552
       1552
       +
         (* Check all properties *)

     

       1553
       1553
       +
         Alcotest.(check string)

     

       1554
       1554
       +
           "removal cookie has empty value" "" (Cookeio.value removal);

     

       1555
       1555
       +
         Alcotest.(check (option int))

     

       1556
       1556
       +
           "removal cookie Max-Age is 0" (Some 0)

     

       1557
       1557
       +
           (Option.bind (Cookeio.max_age removal) Ptime.Span.to_int_s);

     

       1558
       1558
       +
       

     

       1559
       1559
       +
         (* Check expires is in the past *)

     

       1560
       1560
       +
         let now = Ptime.of_float_s 1000.0 |> Option.get in

     

       1561
       1561
       +
         match Cookeio.expires removal with

     

       1562
       1562
       +
         | Some (`DateTime exp) ->

     

       1563
       1563
       +
             Alcotest.(check bool)

     

       1564
       1564
       +
               "expires is in the past" true

     

       1565
       1565
       +
               (Ptime.compare exp now < 0)

     

       1566
       1566
       +
         | _ -> Alcotest.fail "removal cookie should have DateTime expires"

     

       1567
       1567
       +
       

     

       1568
       1568
       +
       (* ============================================================================ *)

     

       1569
       1569
       +
       (* Priority 2 Tests *)

     

       1570
       1570
       +
       (* ============================================================================ *)

     

       1571
       1571
       +
       

     

       1572
       1572
       +
       (* Priority 2.1: Partitioned Cookies *)

     

       1573
       1573
       +
       

     

       1574
       1574
       +
       let test_partitioned_parsing env =

     

       1575
       1575
       +
         let clock = Eio.Stdenv.clock env in

     

       1576
       1576
       +
       

     

       1577
       1577
       +
         match

     

       1578
       1578
       +
           of_set_cookie_header

     

       1579
       1579
       +
             ~now:(fun () ->

     

       1580
       1580
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1581
       1581
       +
               |> Option.value ~default:Ptime.epoch)

     

       1582
       1582
       +
             ~domain:"widget.com" ~path:"/" "id=123; Partitioned; Secure"

     

       1583
       1583
       +
         with

     

       1584
       1584
       +
         | Ok c ->

     

       1585
       1585
       +
             Alcotest.(check bool) "partitioned flag" true (partitioned c);

     

       1586
       1586
       +
             Alcotest.(check bool) "secure flag" true (secure c)

     

       1587
       1587
       +
         | Error msg -> Alcotest.fail ("Should parse valid Partitioned cookie: " ^ msg)

     

       1588
       1588
       +
       

     

       1589
       1589
       +
       let test_partitioned_serialization env =

     

       1590
       1590
       +
         let clock = Eio.Stdenv.clock env in

     

       1591
       1591
       +
         let now =

     

       1592
       1592
       +
           Ptime.of_float_s (Eio.Time.now clock) |> Option.value ~default:Ptime.epoch

     

       1593
       1593
       +
         in

     

       1594
       1594
       +
       

     

       1595
       1595
       +
         let cookie =

     

       1596
       1596
       +
           make ~domain:"widget.com" ~path:"/" ~name:"id" ~value:"123" ~secure:true

     

       1597
       1597
       +
             ~partitioned:true ~creation_time:now ~last_access:now ()

     

       1598
       1598
       +
         in

     

       1599
       1599
       +
       

     

       1600
       1600
       +
         let header = make_set_cookie_header cookie in

     

       1601
       1601
       +
         let contains_substring s sub =

     

       1602
       1602
       +
           try

     

       1603
       1603
       +
             let _ = Str.search_forward (Str.regexp_string sub) s 0 in

     

       1604
       1604
       +
             true

     

       1605
       1605
       +
           with Not_found -> false

     

       1606
       1606
       +
         in

     

       1607
       1607
       +
         let has_partitioned = contains_substring header "Partitioned" in

     

       1608
       1608
       +
         let has_secure = contains_substring header "Secure" in

     

       1609
       1609
       +
         Alcotest.(check bool) "contains Partitioned" true has_partitioned;

     

       1610
       1610
       +
         Alcotest.(check bool) "contains Secure" true has_secure

     

       1611
       1611
       +
       

     

       1612
       1612
       +
       let test_partitioned_requires_secure env =

     

       1613
       1613
       +
         let clock = Eio.Stdenv.clock env in

     

       1614
       1614
       +
       

     

       1615
       1615
       +
         (* Partitioned without Secure should be rejected *)

     

       1616
       1616
       +
         match

     

       1617
       1617
       +
           of_set_cookie_header

     

       1618
       1618
       +
             ~now:(fun () ->

     

       1619
       1619
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1620
       1620
       +
               |> Option.value ~default:Ptime.epoch)

     

       1621
       1621
       +
             ~domain:"widget.com" ~path:"/" "id=123; Partitioned"

     

       1622
       1622
       +
         with

     

       1623
       1623
       +
         | Error _ -> () (* Expected *)

     

       1624
       1624
       +
         | Ok _ -> Alcotest.fail "Should reject Partitioned without Secure"

     

       1625
       1625
       +
       

     

       1626
       1626
       +
       (* Priority 2.2: Expiration Variants *)

     

       1627
       1627
       +
       

     

       1628
       1628
       +
       let test_expiration_variants env =

     

       1629
       1629
       +
         let clock = Eio.Stdenv.clock env in

     

       1630
       1630
       +
         let now =

     

       1631
       1631
       +
           Ptime.of_float_s (Eio.Time.now clock) |> Option.value ~default:Ptime.epoch

     

       1632
       1632
       +
         in

     

       1633
       1633
       +
         let make_base ~name ?expires () =

     

       1634
       1634
       +
           make ~domain:"ex.com" ~path:"/" ~name ~value:"v" ?expires ~creation_time:now

     

       1635
       1635
       +
             ~last_access:now ()

     

       1636
       1636
       +
         in

     

       1637
       1637
       +
       

     

       1638
       1638
       +
         (* No expiration *)

     

       1639
       1639
       +
         let c1 = make_base ~name:"no_expiry" () in

     

       1640
       1640
       +
         Alcotest.(check (option expiration_testable))

     

       1641
       1641
       +
           "no expiration" None (expires c1);

     

       1642
       1642
       +
       

     

       1643
       1643
       +
         (* Session cookie *)

     

       1644
       1644
       +
         let c2 = make_base ~name:"session" ~expires:`Session () in

     

       1645
       1645
       +
         Alcotest.(check (option expiration_testable))

     

       1646
       1646
       +
           "session cookie" (Some `Session) (expires c2);

     

       1647
       1647
       +
       

     

       1648
       1648
       +
         (* Explicit expiration *)

     

       1649
       1649
       +
         let future = Ptime.add_span now (Ptime.Span.of_int_s 3600) |> Option.get in

     

       1650
       1650
       +
         let c3 = make_base ~name:"persistent" ~expires:(`DateTime future) () in

     

       1651
       1651
       +
         match expires c3 with

     

       1652
       1652
       +
         | Some (`DateTime t) when Ptime.equal t future -> ()

     

       1653
       1653
       +
         | _ -> Alcotest.fail "Expected DateTime expiration"

     

       1654
       1654
       +
       

     

       1655
       1655
       +
       let test_parse_session_expiration env =

     

       1656
       1656
       +
         let clock = Eio.Stdenv.clock env in

     

       1657
       1657
       +
       

     

       1658
       1658
       +
         (* Expires=0 should parse as Session *)

     

       1659
       1659
       +
         match

     

       1660
       1660
       +
           of_set_cookie_header

     

       1661
       1661
       +
             ~now:(fun () ->

     

       1662
       1662
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1663
       1663
       +
               |> Option.value ~default:Ptime.epoch)

     

       1664
       1664
       +
             ~domain:"ex.com" ~path:"/" "id=123; Expires=0"

     

       1665
       1665
       +
         with

     

       1666
       1666
       +
         | Ok c ->

     

       1667
       1667
       +
             Alcotest.(check (option expiration_testable))

     

       1668
       1668
       +
               "expires=0 is session" (Some `Session) (expires c)

     

       1669
       1669
       +
         | Error msg -> Alcotest.fail ("Should parse Expires=0: " ^ msg)

     

       1670
       1670
       +
       

     

       1671
       1671
       +
       let test_serialize_expiration_variants env =

     

       1672
       1672
       +
         let clock = Eio.Stdenv.clock env in

     

       1673
       1673
       +
         let now =

     

       1674
       1674
       +
           Ptime.of_float_s (Eio.Time.now clock) |> Option.value ~default:Ptime.epoch

     

       1675
       1675
       +
         in

     

       1676
       1676
       +
         let contains_substring s sub =

     

       1677
       1677
       +
           try

     

       1678
       1678
       +
             let _ = Str.search_forward (Str.regexp_string sub) s 0 in

     

       1679
       1679
       +
             true

     

       1680
       1680
       +
           with Not_found -> false

     

       1681
       1681
       +
         in

     

       1682
       1682
       +
       

     

       1683
       1683
       +
         (* Session cookie serialization *)

     

       1684
       1684
       +
         let c1 =

     

       1685
       1685
       +
           make ~domain:"ex.com" ~path:"/" ~name:"s" ~value:"v" ~expires:`Session

     

       1686
       1686
       +
             ~creation_time:now ~last_access:now ()

     

       1687
       1687
       +
         in

     

       1688
       1688
       +
         let h1 = make_set_cookie_header c1 in

     

       1689
       1689
       +
         let has_expires = contains_substring h1 "Expires=" in

     

       1690
       1690
       +
         Alcotest.(check bool) "session has Expires" true has_expires;

     

       1691
       1691
       +
       

     

       1692
       1692
       +
         (* DateTime serialization *)

     

       1693
       1693
       +
         let future = Ptime.add_span now (Ptime.Span.of_int_s 3600) |> Option.get in

     

       1694
       1694
       +
         let c2 =

     

       1695
       1695
       +
           make ~domain:"ex.com" ~path:"/" ~name:"p" ~value:"v"

     

       1696
       1696
       +
             ~expires:(`DateTime future) ~creation_time:now ~last_access:now ()

     

       1697
       1697
       +
         in

     

       1698
       1698
       +
         let h2 = make_set_cookie_header c2 in

     

       1699
       1699
       +
         let has_expires2 = contains_substring h2 "Expires=" in

     

       1700
       1700
       +
         Alcotest.(check bool) "datetime has Expires" true has_expires2

     

       1701
       1701
       +
       

     

       1702
       1702
       +
       (* Priority 2.3: Value Trimming *)

     

       1703
       1703
       +
       

     

       1704
       1704
       +
       let test_quoted_cookie_values env =

     

       1705
       1705
       +
         let clock = Eio.Stdenv.clock env in

     

       1706
       1706
       +
         (* Test valid RFC 6265 cookie values:

     

       1707
       1707
       +
            cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )

     

       1708
       1708
       +
            Valid cases have either no quotes or properly paired DQUOTE wrapper *)

     

       1709
       1709
       +
         let valid_cases =

     

       1710
       1710
       +
           [

     

       1711
       1711
       +
             ("name=value", "value", "value");           (* No quotes *)

     

       1712
       1712
       +
             ("name=\"value\"", "\"value\"", "value");   (* Properly quoted *)

     

       1713
       1713
       +
             ("name=\"\"", "\"\"", "");                  (* Empty quoted value *)

     

       1714
       1714
       +
           ]

     

       1715
       1715
       +
         in

     

       1716
       1716
       +
       

     

       1717
       1717
       +
         List.iter

     

       1718
       1718
       +
           (fun (input, expected_raw, expected_trimmed) ->

     

       1719
       1719
       +
             match

     

       1720
       1720
       +
               of_set_cookie_header

     

       1721
       1721
       +
                 ~now:(fun () ->

     

       1722
       1722
       +
                   Ptime.of_float_s (Eio.Time.now clock)

     

       1723
       1723
       +
                   |> Option.value ~default:Ptime.epoch)

     

       1724
       1724
       +
                 ~domain:"ex.com" ~path:"/" input

     

       1725
       1725
       +
             with

     

       1726
       1726
       +
             | Ok c ->

     

       1727
       1727
       +
                 Alcotest.(check string)

     

       1728
       1728
       +
                   (Printf.sprintf "raw value for %s" input)

     

       1729
       1729
       +
                   expected_raw (value c);

     

       1730
       1730
       +
                 Alcotest.(check string)

     

       1731
       1731
       +
                   (Printf.sprintf "trimmed value for %s" input)

     

       1732
       1732
       +
                   expected_trimmed (value_trimmed c)

     

       1733
       1733
       +
             | Error msg -> Alcotest.fail ("Parse failed: " ^ input ^ ": " ^ msg))

     

       1734
       1734
       +
           valid_cases;

     

       1735
       1735
       +
       

     

       1736
       1736
       +
         (* Test invalid RFC 6265 cookie values are rejected *)

     

       1737
       1737
       +
         let invalid_cases =

     

       1738
       1738
       +
           [

     

       1739
       1739
       +
             "name=\"partial";   (* Opening quote without closing *)

     

       1740
       1740
       +
             "name=\"val\"\"";   (* Embedded quote *)

     

       1741
       1741
       +
             "name=val\"";       (* Trailing quote without opening *)

     

       1742
       1742
       +
           ]

     

       1743
       1743
       +
         in

     

       1744
       1744
       +
       

     

       1745
       1745
       +
         List.iter

     

       1746
       1746
       +
           (fun input ->

     

       1747
       1747
       +
             match

     

       1748
       1748
       +
               of_set_cookie_header

     

       1749
       1749
       +
                 ~now:(fun () ->

     

       1750
       1750
       +
                   Ptime.of_float_s (Eio.Time.now clock)

     

       1751
       1751
       +
                   |> Option.value ~default:Ptime.epoch)

     

       1752
       1752
       +
                 ~domain:"ex.com" ~path:"/" input

     

       1753
       1753
       +
             with

     

       1754
       1754
       +
             | Error _ -> ()  (* Expected - invalid values are rejected *)

     

       1755
       1755
       +
             | Ok _ ->

     

       1756
       1756
       +
                 Alcotest.fail

     

       1757
       1757
       +
                   (Printf.sprintf "Should reject invalid value: %s" input))

     

       1758
       1758
       +
           invalid_cases

     

       1759
       1759
       +
       

     

       1760
       1760
       +
       let test_trimmed_value_not_used_for_equality env =

     

       1761
       1761
       +
         let clock = Eio.Stdenv.clock env in

     

       1762
       1762
       +
       

     

       1763
       1763
       +
         match

     

       1764
       1764
       +
           of_set_cookie_header

     

       1765
       1765
       +
             ~now:(fun () ->

     

       1766
       1766
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1767
       1767
       +
               |> Option.value ~default:Ptime.epoch)

     

       1768
       1768
       +
             ~domain:"ex.com" ~path:"/" "name=\"value\""

     

       1769
       1769
       +
         with

     

       1770
       1770
       +
         | Ok c1 -> begin

     

       1771
       1771
       +
             match

     

       1772
       1772
       +
               of_set_cookie_header

     

       1773
       1773
       +
                 ~now:(fun () ->

     

       1774
       1774
       +
                   Ptime.of_float_s (Eio.Time.now clock)

     

       1775
       1775
       +
                   |> Option.value ~default:Ptime.epoch)

     

       1776
       1776
       +
                 ~domain:"ex.com" ~path:"/" "name=value"

     

       1777
       1777
       +
             with

     

       1778
       1778
       +
             | Ok c2 ->

     

       1779
       1779
       +
                 (* Different raw values *)

     

       1780
       1780
       +
                 Alcotest.(check bool)

     

       1781
       1781
       +
                   "different raw values" false

     

       1782
       1782
       +
                   (value c1 = value c2);

     

       1783
       1783
       +
                 (* Same trimmed values *)

     

       1784
       1784
       +
                 Alcotest.(check string)

     

       1785
       1785
       +
                   "same trimmed values" (value_trimmed c1) (value_trimmed c2)

     

       1786
       1786
       +
             | Error msg -> Alcotest.fail ("Parse failed for unquoted: " ^ msg)

     

       1787
       1787
       +
           end

     

       1788
       1788
       +
         | Error msg -> Alcotest.fail ("Parse failed for quoted: " ^ msg)

     

       1789
       1789
       +
       

     

       1790
       1790
       +
       (* Priority 2.4: Cookie Header Parsing *)

     

       1791
       1791
       +
       

     

       1792
       1792
       +
       let test_cookie_header_parsing_basic env =

     

       1793
       1793
       +
         let clock = Eio.Stdenv.clock env in

     

       1794
       1794
       +
         let result =

     

       1795
       1795
       +
           of_cookie_header

     

       1796
       1796
       +
             ~now:(fun () ->

     

       1797
       1797
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1798
       1798
       +
               |> Option.value ~default:Ptime.epoch)

     

       1799
       1799
       +
             ~domain:"ex.com" ~path:"/" "session=abc123; theme=dark; lang=en"

     

       1800
       1800
       +
         in

     

       1801
       1801
       +
       

     

       1802
       1802
       +
         match result with

     

       1803
       1803
       +
         | Error msg -> Alcotest.fail ("Parse failed: " ^ msg)

     

       1804
       1804
       +
         | Ok cookies ->

     

       1805
       1805
       +
             Alcotest.(check int) "parsed 3 cookies" 3 (List.length cookies);

     

       1806
       1806
       +
       

     

       1807
       1807
       +
             let find name_val = List.find (fun c -> name c = name_val) cookies in

     

       1808
       1808
       +
             Alcotest.(check string) "session value" "abc123" (value (find "session"));

     

       1809
       1809
       +
             Alcotest.(check string) "theme value" "dark" (value (find "theme"));

     

       1810
       1810
       +
             Alcotest.(check string) "lang value" "en" (value (find "lang"))

     

       1811
       1811
       +
       

     

       1812
       1812
       +
       let test_cookie_header_defaults env =

     

       1813
       1813
       +
         let clock = Eio.Stdenv.clock env in

     

       1814
       1814
       +
       

     

       1815
       1815
       +
         match

     

       1816
       1816
       +
           of_cookie_header

     

       1817
       1817
       +
             ~now:(fun () ->

     

       1818
       1818
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1819
       1819
       +
               |> Option.value ~default:Ptime.epoch)

     

       1820
       1820
       +
             ~domain:"example.com" ~path:"/app" "session=xyz"

     

       1821
       1821
       +
         with

     

       1822
       1822
       +
         | Ok [ c ] ->

     

       1823
       1823
       +
             (* Domain and path from request context *)

     

       1824
       1824
       +
             Alcotest.(check string) "domain from context" "example.com" (domain c);

     

       1825
       1825
       +
             Alcotest.(check string) "path from context" "/app" (path c);

     

       1826
       1826
       +
       

     

       1827
       1827
       +
             (* Security flags default to false *)

     

       1828
       1828
       +
             Alcotest.(check bool) "secure default" false (secure c);

     

       1829
       1829
       +
             Alcotest.(check bool) "http_only default" false (http_only c);

     

       1830
       1830
       +
             Alcotest.(check bool) "partitioned default" false (partitioned c);

     

       1831
       1831
       +
       

     

       1832
       1832
       +
             (* Optional attributes default to None *)

     

       1833
       1833
       +
             Alcotest.(check (option expiration_testable))

     

       1834
       1834
       +
               "no expiration" None (expires c);

     

       1835
       1835
       +
             Alcotest.(check (option span_testable)) "no max_age" None (max_age c);

     

       1836
       1836
       +
             Alcotest.(check (option same_site_testable))

     

       1837
       1837
       +
               "no same_site" None (same_site c)

     

       1838
       1838
       +
         | Ok _ -> Alcotest.fail "Should parse single cookie"

     

       1839
       1839
       +
         | Error msg -> Alcotest.fail ("Parse failed: " ^ msg)

     

       1840
       1840
       +
       

     

       1841
       1841
       +
       let test_cookie_header_edge_cases env =

     

       1842
       1842
       +
         let clock = Eio.Stdenv.clock env in

     

       1843
       1843
       +
       

     

       1844
       1844
       +
         let test input expected_count description =

     

       1845
       1845
       +
           let result =

     

       1846
       1846
       +
             of_cookie_header

     

       1847
       1847
       +
               ~now:(fun () ->

     

       1848
       1848
       +
                 Ptime.of_float_s (Eio.Time.now clock)

     

       1849
       1849
       +
                 |> Option.value ~default:Ptime.epoch)

     

       1850
       1850
       +
               ~domain:"ex.com" ~path:"/" input

     

       1851
       1851
       +
           in

     

       1852
       1852
       +
           match result with

     

       1853
       1853
       +
           | Ok cookies ->

     

       1854
       1854
       +
               Alcotest.(check int) description expected_count (List.length cookies)

     

       1855
       1855
       +
           | Error msg ->

     

       1856
       1856
       +
               Alcotest.fail (description ^ " failed: " ^ msg)

     

       1857
       1857
       +
         in

     

       1858
       1858
       +
       

     

       1859
       1859
       +
         test "" 0 "empty string";

     

       1860
       1860
       +
         test ";;" 0 "only separators";

     

       1861
       1861
       +
         test "a=1;;b=2" 2 "double separator";

     

       1862
       1862
       +
         test " a=1 ; b=2 " 2 "excess whitespace";

     

       1863
       1863
       +
         test "   " 0 "only whitespace"

     

       1864
       1864
       +
       

     

       1865
       1865
       +
       let test_cookie_header_with_errors env =

     

       1866
       1866
       +
         let clock = Eio.Stdenv.clock env in

     

       1867
       1867
       +
       

     

       1868
       1868
       +
         (* Invalid cookie (empty name) should cause entire parse to fail *)

     

       1869
       1869
       +
         let result =

     

       1870
       1870
       +
           of_cookie_header

     

       1871
       1871
       +
             ~now:(fun () ->

     

       1872
       1872
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1873
       1873
       +
               |> Option.value ~default:Ptime.epoch)

     

       1874
       1874
       +
             ~domain:"ex.com" ~path:"/" "valid=1;=noname;valid2=2"

     

       1875
       1875
       +
         in

     

       1876
       1876
       +
       

     

       1877
       1877
       +
         (* Error should have descriptive message about the invalid cookie *)

     

       1878
       1878
       +
         let contains_substring s sub =

     

       1879
       1879
       +
           try

     

       1880
       1880
       +
             let _ = Str.search_forward (Str.regexp_string sub) s 0 in

     

       1881
       1881
       +
             true

     

       1882
       1882
       +
           with Not_found -> false

     

       1883
       1883
       +
         in

     

       1884
       1884
       +
         match result with

     

       1885
       1885
       +
         | Error msg ->

     

       1886
       1886
       +
             let has_name = contains_substring msg "name" in

     

       1887
       1887
       +
             let has_empty = contains_substring msg "empty" in

     

       1888
       1888
       +
             Alcotest.(check bool)

     

       1889
       1889
       +
               "error mentions name or empty" true (has_name || has_empty)

     

       1890
       1890
       +
         | Ok _ -> Alcotest.fail "Expected error for empty cookie name"

     

       1891
       1891
       +
       

     

       1892
       1892
       +
       (* Max-Age and Expires Interaction *)

     

       1893
       1893
       +
       

     

       1894
       1894
       +
       let test_max_age_and_expires_both_present env =

     

       1895
       1895
       +
         let clock = Eio.Stdenv.clock env in

     

       1896
       1896
       +
         let now =

     

       1897
       1897
       +
           Ptime.of_float_s (Eio.Time.now clock) |> Option.value ~default:Ptime.epoch

     

       1898
       1898
       +
         in

     

       1899
       1899
       +
         let future = Ptime.add_span now (Ptime.Span.of_int_s 7200) |> Option.get in

     

       1900
       1900
       +
       

     

       1901
       1901
       +
         (* Create cookie with both *)

     

       1902
       1902
       +
         let cookie =

     

       1903
       1903
       +
           make ~domain:"ex.com" ~path:"/" ~name:"dual" ~value:"val"

     

       1904
       1904
       +
             ~max_age:(Ptime.Span.of_int_s 3600) ~expires:(`DateTime future)

     

       1905
       1905
       +
             ~creation_time:now ~last_access:now ()

     

       1906
       1906
       +
         in

     

       1907
       1907
       +
       

     

       1908
       1908
       +
         (* Both should be present *)

     

       1909
       1909
       +
         begin match max_age cookie with

     

       1910
       1910
       +
         | Some span -> begin

     

       1911
       1911
       +
             match Ptime.Span.to_int_s span with

     

       1912
       1912
       +
             | Some s ->

     

       1913
       1913
       +
                 Alcotest.(check int64) "max_age present" 3600L (Int64.of_int s)

     

       1914
       1914
       +
             | None -> Alcotest.fail "max_age span could not be converted to int"

     

       1915
       1915
       +
           end

     

       1916
       1916
       +
         | None -> Alcotest.fail "max_age should be present"

     

       1917
       1917
       +
         end;

     

       1918
       1918
       +
       

     

       1919
       1919
       +
         begin match expires cookie with

     

       1920
       1920
       +
         | Some (`DateTime t) when Ptime.equal t future -> ()

     

       1921
       1921
       +
         | _ -> Alcotest.fail "expires should be present"

     

       1922
       1922
       +
         end;

     

       1923
       1923
       +
       

     

       1924
       1924
       +
         (* Both should appear in serialization *)

     

       1925
       1925
       +
         let header = make_set_cookie_header cookie in

     

       1926
       1926
       +
         let contains_substring s sub =

     

       1927
       1927
       +
           try

     

       1928
       1928
       +
             let _ = Str.search_forward (Str.regexp_string sub) s 0 in

     

       1929
       1929
       +
             true

     

       1930
       1930
       +
           with Not_found -> false

     

       1931
       1931
       +
         in

     

       1932
       1932
       +
         let has_max_age = contains_substring header "Max-Age=3600" in

     

       1933
       1933
       +
         let has_expires = contains_substring header "Expires=" in

     

       1934
       1934
       +
         Alcotest.(check bool) "contains Max-Age" true has_max_age;

     

       1935
       1935
       +
         Alcotest.(check bool) "contains Expires" true has_expires

     

       1936
       1936
       +
       

     

       1937
       1937
       +
       let test_parse_max_age_and_expires env =

     

       1938
       1938
       +
         let clock = Eio.Stdenv.clock env in

     

       1939
       1939
       +
       

     

       1940
       1940
       +
         (* Parse Set-Cookie with both attributes *)

     

       1941
       1941
       +
         match

     

       1942
       1942
       +
           of_set_cookie_header

     

       1943
       1943
       +
             ~now:(fun () ->

     

       1944
       1944
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1945
       1945
       +
               |> Option.value ~default:Ptime.epoch)

     

       1946
       1946
       +
             ~domain:"ex.com" ~path:"/"

     

       1947
       1947
       +
             "id=123; Max-Age=3600; Expires=Wed, 21 Oct 2025 07:28:00 GMT"

     

       1948
       1948
       +
         with

     

       1949
       1949
       +
         | Ok c ->

     

       1950
       1950
       +
             (* Both should be stored *)

     

       1951
       1951
       +
             begin match max_age c with

     

       1952
       1952
       +
             | Some span -> begin

     

       1953
       1953
       +
                 match Ptime.Span.to_int_s span with

     

       1954
       1954
       +
                 | Some s ->

     

       1955
       1955
       +
                     Alcotest.(check int64) "max_age parsed" 3600L (Int64.of_int s)

     

       1956
       1956
       +
                 | None -> Alcotest.fail "max_age span could not be converted to int"

     

       1957
       1957
       +
               end

     

       1958
       1958
       +
             | None -> Alcotest.fail "max_age should be parsed"

     

       1959
       1959
       +
             end;

     

       1960
       1960
       +
       

     

       1961
       1961
       +
             begin match expires c with

     

       1962
       1962
       +
             | Some (`DateTime _) -> ()

     

       1963
       1963
       +
             | _ -> Alcotest.fail "expires should be parsed"

     

       1964
       1964
       +
             end

     

       1965
       1965
       +
         | Error msg -> Alcotest.fail ("Should parse cookie with both attributes: " ^ msg)

     

       1966
       1966
       +
       

     

       1967
       1967
       +
       (* ============================================================================ *)

     

       1968
       1968
       +
       (* Host-Only Flag Tests (RFC 6265 Section 5.3) *)

     

       1969
       1969
       +
       (* ============================================================================ *)

     

       1970
       1970
       +
       

     

       1971
       1971
       +
       let test_host_only_without_domain_attribute () =

     

       1972
       1972
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1973
       1973
       +
         let clock = Eio_mock.Clock.make () in

     

       1974
       1974
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1975
       1975
       +
       

     

       1976
       1976
       +
         (* Cookie without Domain attribute should have host_only=true *)

     

       1977
       1977
       +
         let header = "session=abc123; Secure; HttpOnly" in

     

       1978
       1978
       +
         let cookie_opt =

     

       1979
       1979
       +
           of_set_cookie_header

     

       1980
       1980
       +
             ~now:(fun () ->

     

       1981
       1981
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       1982
       1982
       +
               |> Option.value ~default:Ptime.epoch)

     

       1983
       1983
       +
             ~domain:"example.com" ~path:"/" header

     

       1984
       1984
       +
         in

     

       1985
       1985
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       1986
       1986
       +
         let cookie = Result.get_ok cookie_opt in

     

       1987
       1987
       +
         Alcotest.(check bool) "host_only is true" true (Cookeio.host_only cookie);

     

       1988
       1988
       +
         Alcotest.(check string) "domain is request host" "example.com" (Cookeio.domain cookie)

     

       1989
       1989
       +
       

     

       1990
       1990
       +
       let test_host_only_with_domain_attribute () =

     

       1991
       1991
       +
         Eio_mock.Backend.run @@ fun () ->

     

       1992
       1992
       +
         let clock = Eio_mock.Clock.make () in

     

       1993
       1993
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       1994
       1994
       +
       

     

       1995
       1995
       +
         (* Cookie with Domain attribute should have host_only=false *)

     

       1996
       1996
       +
         let header = "session=abc123; Domain=example.com; Secure" in

     

       1997
       1997
       +
         let cookie_opt =

     

       1998
       1998
       +
           of_set_cookie_header

     

       1999
       1999
       +
             ~now:(fun () ->

     

       2000
       2000
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       2001
       2001
       +
               |> Option.value ~default:Ptime.epoch)

     

       2002
       2002
       +
             ~domain:"example.com" ~path:"/" header

     

       2003
       2003
       +
         in

     

       2004
       2004
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       2005
       2005
       +
         let cookie = Result.get_ok cookie_opt in

     

       2006
       2006
       +
         Alcotest.(check bool) "host_only is false" false (Cookeio.host_only cookie);

     

       2007
       2007
       +
         Alcotest.(check string) "domain is attribute value" "example.com" (Cookeio.domain cookie)

     

       2008
       2008
       +
       

     

       2009
       2009
       +
       let test_host_only_with_dotted_domain_attribute () =

     

       2010
       2010
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2011
       2011
       +
         let clock = Eio_mock.Clock.make () in

     

       2012
       2012
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2013
       2013
       +
       

     

       2014
       2014
       +
         (* Cookie with .domain should have host_only=false and normalized domain *)

     

       2015
       2015
       +
         let header = "session=abc123; Domain=.example.com" in

     

       2016
       2016
       +
         let cookie_opt =

     

       2017
       2017
       +
           of_set_cookie_header

     

       2018
       2018
       +
             ~now:(fun () ->

     

       2019
       2019
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       2020
       2020
       +
               |> Option.value ~default:Ptime.epoch)

     

       2021
       2021
       +
             ~domain:"example.com" ~path:"/" header

     

       2022
       2022
       +
         in

     

       2023
       2023
       +
         Alcotest.(check bool) "cookie parsed" true (Result.is_ok cookie_opt);

     

       2024
       2024
       +
         let cookie = Result.get_ok cookie_opt in

     

       2025
       2025
       +
         Alcotest.(check bool) "host_only is false" false (Cookeio.host_only cookie);

     

       2026
       2026
       +
         Alcotest.(check string) "domain normalized" "example.com" (Cookeio.domain cookie)

     

       2027
       2027
       +
       

     

       2028
       2028
       +
       let test_host_only_domain_matching () =

     

       2029
       2029
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2030
       2030
       +
         let clock = Eio_mock.Clock.make () in

     

       2031
       2031
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2032
       2032
       +
       

     

       2033
       2033
       +
         let jar = create () in

     

       2034
       2034
       +
       

     

       2035
       2035
       +
         (* Add a host-only cookie (no Domain attribute) *)

     

       2036
       2036
       +
         let host_only_cookie =

     

       2037
       2037
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"host_only" ~value:"val1"

     

       2038
       2038
       +
             ~secure:false ~http_only:false ~host_only:true

     

       2039
       2039
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2040
       2040
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2041
       2041
       +
         in

     

       2042
       2042
       +
         add_cookie jar host_only_cookie;

     

       2043
       2043
       +
       

     

       2044
       2044
       +
         (* Add a domain cookie (with Domain attribute) *)

     

       2045
       2045
       +
         let domain_cookie =

     

       2046
       2046
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"domain" ~value:"val2"

     

       2047
       2047
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2048
       2048
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2049
       2049
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2050
       2050
       +
         in

     

       2051
       2051
       +
         add_cookie jar domain_cookie;

     

       2052
       2052
       +
       

     

       2053
       2053
       +
         (* Both cookies should match exact domain *)

     

       2054
       2054
       +
         let cookies_exact =

     

       2055
       2055
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       2056
       2056
       +
         in

     

       2057
       2057
       +
         Alcotest.(check int) "both match exact domain" 2 (List.length cookies_exact);

     

       2058
       2058
       +
       

     

       2059
       2059
       +
         (* Only domain cookie should match subdomain *)

     

       2060
       2060
       +
         let cookies_sub =

     

       2061
       2061
       +
           get_cookies jar ~clock ~domain:"sub.example.com" ~path:"/" ~is_secure:false

     

       2062
       2062
       +
         in

     

       2063
       2063
       +
         Alcotest.(check int) "only domain cookie matches subdomain" 1 (List.length cookies_sub);

     

       2064
       2064
       +
         let sub_cookie = List.hd cookies_sub in

     

       2065
       2065
       +
         Alcotest.(check string) "subdomain match is domain cookie" "domain" (Cookeio.name sub_cookie)

     

       2066
       2066
       +
       

     

       2067
       2067
       +
       let test_host_only_cookie_header_parsing () =

     

       2068
       2068
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2069
       2069
       +
         let clock = Eio_mock.Clock.make () in

     

       2070
       2070
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2071
       2071
       +
       

     

       2072
       2072
       +
         (* Cookies from Cookie header should have host_only=true *)

     

       2073
       2073
       +
         let result =

     

       2074
       2074
       +
           of_cookie_header

     

       2075
       2075
       +
             ~now:(fun () ->

     

       2076
       2076
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       2077
       2077
       +
               |> Option.value ~default:Ptime.epoch)

     

       2078
       2078
       +
             ~domain:"example.com" ~path:"/" "session=abc; theme=dark"

     

       2079
       2079
       +
         in

     

       2080
       2080
       +
         match result with

     

       2081
       2081
       +
         | Error msg -> Alcotest.fail ("Parse failed: " ^ msg)

     

       2082
       2082
       +
         | Ok cookies ->

     

       2083
       2083
       +
             Alcotest.(check int) "parsed 2 cookies" 2 (List.length cookies);

     

       2084
       2084
       +
             List.iter (fun c ->

     

       2085
       2085
       +
               Alcotest.(check bool)

     

       2086
       2086
       +
                 ("host_only is true for " ^ Cookeio.name c)

     

       2087
       2087
       +
                 true (Cookeio.host_only c)

     

       2088
       2088
       +
             ) cookies

     

       2089
       2089
       +
       

     

       2090
       2090
       +
       let test_host_only_mozilla_format_round_trip () =

     

       2091
       2091
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2092
       2092
       +
         let clock = Eio_mock.Clock.make () in

     

       2093
       2093
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2094
       2094
       +
       

     

       2095
       2095
       +
         let jar = create () in

     

       2096
       2096
       +
       

     

       2097
       2097
       +
         (* Add host-only cookie *)

     

       2098
       2098
       +
         let host_only =

     

       2099
       2099
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"hostonly" ~value:"v1"

     

       2100
       2100
       +
             ~secure:false ~http_only:false ~host_only:true

     

       2101
       2101
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2102
       2102
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2103
       2103
       +
         in

     

       2104
       2104
       +
         add_cookie jar host_only;

     

       2105
       2105
       +
       

     

       2106
       2106
       +
         (* Add domain cookie *)

     

       2107
       2107
       +
         let domain_cookie =

     

       2108
       2108
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"domain" ~value:"v2"

     

       2109
       2109
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2110
       2110
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2111
       2111
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2112
       2112
       +
         in

     

       2113
       2113
       +
         add_cookie jar domain_cookie;

     

       2114
       2114
       +
       

     

       2115
       2115
       +
         (* Round trip through Mozilla format *)

     

       2116
       2116
       +
         let mozilla = to_mozilla_format jar in

     

       2117
       2117
       +
         let jar2 = from_mozilla_format ~clock mozilla in

     

       2118
       2118
       +
         let cookies = get_all_cookies jar2 in

     

       2119
       2119
       +
       

     

       2120
       2120
       +
         Alcotest.(check int) "2 cookies after round trip" 2 (List.length cookies);

     

       2121
       2121
       +
       

     

       2122
       2122
       +
         let find name_val = List.find (fun c -> Cookeio.name c = name_val) cookies in

     

       2123
       2123
       +
         Alcotest.(check bool) "hostonly preserved" true (Cookeio.host_only (find "hostonly"));

     

       2124
       2124
       +
         Alcotest.(check bool) "domain preserved" false (Cookeio.host_only (find "domain"))

     

       2125
       2125
       +
       

     

       2126
       2126
       +
       (* ============================================================================ *)

     

       2127
       2127
       +
       (* Path Matching Tests (RFC 6265 Section 5.1.4) *)

     

       2128
       2128
       +
       (* ============================================================================ *)

     

       2129
       2129
       +
       

     

       2130
       2130
       +
       let test_path_matching_identical () =

     

       2131
       2131
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2132
       2132
       +
         let clock = Eio_mock.Clock.make () in

     

       2133
       2133
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2134
       2134
       +
       

     

       2135
       2135
       +
         let jar = create () in

     

       2136
       2136
       +
         let cookie =

     

       2137
       2137
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo" ~name:"test" ~value:"val"

     

       2138
       2138
       +
             ~secure:false ~http_only:false

     

       2139
       2139
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2140
       2140
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2141
       2141
       +
         in

     

       2142
       2142
       +
         add_cookie jar cookie;

     

       2143
       2143
       +
       

     

       2144
       2144
       +
         (* Identical path should match *)

     

       2145
       2145
       +
         let cookies =

     

       2146
       2146
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo" ~is_secure:false

     

       2147
       2147
       +
         in

     

       2148
       2148
       +
         Alcotest.(check int) "identical path matches" 1 (List.length cookies)

     

       2149
       2149
       +
       

     

       2150
       2150
       +
       let test_path_matching_with_trailing_slash () =

     

       2151
       2151
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2152
       2152
       +
         let clock = Eio_mock.Clock.make () in

     

       2153
       2153
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2154
       2154
       +
       

     

       2155
       2155
       +
         let jar = create () in

     

       2156
       2156
       +
         let cookie =

     

       2157
       2157
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo/" ~name:"test" ~value:"val"

     

       2158
       2158
       +
             ~secure:false ~http_only:false

     

       2159
       2159
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2160
       2160
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2161
       2161
       +
         in

     

       2162
       2162
       +
         add_cookie jar cookie;

     

       2163
       2163
       +
       

     

       2164
       2164
       +
         (* Cookie path /foo/ should match /foo/bar *)

     

       2165
       2165
       +
         let cookies =

     

       2166
       2166
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo/bar" ~is_secure:false

     

       2167
       2167
       +
         in

     

       2168
       2168
       +
         Alcotest.(check int) "/foo/ matches /foo/bar" 1 (List.length cookies);

     

       2169
       2169
       +
       

     

       2170
       2170
       +
         (* Cookie path /foo/ should match /foo/ *)

     

       2171
       2171
       +
         let cookies2 =

     

       2172
       2172
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo/" ~is_secure:false

     

       2173
       2173
       +
         in

     

       2174
       2174
       +
         Alcotest.(check int) "/foo/ matches /foo/" 1 (List.length cookies2)

     

       2175
       2175
       +
       

     

       2176
       2176
       +
       let test_path_matching_prefix_with_slash () =

     

       2177
       2177
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2178
       2178
       +
         let clock = Eio_mock.Clock.make () in

     

       2179
       2179
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2180
       2180
       +
       

     

       2181
       2181
       +
         let jar = create () in

     

       2182
       2182
       +
         let cookie =

     

       2183
       2183
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo" ~name:"test" ~value:"val"

     

       2184
       2184
       +
             ~secure:false ~http_only:false

     

       2185
       2185
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2186
       2186
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2187
       2187
       +
         in

     

       2188
       2188
       +
         add_cookie jar cookie;

     

       2189
       2189
       +
       

     

       2190
       2190
       +
         (* Cookie path /foo should match /foo/bar (next char is /) *)

     

       2191
       2191
       +
         let cookies =

     

       2192
       2192
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo/bar" ~is_secure:false

     

       2193
       2193
       +
         in

     

       2194
       2194
       +
         Alcotest.(check int) "/foo matches /foo/bar" 1 (List.length cookies);

     

       2195
       2195
       +
       

     

       2196
       2196
       +
         (* Cookie path /foo should match /foo/ *)

     

       2197
       2197
       +
         let cookies2 =

     

       2198
       2198
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo/" ~is_secure:false

     

       2199
       2199
       +
         in

     

       2200
       2200
       +
         Alcotest.(check int) "/foo matches /foo/" 1 (List.length cookies2)

     

       2201
       2201
       +
       

     

       2202
       2202
       +
       let test_path_matching_no_false_prefix () =

     

       2203
       2203
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2204
       2204
       +
         let clock = Eio_mock.Clock.make () in

     

       2205
       2205
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2206
       2206
       +
       

     

       2207
       2207
       +
         let jar = create () in

     

       2208
       2208
       +
         let cookie =

     

       2209
       2209
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo" ~name:"test" ~value:"val"

     

       2210
       2210
       +
             ~secure:false ~http_only:false

     

       2211
       2211
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2212
       2212
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2213
       2213
       +
         in

     

       2214
       2214
       +
         add_cookie jar cookie;

     

       2215
       2215
       +
       

     

       2216
       2216
       +
         (* Cookie path /foo should NOT match /foobar (no / separator) *)

     

       2217
       2217
       +
         let cookies =

     

       2218
       2218
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foobar" ~is_secure:false

     

       2219
       2219
       +
         in

     

       2220
       2220
       +
         Alcotest.(check int) "/foo does NOT match /foobar" 0 (List.length cookies);

     

       2221
       2221
       +
       

     

       2222
       2222
       +
         (* Cookie path /foo should NOT match /foob *)

     

       2223
       2223
       +
         let cookies2 =

     

       2224
       2224
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foob" ~is_secure:false

     

       2225
       2225
       +
         in

     

       2226
       2226
       +
         Alcotest.(check int) "/foo does NOT match /foob" 0 (List.length cookies2)

     

       2227
       2227
       +
       

     

       2228
       2228
       +
       let test_path_matching_root () =

     

       2229
       2229
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2230
       2230
       +
         let clock = Eio_mock.Clock.make () in

     

       2231
       2231
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2232
       2232
       +
       

     

       2233
       2233
       +
         let jar = create () in

     

       2234
       2234
       +
         let cookie =

     

       2235
       2235
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"val"

     

       2236
       2236
       +
             ~secure:false ~http_only:false

     

       2237
       2237
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2238
       2238
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2239
       2239
       +
         in

     

       2240
       2240
       +
         add_cookie jar cookie;

     

       2241
       2241
       +
       

     

       2242
       2242
       +
         (* Root path should match everything *)

     

       2243
       2243
       +
         let cookies1 =

     

       2244
       2244
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       2245
       2245
       +
         in

     

       2246
       2246
       +
         Alcotest.(check int) "/ matches /" 1 (List.length cookies1);

     

       2247
       2247
       +
       

     

       2248
       2248
       +
         let cookies2 =

     

       2249
       2249
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo" ~is_secure:false

     

       2250
       2250
       +
         in

     

       2251
       2251
       +
         Alcotest.(check int) "/ matches /foo" 1 (List.length cookies2);

     

       2252
       2252
       +
       

     

       2253
       2253
       +
         let cookies3 =

     

       2254
       2254
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo/bar/baz" ~is_secure:false

     

       2255
       2255
       +
         in

     

       2256
       2256
       +
         Alcotest.(check int) "/ matches /foo/bar/baz" 1 (List.length cookies3)

     

       2257
       2257
       +
       

     

       2258
       2258
       +
       let test_path_matching_no_match () =

     

       2259
       2259
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2260
       2260
       +
         let clock = Eio_mock.Clock.make () in

     

       2261
       2261
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2262
       2262
       +
       

     

       2263
       2263
       +
         let jar = create () in

     

       2264
       2264
       +
         let cookie =

     

       2265
       2265
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo/bar" ~name:"test" ~value:"val"

     

       2266
       2266
       +
             ~secure:false ~http_only:false

     

       2267
       2267
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2268
       2268
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2269
       2269
       +
         in

     

       2270
       2270
       +
         add_cookie jar cookie;

     

       2271
       2271
       +
       

     

       2272
       2272
       +
         (* Cookie path /foo/bar should NOT match /foo *)

     

       2273
       2273
       +
         let cookies =

     

       2274
       2274
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo" ~is_secure:false

     

       2275
       2275
       +
         in

     

       2276
       2276
       +
         Alcotest.(check int) "/foo/bar does NOT match /foo" 0 (List.length cookies);

     

       2277
       2277
       +
       

     

       2278
       2278
       +
         (* Cookie path /foo/bar should NOT match / *)

     

       2279
       2279
       +
         let cookies2 =

     

       2280
       2280
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       2281
       2281
       +
         in

     

       2282
       2282
       +
         Alcotest.(check int) "/foo/bar does NOT match /" 0 (List.length cookies2);

     

       2283
       2283
       +
       

     

       2284
       2284
       +
         (* Cookie path /foo/bar should NOT match /baz *)

     

       2285
       2285
       +
         let cookies3 =

     

       2286
       2286
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/baz" ~is_secure:false

     

       2287
       2287
       +
         in

     

       2288
       2288
       +
         Alcotest.(check int) "/foo/bar does NOT match /baz" 0 (List.length cookies3)

     

       2289
       2289
       +
       

     

       2290
       2290
       +
       (* ============================================================================ *)

     

       2291
       2291
       +
       (* Cookie Ordering Tests (RFC 6265 Section 5.4, Step 2) *)

     

       2292
       2292
       +
       (* ============================================================================ *)

     

       2293
       2293
       +
       

     

       2294
       2294
       +
       let test_cookie_ordering_by_path_length () =

     

       2295
       2295
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2296
       2296
       +
         let clock = Eio_mock.Clock.make () in

     

       2297
       2297
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2298
       2298
       +
       

     

       2299
       2299
       +
         let jar = create () in

     

       2300
       2300
       +
       

     

       2301
       2301
       +
         (* Add cookies with different path lengths, but same creation time *)

     

       2302
       2302
       +
         let cookie_short =

     

       2303
       2303
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"short" ~value:"v1"

     

       2304
       2304
       +
             ~secure:false ~http_only:false

     

       2305
       2305
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2306
       2306
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2307
       2307
       +
         in

     

       2308
       2308
       +
         let cookie_medium =

     

       2309
       2309
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo" ~name:"medium" ~value:"v2"

     

       2310
       2310
       +
             ~secure:false ~http_only:false

     

       2311
       2311
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2312
       2312
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2313
       2313
       +
         in

     

       2314
       2314
       +
         let cookie_long =

     

       2315
       2315
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo/bar" ~name:"long" ~value:"v3"

     

       2316
       2316
       +
             ~secure:false ~http_only:false

     

       2317
       2317
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2318
       2318
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2319
       2319
       +
         in

     

       2320
       2320
       +
       

     

       2321
       2321
       +
         (* Add in random order *)

     

       2322
       2322
       +
         add_cookie jar cookie_short;

     

       2323
       2323
       +
         add_cookie jar cookie_long;

     

       2324
       2324
       +
         add_cookie jar cookie_medium;

     

       2325
       2325
       +
       

     

       2326
       2326
       +
         (* Get cookies for path /foo/bar/baz - all three should match *)

     

       2327
       2327
       +
         let cookies =

     

       2328
       2328
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo/bar/baz" ~is_secure:false

     

       2329
       2329
       +
         in

     

       2330
       2330
       +
       

     

       2331
       2331
       +
         Alcotest.(check int) "all 3 cookies match" 3 (List.length cookies);

     

       2332
       2332
       +
       

     

       2333
       2333
       +
         (* Verify order: longest path first *)

     

       2334
       2334
       +
         let names = List.map Cookeio.name cookies in

     

       2335
       2335
       +
         Alcotest.(check (list string))

     

       2336
       2336
       +
           "cookies ordered by path length (longest first)"

     

       2337
       2337
       +
           [ "long"; "medium"; "short" ]

     

       2338
       2338
       +
           names

     

       2339
       2339
       +
       

     

       2340
       2340
       +
       let test_cookie_ordering_by_creation_time () =

     

       2341
       2341
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2342
       2342
       +
         let clock = Eio_mock.Clock.make () in

     

       2343
       2343
       +
         Eio_mock.Clock.set_time clock 2000.0;

     

       2344
       2344
       +
       

     

       2345
       2345
       +
         let jar = create () in

     

       2346
       2346
       +
       

     

       2347
       2347
       +
         (* Add cookies with same path but different creation times *)

     

       2348
       2348
       +
         let cookie_new =

     

       2349
       2349
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"new" ~value:"v1"

     

       2350
       2350
       +
             ~secure:false ~http_only:false

     

       2351
       2351
       +
             ~creation_time:(Ptime.of_float_s 1500.0 |> Option.get)

     

       2352
       2352
       +
             ~last_access:(Ptime.of_float_s 1500.0 |> Option.get) ()

     

       2353
       2353
       +
         in

     

       2354
       2354
       +
         let cookie_old =

     

       2355
       2355
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"old" ~value:"v2"

     

       2356
       2356
       +
             ~secure:false ~http_only:false

     

       2357
       2357
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2358
       2358
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2359
       2359
       +
         in

     

       2360
       2360
       +
         let cookie_middle =

     

       2361
       2361
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"middle" ~value:"v3"

     

       2362
       2362
       +
             ~secure:false ~http_only:false

     

       2363
       2363
       +
             ~creation_time:(Ptime.of_float_s 1200.0 |> Option.get)

     

       2364
       2364
       +
             ~last_access:(Ptime.of_float_s 1200.0 |> Option.get) ()

     

       2365
       2365
       +
         in

     

       2366
       2366
       +
       

     

       2367
       2367
       +
         (* Add in random order *)

     

       2368
       2368
       +
         add_cookie jar cookie_new;

     

       2369
       2369
       +
         add_cookie jar cookie_old;

     

       2370
       2370
       +
         add_cookie jar cookie_middle;

     

       2371
       2371
       +
       

     

       2372
       2372
       +
         let cookies =

     

       2373
       2373
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       2374
       2374
       +
         in

     

       2375
       2375
       +
       

     

       2376
       2376
       +
         Alcotest.(check int) "all 3 cookies match" 3 (List.length cookies);

     

       2377
       2377
       +
       

     

       2378
       2378
       +
         (* Verify order: earlier creation time first (for same path length) *)

     

       2379
       2379
       +
         let names = List.map Cookeio.name cookies in

     

       2380
       2380
       +
         Alcotest.(check (list string))

     

       2381
       2381
       +
           "cookies ordered by creation time (earliest first)"

     

       2382
       2382
       +
           [ "old"; "middle"; "new" ]

     

       2383
       2383
       +
           names

     

       2384
       2384
       +
       

     

       2385
       2385
       +
       let test_cookie_ordering_combined () =

     

       2386
       2386
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2387
       2387
       +
         let clock = Eio_mock.Clock.make () in

     

       2388
       2388
       +
         Eio_mock.Clock.set_time clock 2000.0;

     

       2389
       2389
       +
       

     

       2390
       2390
       +
         let jar = create () in

     

       2391
       2391
       +
       

     

       2392
       2392
       +
         (* Mix of different paths and creation times *)

     

       2393
       2393
       +
         let cookie_a =

     

       2394
       2394
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo" ~name:"a" ~value:"v1"

     

       2395
       2395
       +
             ~secure:false ~http_only:false

     

       2396
       2396
       +
             ~creation_time:(Ptime.of_float_s 1500.0 |> Option.get)

     

       2397
       2397
       +
             ~last_access:(Ptime.of_float_s 1500.0 |> Option.get) ()

     

       2398
       2398
       +
         in

     

       2399
       2399
       +
         let cookie_b =

     

       2400
       2400
       +
           Cookeio.make ~domain:"example.com" ~path:"/foo" ~name:"b" ~value:"v2"

     

       2401
       2401
       +
             ~secure:false ~http_only:false

     

       2402
       2402
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2403
       2403
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2404
       2404
       +
         in

     

       2405
       2405
       +
         let cookie_c =

     

       2406
       2406
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"c" ~value:"v3"

     

       2407
       2407
       +
             ~secure:false ~http_only:false

     

       2408
       2408
       +
             ~creation_time:(Ptime.of_float_s 500.0 |> Option.get)

     

       2409
       2409
       +
             ~last_access:(Ptime.of_float_s 500.0 |> Option.get) ()

     

       2410
       2410
       +
         in

     

       2411
       2411
       +
       

     

       2412
       2412
       +
         add_cookie jar cookie_a;

     

       2413
       2413
       +
         add_cookie jar cookie_c;

     

       2414
       2414
       +
         add_cookie jar cookie_b;

     

       2415
       2415
       +
       

     

       2416
       2416
       +
         let cookies =

     

       2417
       2417
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/foo/bar" ~is_secure:false

     

       2418
       2418
       +
         in

     

       2419
       2419
       +
       

     

       2420
       2420
       +
         Alcotest.(check int) "all 3 cookies match" 3 (List.length cookies);

     

       2421
       2421
       +
       

     

       2422
       2422
       +
         (* /foo cookies (length 4) should come before / cookie (length 1)

     

       2423
       2423
       +
            Within /foo, earlier creation time (b=1000) should come before (a=1500) *)

     

       2424
       2424
       +
         let names = List.map Cookeio.name cookies in

     

       2425
       2425
       +
         Alcotest.(check (list string))

     

       2426
       2426
       +
           "cookies ordered by path length then creation time"

     

       2427
       2427
       +
           [ "b"; "a"; "c" ]

     

       2428
       2428
       +
           names

     

       2429
       2429
       +
       

     

       2430
       2430
       +
       (* ============================================================================ *)

     

       2431
       2431
       +
       (* Creation Time Preservation Tests (RFC 6265 Section 5.3, Step 11.3) *)

     

       2432
       2432
       +
       (* ============================================================================ *)

     

       2433
       2433
       +
       

     

       2434
       2434
       +
       let test_creation_time_preserved_on_update () =

     

       2435
       2435
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2436
       2436
       +
         let clock = Eio_mock.Clock.make () in

     

       2437
       2437
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2438
       2438
       +
       

     

       2439
       2439
       +
         let jar = create () in

     

       2440
       2440
       +
       

     

       2441
       2441
       +
         (* Add initial cookie with creation_time=500 *)

     

       2442
       2442
       +
         let original_creation = Ptime.of_float_s 500.0 |> Option.get in

     

       2443
       2443
       +
         let cookie_v1 =

     

       2444
       2444
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"session" ~value:"v1"

     

       2445
       2445
       +
             ~secure:false ~http_only:false

     

       2446
       2446
       +
             ~creation_time:original_creation

     

       2447
       2447
       +
             ~last_access:(Ptime.of_float_s 500.0 |> Option.get) ()

     

       2448
       2448
       +
         in

     

       2449
       2449
       +
         add_cookie jar cookie_v1;

     

       2450
       2450
       +
       

     

       2451
       2451
       +
         (* Update the cookie with a new value (creation_time=1000) *)

     

       2452
       2452
       +
         Eio_mock.Clock.set_time clock 1500.0;

     

       2453
       2453
       +
         let cookie_v2 =

     

       2454
       2454
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"session" ~value:"v2"

     

       2455
       2455
       +
             ~secure:false ~http_only:false

     

       2456
       2456
       +
             ~creation_time:(Ptime.of_float_s 1500.0 |> Option.get)

     

       2457
       2457
       +
             ~last_access:(Ptime.of_float_s 1500.0 |> Option.get) ()

     

       2458
       2458
       +
         in

     

       2459
       2459
       +
         add_cookie jar cookie_v2;

     

       2460
       2460
       +
       

     

       2461
       2461
       +
         (* Get the cookie and verify creation_time was preserved *)

     

       2462
       2462
       +
         let cookies =

     

       2463
       2463
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       2464
       2464
       +
         in

     

       2465
       2465
       +
         Alcotest.(check int) "still one cookie" 1 (List.length cookies);

     

       2466
       2466
       +
       

     

       2467
       2467
       +
         let cookie = List.hd cookies in

     

       2468
       2468
       +
         Alcotest.(check string) "value was updated" "v2" (Cookeio.value cookie);

     

       2469
       2469
       +
       

     

       2470
       2470
       +
         (* Creation time should be preserved from original cookie *)

     

       2471
       2471
       +
         let creation_float =

     

       2472
       2472
       +
           Ptime.to_float_s (Cookeio.creation_time cookie)

     

       2473
       2473
       +
         in

     

       2474
       2474
       +
         Alcotest.(check (float 0.001))

     

       2475
       2475
       +
           "creation_time preserved from original"

     

       2476
       2476
       +
           500.0 creation_float

     

       2477
       2477
       +
       

     

       2478
       2478
       +
       let test_creation_time_preserved_add_original () =

     

       2479
       2479
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2480
       2480
       +
         let clock = Eio_mock.Clock.make () in

     

       2481
       2481
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2482
       2482
       +
       

     

       2483
       2483
       +
         let jar = create () in

     

       2484
       2484
       +
       

     

       2485
       2485
       +
         (* Add initial original cookie *)

     

       2486
       2486
       +
         let original_creation = Ptime.of_float_s 100.0 |> Option.get in

     

       2487
       2487
       +
         let cookie_v1 =

     

       2488
       2488
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"v1"

     

       2489
       2489
       +
             ~secure:false ~http_only:false

     

       2490
       2490
       +
             ~creation_time:original_creation

     

       2491
       2491
       +
             ~last_access:(Ptime.of_float_s 100.0 |> Option.get) ()

     

       2492
       2492
       +
         in

     

       2493
       2493
       +
         add_original jar cookie_v1;

     

       2494
       2494
       +
       

     

       2495
       2495
       +
         (* Replace with new original cookie *)

     

       2496
       2496
       +
         let cookie_v2 =

     

       2497
       2497
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"test" ~value:"v2"

     

       2498
       2498
       +
             ~secure:false ~http_only:false

     

       2499
       2499
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2500
       2500
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2501
       2501
       +
         in

     

       2502
       2502
       +
         add_original jar cookie_v2;

     

       2503
       2503
       +
       

     

       2504
       2504
       +
         let cookies = get_all_cookies jar in

     

       2505
       2505
       +
         Alcotest.(check int) "still one cookie" 1 (List.length cookies);

     

       2506
       2506
       +
       

     

       2507
       2507
       +
         let cookie = List.hd cookies in

     

       2508
       2508
       +
         Alcotest.(check string) "value was updated" "v2" (Cookeio.value cookie);

     

       2509
       2509
       +
       

     

       2510
       2510
       +
         (* Creation time should be preserved *)

     

       2511
       2511
       +
         let creation_float =

     

       2512
       2512
       +
           Ptime.to_float_s (Cookeio.creation_time cookie)

     

       2513
       2513
       +
         in

     

       2514
       2514
       +
         Alcotest.(check (float 0.001))

     

       2515
       2515
       +
           "creation_time preserved in add_original"

     

       2516
       2516
       +
           100.0 creation_float

     

       2517
       2517
       +
       

     

       2518
       2518
       +
       let test_creation_time_new_cookie () =

     

       2519
       2519
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2520
       2520
       +
         let clock = Eio_mock.Clock.make () in

     

       2521
       2521
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2522
       2522
       +
       

     

       2523
       2523
       +
         let jar = create () in

     

       2524
       2524
       +
       

     

       2525
       2525
       +
         (* Add a new cookie (no existing cookie to preserve from) *)

     

       2526
       2526
       +
         let cookie =

     

       2527
       2527
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"new" ~value:"v1"

     

       2528
       2528
       +
             ~secure:false ~http_only:false

     

       2529
       2529
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2530
       2530
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2531
       2531
       +
         in

     

       2532
       2532
       +
         add_cookie jar cookie;

     

       2533
       2533
       +
       

     

       2534
       2534
       +
         let cookies =

     

       2535
       2535
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       2536
       2536
       +
         in

     

       2537
       2537
       +
         let cookie = List.hd cookies in

     

       2538
       2538
       +
       

     

       2539
       2539
       +
         (* New cookie should keep its own creation time *)

     

       2540
       2540
       +
         let creation_float =

     

       2541
       2541
       +
           Ptime.to_float_s (Cookeio.creation_time cookie)

     

       2542
       2542
       +
         in

     

       2543
       2543
       +
         Alcotest.(check (float 0.001))

     

       2544
       2544
       +
           "new cookie keeps its creation_time"

     

       2545
       2545
       +
           1000.0 creation_float

     

       2546
       2546
       +
       

     

       2547
       2547
       +
       (* ============================================================================ *)

     

       2548
       2548
       +
       (* IP Address Domain Matching Tests (RFC 6265 Section 5.1.3) *)

     

       2549
       2549
       +
       (* ============================================================================ *)

     

       2550
       2550
       +
       

     

       2551
       2551
       +
       let test_ipv4_exact_match () =

     

       2552
       2552
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2553
       2553
       +
         let clock = Eio_mock.Clock.make () in

     

       2554
       2554
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2555
       2555
       +
       

     

       2556
       2556
       +
         let jar = create () in

     

       2557
       2557
       +
         let cookie =

     

       2558
       2558
       +
           Cookeio.make ~domain:"192.168.1.1" ~path:"/" ~name:"test" ~value:"val"

     

       2559
       2559
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2560
       2560
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2561
       2561
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2562
       2562
       +
         in

     

       2563
       2563
       +
         add_cookie jar cookie;

     

       2564
       2564
       +
       

     

       2565
       2565
       +
         (* IPv4 cookie should match exact IP *)

     

       2566
       2566
       +
         let cookies =

     

       2567
       2567
       +
           get_cookies jar ~clock ~domain:"192.168.1.1" ~path:"/" ~is_secure:false

     

       2568
       2568
       +
         in

     

       2569
       2569
       +
         Alcotest.(check int) "IPv4 exact match" 1 (List.length cookies)

     

       2570
       2570
       +
       

     

       2571
       2571
       +
       let test_ipv4_no_suffix_match () =

     

       2572
       2572
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2573
       2573
       +
         let clock = Eio_mock.Clock.make () in

     

       2574
       2574
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2575
       2575
       +
       

     

       2576
       2576
       +
         let jar = create () in

     

       2577
       2577
       +
         (* Cookie for 168.1.1 - this should NOT match requests to 192.168.1.1

     

       2578
       2578
       +
            even though "192.168.1.1" ends with ".168.1.1" *)

     

       2579
       2579
       +
         let cookie =

     

       2580
       2580
       +
           Cookeio.make ~domain:"168.1.1" ~path:"/" ~name:"test" ~value:"val"

     

       2581
       2581
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2582
       2582
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2583
       2583
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2584
       2584
       +
         in

     

       2585
       2585
       +
         add_cookie jar cookie;

     

       2586
       2586
       +
       

     

       2587
       2587
       +
         (* Should NOT match - IP addresses don't do suffix matching *)

     

       2588
       2588
       +
         let cookies =

     

       2589
       2589
       +
           get_cookies jar ~clock ~domain:"192.168.1.1" ~path:"/" ~is_secure:false

     

       2590
       2590
       +
         in

     

       2591
       2591
       +
         Alcotest.(check int) "IPv4 no suffix match" 0 (List.length cookies)

     

       2592
       2592
       +
       

     

       2593
       2593
       +
       let test_ipv4_different_ip () =

     

       2594
       2594
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2595
       2595
       +
         let clock = Eio_mock.Clock.make () in

     

       2596
       2596
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2597
       2597
       +
       

     

       2598
       2598
       +
         let jar = create () in

     

       2599
       2599
       +
         let cookie =

     

       2600
       2600
       +
           Cookeio.make ~domain:"192.168.1.1" ~path:"/" ~name:"test" ~value:"val"

     

       2601
       2601
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2602
       2602
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2603
       2603
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2604
       2604
       +
         in

     

       2605
       2605
       +
         add_cookie jar cookie;

     

       2606
       2606
       +
       

     

       2607
       2607
       +
         (* Different IP should not match *)

     

       2608
       2608
       +
         let cookies =

     

       2609
       2609
       +
           get_cookies jar ~clock ~domain:"192.168.1.2" ~path:"/" ~is_secure:false

     

       2610
       2610
       +
         in

     

       2611
       2611
       +
         Alcotest.(check int) "different IPv4 no match" 0 (List.length cookies)

     

       2612
       2612
       +
       

     

       2613
       2613
       +
       let test_ipv6_exact_match () =

     

       2614
       2614
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2615
       2615
       +
         let clock = Eio_mock.Clock.make () in

     

       2616
       2616
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2617
       2617
       +
       

     

       2618
       2618
       +
         let jar = create () in

     

       2619
       2619
       +
         let cookie =

     

       2620
       2620
       +
           Cookeio.make ~domain:"::1" ~path:"/" ~name:"test" ~value:"val"

     

       2621
       2621
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2622
       2622
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2623
       2623
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2624
       2624
       +
         in

     

       2625
       2625
       +
         add_cookie jar cookie;

     

       2626
       2626
       +
       

     

       2627
       2627
       +
         (* IPv6 loopback should match exactly *)

     

       2628
       2628
       +
         let cookies =

     

       2629
       2629
       +
           get_cookies jar ~clock ~domain:"::1" ~path:"/" ~is_secure:false

     

       2630
       2630
       +
         in

     

       2631
       2631
       +
         Alcotest.(check int) "IPv6 exact match" 1 (List.length cookies)

     

       2632
       2632
       +
       

     

       2633
       2633
       +
       let test_ipv6_full_format () =

     

       2634
       2634
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2635
       2635
       +
         let clock = Eio_mock.Clock.make () in

     

       2636
       2636
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2637
       2637
       +
       

     

       2638
       2638
       +
         let jar = create () in

     

       2639
       2639
       +
         let cookie =

     

       2640
       2640
       +
           Cookeio.make ~domain:"2001:db8::1" ~path:"/" ~name:"test" ~value:"val"

     

       2641
       2641
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2642
       2642
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2643
       2643
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2644
       2644
       +
         in

     

       2645
       2645
       +
         add_cookie jar cookie;

     

       2646
       2646
       +
       

     

       2647
       2647
       +
         (* IPv6 should match exactly *)

     

       2648
       2648
       +
         let cookies =

     

       2649
       2649
       +
           get_cookies jar ~clock ~domain:"2001:db8::1" ~path:"/" ~is_secure:false

     

       2650
       2650
       +
         in

     

       2651
       2651
       +
         Alcotest.(check int) "IPv6 full format match" 1 (List.length cookies);

     

       2652
       2652
       +
       

     

       2653
       2653
       +
         (* Different IPv6 should not match *)

     

       2654
       2654
       +
         let cookies2 =

     

       2655
       2655
       +
           get_cookies jar ~clock ~domain:"2001:db8::2" ~path:"/" ~is_secure:false

     

       2656
       2656
       +
         in

     

       2657
       2657
       +
         Alcotest.(check int) "different IPv6 no match" 0 (List.length cookies2)

     

       2658
       2658
       +
       

     

       2659
       2659
       +
       let test_ip_vs_hostname () =

     

       2660
       2660
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2661
       2661
       +
         let clock = Eio_mock.Clock.make () in

     

       2662
       2662
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2663
       2663
       +
       

     

       2664
       2664
       +
         let jar = create () in

     

       2665
       2665
       +
       

     

       2666
       2666
       +
         (* Add a hostname cookie with host_only=false (domain cookie) *)

     

       2667
       2667
       +
         let hostname_cookie =

     

       2668
       2668
       +
           Cookeio.make ~domain:"example.com" ~path:"/" ~name:"hostname" ~value:"h1"

     

       2669
       2669
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2670
       2670
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2671
       2671
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2672
       2672
       +
         in

     

       2673
       2673
       +
         add_cookie jar hostname_cookie;

     

       2674
       2674
       +
       

     

       2675
       2675
       +
         (* Add an IP cookie with host_only=false *)

     

       2676
       2676
       +
         let ip_cookie =

     

       2677
       2677
       +
           Cookeio.make ~domain:"192.168.1.1" ~path:"/" ~name:"ip" ~value:"i1"

     

       2678
       2678
       +
             ~secure:false ~http_only:false ~host_only:false

     

       2679
       2679
       +
             ~creation_time:(Ptime.of_float_s 1000.0 |> Option.get)

     

       2680
       2680
       +
             ~last_access:(Ptime.of_float_s 1000.0 |> Option.get) ()

     

       2681
       2681
       +
         in

     

       2682
       2682
       +
         add_cookie jar ip_cookie;

     

       2683
       2683
       +
       

     

       2684
       2684
       +
         (* Hostname request should match hostname cookie and subdomains *)

     

       2685
       2685
       +
         let cookies1 =

     

       2686
       2686
       +
           get_cookies jar ~clock ~domain:"example.com" ~path:"/" ~is_secure:false

     

       2687
       2687
       +
         in

     

       2688
       2688
       +
         Alcotest.(check int) "hostname matches hostname cookie" 1 (List.length cookies1);

     

       2689
       2689
       +
       

     

       2690
       2690
       +
         let cookies2 =

     

       2691
       2691
       +
           get_cookies jar ~clock ~domain:"sub.example.com" ~path:"/" ~is_secure:false

     

       2692
       2692
       +
         in

     

       2693
       2693
       +
         Alcotest.(check int) "subdomain matches hostname cookie" 1 (List.length cookies2);

     

       2694
       2694
       +
       

     

       2695
       2695
       +
         (* IP request should only match IP cookie exactly *)

     

       2696
       2696
       +
         let cookies3 =

     

       2697
       2697
       +
           get_cookies jar ~clock ~domain:"192.168.1.1" ~path:"/" ~is_secure:false

     

       2698
       2698
       +
         in

     

       2699
       2699
       +
         Alcotest.(check int) "IP matches IP cookie" 1 (List.length cookies3);

     

       2700
       2700
       +
         Alcotest.(check string) "IP cookie is returned" "ip" (Cookeio.name (List.hd cookies3))

     

       2701
       2701
       +
       

     

       2702
       2702
       +
       (* ============================================================================ *)

     

       2703
       2703
       +
       (* RFC 6265 Validation Tests *)

     

       2704
       2704
       +
       (* ============================================================================ *)

     

       2705
       2705
       +
       

     

       2706
       2706
       +
       let test_validate_cookie_name_valid () =

     

       2707
       2707
       +
         (* Valid token characters per RFC 2616 *)

     

       2708
       2708
       +
         let valid_names = ["session"; "SID"; "my-cookie"; "COOKIE_123"; "abc.def"] in

     

       2709
       2709
       +
         List.iter (fun name ->

     

       2710
       2710
       +
           match Cookeio.Validate.cookie_name name with

     

       2711
       2711
       +
           | Ok _ -> ()

     

       2712
       2712
       +
           | Error msg ->

     

       2713
       2713
       +
               Alcotest.fail (Printf.sprintf "Name %S should be valid: %s" name msg))

     

       2714
       2714
       +
           valid_names

     

       2715
       2715
       +
       

     

       2716
       2716
       +
       let test_validate_cookie_name_invalid () =

     

       2717
       2717
       +
         (* Invalid: control chars, separators, spaces *)

     

       2718
       2718
       +
         let invalid_names =

     

       2719
       2719
       +
           [

     

       2720
       2720
       +
             ("", "empty");

     

       2721
       2721
       +
             ("my cookie", "space");

     

       2722
       2722
       +
             ("cookie=value", "equals");

     

       2723
       2723
       +
             ("my;cookie", "semicolon");

     

       2724
       2724
       +
             ("name\t", "tab");

     

       2725
       2725
       +
             ("(cookie)", "parens");

     

       2726
       2726
       +
             ("name,val", "comma");

     

       2727
       2727
       +
           ]

     

       2728
       2728
       +
         in

     

       2729
       2729
       +
         List.iter (fun (name, reason) ->

     

       2730
       2730
       +
           match Cookeio.Validate.cookie_name name with

     

       2731
       2731
       +
           | Error _ -> ()  (* Expected *)

     

       2732
       2732
       +
           | Ok _ ->

     

       2733
       2733
       +
               Alcotest.fail

     

       2734
       2734
       +
                 (Printf.sprintf "Name %S (%s) should be invalid" name reason))

     

       2735
       2735
       +
           invalid_names

     

       2736
       2736
       +
       

     

       2737
       2737
       +
       let test_validate_cookie_value_valid () =

     

       2738
       2738
       +
         (* Valid cookie-octets or quoted values *)

     

       2739
       2739
       +
         let valid_values = ["abc123"; "value!#$%&'()*+-./"; "\"quoted\""; ""] in

     

       2740
       2740
       +
         List.iter (fun value ->

     

       2741
       2741
       +
           match Cookeio.Validate.cookie_value value with

     

       2742
       2742
       +
           | Ok _ -> ()

     

       2743
       2743
       +
           | Error msg ->

     

       2744
       2744
       +
               Alcotest.fail (Printf.sprintf "Value %S should be valid: %s" value msg))

     

       2745
       2745
       +
           valid_values

     

       2746
       2746
       +
       

     

       2747
       2747
       +
       let test_validate_cookie_value_invalid () =

     

       2748
       2748
       +
         (* Invalid: space, comma, semicolon, backslash, unmatched quotes *)

     

       2749
       2749
       +
         let invalid_values =

     

       2750
       2750
       +
           [

     

       2751
       2751
       +
             ("with space", "space");

     

       2752
       2752
       +
             ("with,comma", "comma");

     

       2753
       2753
       +
             ("with;semi", "semicolon");

     

       2754
       2754
       +
             ("back\\slash", "backslash");

     

       2755
       2755
       +
             ("\"unmatched", "unmatched opening quote");

     

       2756
       2756
       +
             ("unmatched\"", "unmatched closing quote");

     

       2757
       2757
       +
           ]

     

       2758
       2758
       +
         in

     

       2759
       2759
       +
         List.iter (fun (value, reason) ->

     

       2760
       2760
       +
           match Cookeio.Validate.cookie_value value with

     

       2761
       2761
       +
           | Error _ -> ()  (* Expected *)

     

       2762
       2762
       +
           | Ok _ ->

     

       2763
       2763
       +
               Alcotest.fail

     

       2764
       2764
       +
                 (Printf.sprintf "Value %S (%s) should be invalid" value reason))

     

       2765
       2765
       +
           invalid_values

     

       2766
       2766
       +
       

     

       2767
       2767
       +
       let test_validate_domain_valid () =

     

       2768
       2768
       +
         (* Valid domain names and IP addresses *)

     

       2769
       2769
       +
         let valid_domains =

     

       2770
       2770
       +
           ["example.com"; "sub.example.com"; ".example.com"; "192.168.1.1"; "::1"]

     

       2771
       2771
       +
         in

     

       2772
       2772
       +
         List.iter (fun domain ->

     

       2773
       2773
       +
           match Cookeio.Validate.domain_value domain with

     

       2774
       2774
       +
           | Ok _ -> ()

     

       2775
       2775
       +
           | Error msg ->

     

       2776
       2776
       +
               Alcotest.fail (Printf.sprintf "Domain %S should be valid: %s" domain msg))

     

       2777
       2777
       +
           valid_domains

     

       2778
       2778
       +
       

     

       2779
       2779
       +
       let test_validate_domain_invalid () =

     

       2780
       2780
       +
         (* Invalid domain names - only test cases that domain-name library rejects.

     

       2781
       2781
       +
            Note: domain-name library has specific rules that may differ from what

     

       2782
       2782
       +
            we might expect from the RFC. *)

     

       2783
       2783
       +
         let invalid_domains =

     

       2784
       2784
       +
           [

     

       2785
       2785
       +
             ("", "empty");

     

       2786
       2786
       +
             (* Note: "-invalid.com" and "invalid-.com" are valid per domain-name library *)

     

       2787
       2787
       +
           ]

     

       2788
       2788
       +
         in

     

       2789
       2789
       +
         List.iter (fun (domain, reason) ->

     

       2790
       2790
       +
           match Cookeio.Validate.domain_value domain with

     

       2791
       2791
       +
           | Error _ -> ()  (* Expected *)

     

       2792
       2792
       +
           | Ok _ ->

     

       2793
       2793
       +
               Alcotest.fail

     

       2794
       2794
       +
                 (Printf.sprintf "Domain %S (%s) should be invalid" domain reason))

     

       2795
       2795
       +
           invalid_domains

     

       2796
       2796
       +
       

     

       2797
       2797
       +
       let test_validate_path_valid () =

     

       2798
       2798
       +
         let valid_paths = ["/"; "/path"; "/path/to/resource"; "/path?query"] in

     

       2799
       2799
       +
         List.iter (fun path ->

     

       2800
       2800
       +
           match Cookeio.Validate.path_value path with

     

       2801
       2801
       +
           | Ok _ -> ()

     

       2802
       2802
       +
           | Error msg ->

     

       2803
       2803
       +
               Alcotest.fail (Printf.sprintf "Path %S should be valid: %s" path msg))

     

       2804
       2804
       +
           valid_paths

     

       2805
       2805
       +
       

     

       2806
       2806
       +
       let test_validate_path_invalid () =

     

       2807
       2807
       +
         let invalid_paths =

     

       2808
       2808
       +
           [

     

       2809
       2809
       +
             ("/path;bad", "semicolon");

     

       2810
       2810
       +
             ("/path\x00bad", "control char");

     

       2811
       2811
       +
           ]

     

       2812
       2812
       +
         in

     

       2813
       2813
       +
         List.iter (fun (path, reason) ->

     

       2814
       2814
       +
           match Cookeio.Validate.path_value path with

     

       2815
       2815
       +
           | Error _ -> ()  (* Expected *)

     

       2816
       2816
       +
           | Ok _ ->

     

       2817
       2817
       +
               Alcotest.fail

     

       2818
       2818
       +
                 (Printf.sprintf "Path %S (%s) should be invalid" path reason))

     

       2819
       2819
       +
           invalid_paths

     

       2820
       2820
       +
       

     

       2821
       2821
       +
       let test_duplicate_cookie_detection () =

     

       2822
       2822
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2823
       2823
       +
         let clock = Eio_mock.Clock.make () in

     

       2824
       2824
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2825
       2825
       +
       

     

       2826
       2826
       +
         (* Duplicate cookie names should be rejected *)

     

       2827
       2827
       +
         let result =

     

       2828
       2828
       +
           of_cookie_header

     

       2829
       2829
       +
             ~now:(fun () ->

     

       2830
       2830
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       2831
       2831
       +
               |> Option.value ~default:Ptime.epoch)

     

       2832
       2832
       +
             ~domain:"example.com" ~path:"/" "session=abc; theme=dark; session=xyz"

     

       2833
       2833
       +
         in

     

       2834
       2834
       +
         match result with

     

       2835
       2835
       +
         | Error msg ->

     

       2836
       2836
       +
             (* Should mention duplicate *)

     

       2837
       2837
       +
             let contains_dup = String.lowercase_ascii msg |> fun s ->

     

       2838
       2838
       +
               try let _ = Str.search_forward (Str.regexp_string "duplicate") s 0 in true

     

       2839
       2839
       +
               with Not_found -> false

     

       2840
       2840
       +
             in

     

       2841
       2841
       +
             Alcotest.(check bool) "error mentions duplicate" true contains_dup

     

       2842
       2842
       +
         | Ok _ -> Alcotest.fail "Should reject duplicate cookie names"

     

       2843
       2843
       +
       

     

       2844
       2844
       +
       let test_validation_error_messages () =

     

       2845
       2845
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2846
       2846
       +
         let clock = Eio_mock.Clock.make () in

     

       2847
       2847
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2848
       2848
       +
       

     

       2849
       2849
       +
         (* Test that error messages are descriptive *)

     

       2850
       2850
       +
         let test_cases =

     

       2851
       2851
       +
           [

     

       2852
       2852
       +
             ("=noname", "Cookie name is empty");

     

       2853
       2853
       +
             ("bad cookie=value", "invalid characters");

     

       2854
       2854
       +
             ("name=val ue", "invalid characters");

     

       2855
       2855
       +
           ]

     

       2856
       2856
       +
         in

     

       2857
       2857
       +
         List.iter (fun (header, expected_substring) ->

     

       2858
       2858
       +
           match

     

       2859
       2859
       +
             of_set_cookie_header

     

       2860
       2860
       +
               ~now:(fun () ->

     

       2861
       2861
       +
                 Ptime.of_float_s (Eio.Time.now clock)

     

       2862
       2862
       +
                 |> Option.value ~default:Ptime.epoch)

     

       2863
       2863
       +
               ~domain:"example.com" ~path:"/" header

     

       2864
       2864
       +
           with

     

       2865
       2865
       +
           | Error msg ->

     

       2866
       2866
       +
               let has_substring =

     

       2867
       2867
       +
                 try

     

       2868
       2868
       +
                   let _ = Str.search_forward

     

       2869
       2869
       +
                     (Str.regexp_string expected_substring) msg 0 in

     

       2870
       2870
       +
                   true

     

       2871
       2871
       +
                 with Not_found -> false

     

       2872
       2872
       +
               in

     

       2873
       2873
       +
               Alcotest.(check bool)

     

       2874
       2874
       +
                 (Printf.sprintf "error for %S mentions %S" header expected_substring)

     

       2875
       2875
       +
                 true has_substring

     

       2876
       2876
       +
           | Ok _ ->

     

       2877
       2877
       +
               Alcotest.fail (Printf.sprintf "Should reject %S" header))

     

       2878
       2878
       +
           test_cases

     

       2879
       2879
       +
       

     

       2880
       2880
       +
       (* ============================================================================ *)

     

       2881
       2881
       +
       (* Public Suffix Validation Tests (RFC 6265 Section 5.3, Step 5) *)

     

       2882
       2882
       +
       (* ============================================================================ *)

     

       2883
       2883
       +
       

     

       2884
       2884
       +
       let test_public_suffix_rejection () =

     

       2885
       2885
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2886
       2886
       +
         let clock = Eio_mock.Clock.make () in

     

       2887
       2887
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2888
       2888
       +
       

     

       2889
       2889
       +
         (* Setting a cookie for a public suffix (TLD) should be rejected *)

     

       2890
       2890
       +
         let test_cases =

     

       2891
       2891
       +
           [

     

       2892
       2892
       +
             (* (request_domain, cookie_domain, description) *)

     

       2893
       2893
       +
             ("www.example.com", "com", "TLD .com");

     

       2894
       2894
       +
             ("www.example.co.uk", "co.uk", "ccTLD .co.uk");

     

       2895
       2895
       +
             ("foo.bar.github.io", "github.io", "private domain github.io");

     

       2896
       2896
       +
           ]

     

       2897
       2897
       +
         in

     

       2898
       2898
       +
       

     

       2899
       2899
       +
         List.iter

     

       2900
       2900
       +
           (fun (request_domain, cookie_domain, description) ->

     

       2901
       2901
       +
             let header = Printf.sprintf "session=abc; Domain=.%s" cookie_domain in

     

       2902
       2902
       +
             let result =

     

       2903
       2903
       +
               of_set_cookie_header

     

       2904
       2904
       +
                 ~now:(fun () ->

     

       2905
       2905
       +
                   Ptime.of_float_s (Eio.Time.now clock)

     

       2906
       2906
       +
                   |> Option.value ~default:Ptime.epoch)

     

       2907
       2907
       +
                 ~domain:request_domain ~path:"/" header

     

       2908
       2908
       +
             in

     

       2909
       2909
       +
             match result with

     

       2910
       2910
       +
             | Error msg ->

     

       2911
       2911
       +
                 (* Should mention public suffix *)

     

       2912
       2912
       +
                 let has_psl =

     

       2913
       2913
       +
                   String.lowercase_ascii msg |> fun s ->

     

       2914
       2914
       +
                   try

     

       2915
       2915
       +
                     let _ = Str.search_forward (Str.regexp_string "public suffix") s 0 in

     

       2916
       2916
       +
                     true

     

       2917
       2917
       +
                   with Not_found -> false

     

       2918
       2918
       +
                 in

     

       2919
       2919
       +
                 Alcotest.(check bool)

     

       2920
       2920
       +
                   (Printf.sprintf "%s: error mentions public suffix" description)

     

       2921
       2921
       +
                   true has_psl

     

       2922
       2922
       +
             | Ok _ ->

     

       2923
       2923
       +
                 Alcotest.fail

     

       2924
       2924
       +
                   (Printf.sprintf "Should reject cookie for %s" description))

     

       2925
       2925
       +
           test_cases

     

       2926
       2926
       +
       

     

       2927
       2927
       +
       let test_public_suffix_allowed_when_exact_match () =

     

       2928
       2928
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2929
       2929
       +
         let clock = Eio_mock.Clock.make () in

     

       2930
       2930
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2931
       2931
       +
       

     

       2932
       2932
       +
         (* If request host exactly matches the public suffix domain, allow it.

     

       2933
       2933
       +
            This is rare but possible for private domains like blogspot.com *)

     

       2934
       2934
       +
         let header = "session=abc; Domain=.blogspot.com" in

     

       2935
       2935
       +
         let result =

     

       2936
       2936
       +
           of_set_cookie_header

     

       2937
       2937
       +
             ~now:(fun () ->

     

       2938
       2938
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       2939
       2939
       +
               |> Option.value ~default:Ptime.epoch)

     

       2940
       2940
       +
             ~domain:"blogspot.com" ~path:"/" header

     

       2941
       2941
       +
         in

     

       2942
       2942
       +
         Alcotest.(check bool)

     

       2943
       2943
       +
           "exact match allows public suffix" true

     

       2944
       2944
       +
           (Result.is_ok result)

     

       2945
       2945
       +
       

     

       2946
       2946
       +
       let test_non_public_suffix_allowed () =

     

       2947
       2947
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2948
       2948
       +
         let clock = Eio_mock.Clock.make () in

     

       2949
       2949
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2950
       2950
       +
       

     

       2951
       2951
       +
         (* Normal domain (not a public suffix) should be allowed *)

     

       2952
       2952
       +
         let test_cases =

     

       2953
       2953
       +
           [

     

       2954
       2954
       +
             ("www.example.com", "example.com", "registrable domain");

     

       2955
       2955
       +
             ("sub.example.com", "example.com", "parent of subdomain");

     

       2956
       2956
       +
             ("www.example.co.uk", "example.co.uk", "registrable domain under ccTLD");

     

       2957
       2957
       +
           ]

     

       2958
       2958
       +
         in

     

       2959
       2959
       +
       

     

       2960
       2960
       +
         List.iter

     

       2961
       2961
       +
           (fun (request_domain, cookie_domain, description) ->

     

       2962
       2962
       +
             let header = Printf.sprintf "session=abc; Domain=.%s" cookie_domain in

     

       2963
       2963
       +
             let result =

     

       2964
       2964
       +
               of_set_cookie_header

     

       2965
       2965
       +
                 ~now:(fun () ->

     

       2966
       2966
       +
                   Ptime.of_float_s (Eio.Time.now clock)

     

       2967
       2967
       +
                   |> Option.value ~default:Ptime.epoch)

     

       2968
       2968
       +
                 ~domain:request_domain ~path:"/" header

     

       2969
       2969
       +
             in

     

       2970
       2970
       +
             match result with

     

       2971
       2971
       +
             | Ok cookie ->

     

       2972
       2972
       +
                 Alcotest.(check string)

     

       2973
       2973
       +
                   (Printf.sprintf "%s: domain correct" description)

     

       2974
       2974
       +
                   cookie_domain (Cookeio.domain cookie)

     

       2975
       2975
       +
             | Error msg ->

     

       2976
       2976
       +
                 Alcotest.fail

     

       2977
       2977
       +
                   (Printf.sprintf "%s should be allowed: %s" description msg))

     

       2978
       2978
       +
           test_cases

     

       2979
       2979
       +
       

     

       2980
       2980
       +
       let test_public_suffix_no_domain_attribute () =

     

       2981
       2981
       +
         Eio_mock.Backend.run @@ fun () ->

     

       2982
       2982
       +
         let clock = Eio_mock.Clock.make () in

     

       2983
       2983
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       2984
       2984
       +
       

     

       2985
       2985
       +
         (* Cookie without Domain attribute should always be allowed (host-only) *)

     

       2986
       2986
       +
         let header = "session=abc; Secure; HttpOnly" in

     

       2987
       2987
       +
         let result =

     

       2988
       2988
       +
           of_set_cookie_header

     

       2989
       2989
       +
             ~now:(fun () ->

     

       2990
       2990
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       2991
       2991
       +
               |> Option.value ~default:Ptime.epoch)

     

       2992
       2992
       +
             ~domain:"www.example.com" ~path:"/" header

     

       2993
       2993
       +
         in

     

       2994
       2994
       +
         match result with

     

       2995
       2995
       +
         | Ok cookie ->

     

       2996
       2996
       +
             Alcotest.(check bool) "host_only is true" true (Cookeio.host_only cookie);

     

       2997
       2997
       +
             Alcotest.(check string)

     

       2998
       2998
       +
               "domain is request domain" "www.example.com"

     

       2999
       2999
       +
               (Cookeio.domain cookie)

     

       3000
       3000
       +
         | Error msg -> Alcotest.fail ("Should allow host-only cookie: " ^ msg)

     

       3001
       3001
       +
       

     

       3002
       3002
       +
       let test_public_suffix_ip_address_bypass () =

     

       3003
       3003
       +
         Eio_mock.Backend.run @@ fun () ->

     

       3004
       3004
       +
         let clock = Eio_mock.Clock.make () in

     

       3005
       3005
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       3006
       3006
       +
       

     

       3007
       3007
       +
         (* IP addresses should bypass PSL check *)

     

       3008
       3008
       +
         let header = "session=abc; Domain=192.168.1.1" in

     

       3009
       3009
       +
         let result =

     

       3010
       3010
       +
           of_set_cookie_header

     

       3011
       3011
       +
             ~now:(fun () ->

     

       3012
       3012
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       3013
       3013
       +
               |> Option.value ~default:Ptime.epoch)

     

       3014
       3014
       +
             ~domain:"192.168.1.1" ~path:"/" header

     

       3015
       3015
       +
         in

     

       3016
       3016
       +
         Alcotest.(check bool)

     

       3017
       3017
       +
           "IP address bypasses PSL" true

     

       3018
       3018
       +
           (Result.is_ok result)

     

       3019
       3019
       +
       

     

       3020
       3020
       +
       let test_public_suffix_case_insensitive () =

     

       3021
       3021
       +
         Eio_mock.Backend.run @@ fun () ->

     

       3022
       3022
       +
         let clock = Eio_mock.Clock.make () in

     

       3023
       3023
       +
         Eio_mock.Clock.set_time clock 1000.0;

     

       3024
       3024
       +
       

     

       3025
       3025
       +
         (* Public suffix check should be case-insensitive *)

     

       3026
       3026
       +
         let header = "session=abc; Domain=.COM" in

     

       3027
       3027
       +
         let result =

     

       3028
       3028
       +
           of_set_cookie_header

     

       3029
       3029
       +
             ~now:(fun () ->

     

       3030
       3030
       +
               Ptime.of_float_s (Eio.Time.now clock)

     

       3031
       3031
       +
               |> Option.value ~default:Ptime.epoch)

     

       3032
       3032
       +
             ~domain:"www.example.COM" ~path:"/" header

     

       3033
       3033
       +
         in

     

       3034
       3034
       +
         Alcotest.(check bool)

     

       3035
       3035
       +
           "uppercase TLD still rejected" true

     

       3036
       3036
       +
           (Result.is_error result)

     

       236
       3037
        
       

     

       237
       3038
        
       let () =

     

       238
       3039
        
         Eio_main.run @@ fun env ->

     
···

       254
       3055
        
                     test_cookie_matching env);

     

       255
       3056
        
               ] );

     

       256
       3057
        
             ( "basic_operations",

     

       257
       257
       -
               [ test_case "Empty jar operations" `Quick (fun () -> test_empty_jar env) ]

     

       258
       258
       -
             );

     

       3058
       3058
       +
               [

     

       3059
       3059
       +
                 test_case "Empty jar operations" `Quick (fun () -> test_empty_jar env);

     

       3060
       3060
       +
               ] );

     

       3061
       3061
       +
             ( "time_handling",

     

       3062
       3062
       +
               [

     

       3063
       3063
       +
                 test_case "Cookie expiry with mock clock" `Quick

     

       3064
       3064
       +
                   test_cookie_expiry_with_mock_clock;

     

       3065
       3065
       +
                 test_case "get_cookies filters expired cookies" `Quick

     

       3066
       3066
       +
                   test_get_cookies_filters_expired;

     

       3067
       3067
       +
                 test_case "Max-Age parsing with mock clock" `Quick

     

       3068
       3068
       +
                   test_max_age_parsing_with_mock_clock;

     

       3069
       3069
       +
                 test_case "Last access time with mock clock" `Quick

     

       3070
       3070
       +
                   test_last_access_time_with_mock_clock;

     

       3071
       3071
       +
                 test_case "Parse Set-Cookie with Expires" `Quick

     

       3072
       3072
       +
                   test_of_set_cookie_header_with_expires;

     

       3073
       3073
       +
                 test_case "SameSite=None validation" `Quick

     

       3074
       3074
       +
                   test_samesite_none_validation;

     

       3075
       3075
       +
               ] );

     

       3076
       3076
       +
             ( "domain_normalization",

     

       3077
       3077
       +
               [

     

       3078
       3078
       +
                 test_case "Domain normalization" `Quick test_domain_normalization;

     

       3079
       3079
       +
                 test_case "Domain matching with normalized domains" `Quick

     

       3080
       3080
       +
                   test_domain_matching;

     

       3081
       3081
       +
               ] );

     

       3082
       3082
       +
             ( "max_age_tracking",

     

       3083
       3083
       +
               [

     

       3084
       3084
       +
                 test_case "Max-Age stored separately from Expires" `Quick

     

       3085
       3085
       +
                   test_max_age_stored_separately;

     

       3086
       3086
       +
                 test_case "Negative Max-Age becomes 0" `Quick

     

       3087
       3087
       +
                   test_max_age_negative_becomes_zero;

     

       3088
       3088
       +
                 test_case "make_set_cookie_header includes Max-Age" `Quick

     

       3089
       3089
       +
                   test_make_set_cookie_header_includes_max_age;

     

       3090
       3090
       +
                 test_case "Max-Age round-trip parsing" `Quick test_max_age_round_trip;

     

       3091
       3091
       +
               ] );

     

       3092
       3092
       +
             ( "delta_tracking",

     

       3093
       3093
       +
               [

     

       3094
       3094
       +
                 test_case "add_original doesn't affect delta" `Quick

     

       3095
       3095
       +
                   test_add_original_not_in_delta;

     

       3096
       3096
       +
                 test_case "add_cookie appears in delta" `Quick

     

       3097
       3097
       +
                   test_add_cookie_appears_in_delta;

     

       3098
       3098
       +
                 test_case "remove original creates removal cookie" `Quick

     

       3099
       3099
       +
                   test_remove_original_creates_removal_cookie;

     

       3100
       3100
       +
                 test_case "remove delta cookie just removes it" `Quick

     

       3101
       3101
       +
                   test_remove_delta_cookie_removes_it;

     

       3102
       3102
       +
                 test_case "get_cookies combines original and delta" `Quick

     

       3103
       3103
       +
                   test_get_cookies_combines_original_and_delta;

     

       3104
       3104
       +
                 test_case "get_cookies delta takes precedence" `Quick

     

       3105
       3105
       +
                   test_get_cookies_delta_takes_precedence;

     

       3106
       3106
       +
                 test_case "get_cookies excludes removal cookies" `Quick

     

       3107
       3107
       +
                   test_get_cookies_excludes_removal_cookies;

     

       3108
       3108
       +
                 test_case "delta returns only changed cookies" `Quick

     

       3109
       3109
       +
                   test_delta_returns_only_changed_cookies;

     

       3110
       3110
       +
                 test_case "removal cookie format" `Quick test_removal_cookie_format;

     

       3111
       3111
       +
               ] );

     

       3112
       3112
       +
             ( "http_date_parsing",

     

       3113
       3113
       +
               [

     

       3114
       3114
       +
                 test_case "HTTP date FMT1 (RFC 1123)" `Quick test_http_date_fmt1;

     

       3115
       3115
       +
                 test_case "HTTP date FMT2 (RFC 850)" `Quick test_http_date_fmt2;

     

       3116
       3116
       +
                 test_case "HTTP date FMT3 (asctime)" `Quick test_http_date_fmt3;

     

       3117
       3117
       +
                 test_case "HTTP date FMT4 (variant)" `Quick test_http_date_fmt4;

     

       3118
       3118
       +
                 test_case "Abbreviated year 69-99 becomes 1900+" `Quick

     

       3119
       3119
       +
                   test_abbreviated_year_69_to_99;

     

       3120
       3120
       +
                 test_case "Abbreviated year 0-68 becomes 2000+" `Quick

     

       3121
       3121
       +
                   test_abbreviated_year_0_to_68;

     

       3122
       3122
       +
                 test_case "RFC 3339 backward compatibility" `Quick

     

       3123
       3123
       +
                   test_rfc3339_still_works;

     

       3124
       3124
       +
                 test_case "Invalid date format logs warning" `Quick

     

       3125
       3125
       +
                   test_invalid_date_format_logs_warning;

     

       3126
       3126
       +
                 test_case "Case-insensitive month parsing" `Quick

     

       3127
       3127
       +
                   test_case_insensitive_month_parsing;

     

       3128
       3128
       +
                 test_case "Case-insensitive GMT parsing" `Quick

     

       3129
       3129
       +
                   test_case_insensitive_gmt_parsing;

     

       3130
       3130
       +
               ] );

     

       3131
       3131
       +
             ( "partitioned",

     

       3132
       3132
       +
               [

     

       3133
       3133
       +
                 test_case "parse partitioned cookie" `Quick (fun () ->

     

       3134
       3134
       +
                     test_partitioned_parsing env);

     

       3135
       3135
       +
                 test_case "serialize partitioned cookie" `Quick (fun () ->

     

       3136
       3136
       +
                     test_partitioned_serialization env);

     

       3137
       3137
       +
                 test_case "partitioned requires secure" `Quick (fun () ->

     

       3138
       3138
       +
                     test_partitioned_requires_secure env);

     

       3139
       3139
       +
               ] );

     

       3140
       3140
       +
             ( "expiration",

     

       3141
       3141
       +
               [

     

       3142
       3142
       +
                 test_case "expiration variants" `Quick (fun () ->

     

       3143
       3143
       +
                     test_expiration_variants env);

     

       3144
       3144
       +
                 test_case "parse session expiration" `Quick (fun () ->

     

       3145
       3145
       +
                     test_parse_session_expiration env);

     

       3146
       3146
       +
                 test_case "serialize expiration variants" `Quick (fun () ->

     

       3147
       3147
       +
                     test_serialize_expiration_variants env);

     

       3148
       3148
       +
               ] );

     

       3149
       3149
       +
             ( "value_trimming",

     

       3150
       3150
       +
               [

     

       3151
       3151
       +
                 test_case "quoted values" `Quick (fun () ->

     

       3152
       3152
       +
                     test_quoted_cookie_values env);

     

       3153
       3153
       +
                 test_case "trimmed not used for equality" `Quick (fun () ->

     

       3154
       3154
       +
                     test_trimmed_value_not_used_for_equality env);

     

       3155
       3155
       +
               ] );

     

       3156
       3156
       +
             ( "cookie_header",

     

       3157
       3157
       +
               [

     

       3158
       3158
       +
                 test_case "parse basic" `Quick (fun () ->

     

       3159
       3159
       +
                     test_cookie_header_parsing_basic env);

     

       3160
       3160
       +
                 test_case "default values" `Quick (fun () ->

     

       3161
       3161
       +
                     test_cookie_header_defaults env);

     

       3162
       3162
       +
                 test_case "edge cases" `Quick (fun () ->

     

       3163
       3163
       +
                     test_cookie_header_edge_cases env);

     

       3164
       3164
       +
                 test_case "multiple with errors" `Quick (fun () ->

     

       3165
       3165
       +
                     test_cookie_header_with_errors env);

     

       3166
       3166
       +
               ] );

     

       3167
       3167
       +
             ( "max_age_expires_interaction",

     

       3168
       3168
       +
               [

     

       3169
       3169
       +
                 test_case "both present" `Quick (fun () ->

     

       3170
       3170
       +
                     test_max_age_and_expires_both_present env);

     

       3171
       3171
       +
                 test_case "parse both" `Quick (fun () ->

     

       3172
       3172
       +
                     test_parse_max_age_and_expires env);

     

       3173
       3173
       +
               ] );

     

       3174
       3174
       +
             ( "host_only_flag",

     

       3175
       3175
       +
               [

     

       3176
       3176
       +
                 test_case "host_only without Domain attribute" `Quick

     

       3177
       3177
       +
                   test_host_only_without_domain_attribute;

     

       3178
       3178
       +
                 test_case "host_only with Domain attribute" `Quick

     

       3179
       3179
       +
                   test_host_only_with_domain_attribute;

     

       3180
       3180
       +
                 test_case "host_only with dotted Domain attribute" `Quick

     

       3181
       3181
       +
                   test_host_only_with_dotted_domain_attribute;

     

       3182
       3182
       +
                 test_case "host_only domain matching" `Quick

     

       3183
       3183
       +
                   test_host_only_domain_matching;

     

       3184
       3184
       +
                 test_case "host_only Cookie header parsing" `Quick

     

       3185
       3185
       +
                   test_host_only_cookie_header_parsing;

     

       3186
       3186
       +
                 test_case "host_only Mozilla format round trip" `Quick

     

       3187
       3187
       +
                   test_host_only_mozilla_format_round_trip;

     

       3188
       3188
       +
               ] );

     

       3189
       3189
       +
             ( "path_matching",

     

       3190
       3190
       +
               [

     

       3191
       3191
       +
                 test_case "identical path" `Quick test_path_matching_identical;

     

       3192
       3192
       +
                 test_case "path with trailing slash" `Quick

     

       3193
       3193
       +
                   test_path_matching_with_trailing_slash;

     

       3194
       3194
       +
                 test_case "prefix with slash separator" `Quick

     

       3195
       3195
       +
                   test_path_matching_prefix_with_slash;

     

       3196
       3196
       +
                 test_case "no false prefix match" `Quick

     

       3197
       3197
       +
                   test_path_matching_no_false_prefix;

     

       3198
       3198
       +
                 test_case "root path matches all" `Quick test_path_matching_root;

     

       3199
       3199
       +
                 test_case "path no match" `Quick test_path_matching_no_match;

     

       3200
       3200
       +
               ] );

     

       3201
       3201
       +
             ( "ip_address_matching",

     

       3202
       3202
       +
               [

     

       3203
       3203
       +
                 test_case "IPv4 exact match" `Quick test_ipv4_exact_match;

     

       3204
       3204
       +
                 test_case "IPv4 no suffix match" `Quick test_ipv4_no_suffix_match;

     

       3205
       3205
       +
                 test_case "IPv4 different IP no match" `Quick test_ipv4_different_ip;

     

       3206
       3206
       +
                 test_case "IPv6 exact match" `Quick test_ipv6_exact_match;

     

       3207
       3207
       +
                 test_case "IPv6 full format" `Quick test_ipv6_full_format;

     

       3208
       3208
       +
                 test_case "IP vs hostname behavior" `Quick test_ip_vs_hostname;

     

       3209
       3209
       +
               ] );

     

       3210
       3210
       +
             ( "rfc6265_validation",

     

       3211
       3211
       +
               [

     

       3212
       3212
       +
                 test_case "valid cookie names" `Quick test_validate_cookie_name_valid;

     

       3213
       3213
       +
                 test_case "invalid cookie names" `Quick test_validate_cookie_name_invalid;

     

       3214
       3214
       +
                 test_case "valid cookie values" `Quick test_validate_cookie_value_valid;

     

       3215
       3215
       +
                 test_case "invalid cookie values" `Quick test_validate_cookie_value_invalid;

     

       3216
       3216
       +
                 test_case "valid domain values" `Quick test_validate_domain_valid;

     

       3217
       3217
       +
                 test_case "invalid domain values" `Quick test_validate_domain_invalid;

     

       3218
       3218
       +
                 test_case "valid path values" `Quick test_validate_path_valid;

     

       3219
       3219
       +
                 test_case "invalid path values" `Quick test_validate_path_invalid;

     

       3220
       3220
       +
                 test_case "duplicate cookie detection" `Quick test_duplicate_cookie_detection;

     

       3221
       3221
       +
                 test_case "validation error messages" `Quick test_validation_error_messages;

     

       3222
       3222
       +
               ] );

     

       3223
       3223
       +
             ( "cookie_ordering",

     

       3224
       3224
       +
               [

     

       3225
       3225
       +
                 test_case "ordering by path length" `Quick

     

       3226
       3226
       +
                   test_cookie_ordering_by_path_length;

     

       3227
       3227
       +
                 test_case "ordering by creation time" `Quick

     

       3228
       3228
       +
                   test_cookie_ordering_by_creation_time;

     

       3229
       3229
       +
                 test_case "ordering combined" `Quick test_cookie_ordering_combined;

     

       3230
       3230
       +
               ] );

     

       3231
       3231
       +
             ( "creation_time_preservation",

     

       3232
       3232
       +
               [

     

       3233
       3233
       +
                 test_case "preserved on update" `Quick

     

       3234
       3234
       +
                   test_creation_time_preserved_on_update;

     

       3235
       3235
       +
                 test_case "preserved in add_original" `Quick

     

       3236
       3236
       +
                   test_creation_time_preserved_add_original;

     

       3237
       3237
       +
                 test_case "new cookie keeps time" `Quick test_creation_time_new_cookie;

     

       3238
       3238
       +
               ] );

     

       3239
       3239
       +
             ( "public_suffix_validation",

     

       3240
       3240
       +
               [

     

       3241
       3241
       +
                 test_case "reject public suffix domains" `Quick

     

       3242
       3242
       +
                   test_public_suffix_rejection;

     

       3243
       3243
       +
                 test_case "allow exact match on public suffix" `Quick

     

       3244
       3244
       +
                   test_public_suffix_allowed_when_exact_match;

     

       3245
       3245
       +
                 test_case "allow non-public-suffix domains" `Quick

     

       3246
       3246
       +
                   test_non_public_suffix_allowed;

     

       3247
       3247
       +
                 test_case "no Domain attribute bypasses PSL" `Quick

     

       3248
       3248
       +
                   test_public_suffix_no_domain_attribute;

     

       3249
       3249
       +
                 test_case "IP address bypasses PSL" `Quick

     

       3250
       3250
       +
                   test_public_suffix_ip_address_bypass;

     

       3251
       3251
       +
                 test_case "case insensitive check" `Quick

     

       3252
       3252
       +
                   test_public_suffix_case_insensitive;

     

       3253
       3253
       +
               ] );

     

       259
       3254
        
           ]

Compare changes