dommy 0.14.0 → 0.16.0

data/lib/dommy/cookie_jar.rb

@@ -0,0 +1,408 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Dommy
+  # One browsing session's cookie store (RFC 6265bis, "Cookies: HTTP State
+  # Management Mechanism"): what `document.cookie` and `cookieStore` read and
+  # write, and — through an embedder that sends requests — what a request's
+  # `Cookie` header carries and a response's `Set-Cookie` stores.
+  #
+  # A cookie is keyed by name, domain (host-only or not) and path, and stored
+  # with the RFC's attribute processing: Expires / Max-Age (capped at 400
+  # days; a past one deletes), Domain (which must domain-match the request
+  # host), Path (default-path from the URL), Secure (only from a secure URL:
+  # https, wss, or a loopback host, as browsers treat http://localhost),
+  # HttpOnly (refused from, and hidden from, a "non-HTTP" API such as
+  # `document.cookie`), SameSite, the `__Secure-` / `__Host-` prefixes, and the
+  # limits (name + value at most 4096 octets, an attribute value at most 1024).
+  # A cookie string with a control character is ignored whole.
+  #
+  # `http: false` marks the "non-HTTP" APIs. Thread-safe: an embedder's network
+  # workers may store and read while the page thread does.
+  #
+  # Not modelled: a public suffix list (a single-label Domain is refused unless
+  # it is the host itself), SameSite enforcement on retrieval (every request
+  # counts as same-site), and per-domain cookie count limits.
+  class CookieJar
+    Cookie = Struct.new(
+      :name, :value, :domain, :path, :expires, :secure, :http_only, :host_only,
+      :same_site, :creation, keyword_init: true
+    ) do
+      # `expires` is a Time, or nil for a session cookie.
+      def persistent? = !expires.nil?
+    end
+
+    MAX_NAME_VALUE_OCTETS = 4096
+    MAX_ATTRIBUTE_VALUE_OCTETS = 1024
+    MAX_AGE_CAP_SECONDS = 400 * 24 * 60 * 60
+    # %x00-08 / %x0A-1F / %x7F: every control character but HTAB.
+    CONTROL_CHARACTERS = /[\x00-\x08\x0A-\x1F\x7F]/
+    EARLIEST = Time.at(0).utc
+
+    def initialize(clock: nil)
+      @cookies = []
+      @clock = clock || -> { Time.now }
+      @sequence = 0
+      @mutex = Mutex.new
+    end
+
+    # "Receive a set-cookie-string" from `url`: parse it and store the cookie
+    # it describes (a past expiry deletes its match). `http: false` for a
+    # non-HTTP API. Returns the stored Cookie, or nil when it was ignored.
+    def store(set_cookie_string, url, http: true)
+      parsed = parse(set_cookie_string.to_s)
+      return nil unless parsed
+
+      record = request_record(url)
+      return nil unless record
+
+      @mutex.synchronize { store_parsed(parsed, record, http) }
+    end
+
+    # Store every `Set-Cookie` of a response's headers (a Hash whose value is
+    # a String — several cookies separated by newlines, as Rack joins them —
+    # or an Array; or an Array of [name, value] pairs) received from `url`.
+    def store_response_headers(headers, url)
+      set_cookie_values(headers).each { |value| store(value, url, http: true) }
+      nil
+    end
+
+    # The cookie-string for a request to `url` (`http: false` leaves out
+    # HttpOnly cookies): matching cookies, longer paths first, then oldest.
+    def cookie_string(url, http: true)
+      matching(url, http: http).map { |c| c.name.empty? ? c.value : "#{c.name}=#{c.value}" }.join("; ")
+    end
+
+    # The cookies a request to `url` would carry, in cookie-string order.
+    def matching(url, http: true)
+      record = request_record(url)
+      return [] unless record
+
+      host = record[:host]
+      path = record[:path]
+      secure = record[:secure]
+      found = @mutex.synchronize do
+        evict_expired
+        @cookies.select do |c|
+          domain_matches_cookie?(c, host) && path_match?(c.path, path) &&
+            (!c.secure || secure) && (http || !c.http_only)
+        end
+      end
+      found.sort_by { |c| [-c.path.length, c.creation] }
+    end
+
+    # Every unexpired cookie.
+    def all
+      @mutex.synchronize do
+        evict_expired
+        @cookies.dup
+      end
+    end
+
+    # The value of the first unexpired cookie named `name`, or nil.
+    def get(name)
+      all.find { |c| c.name == name.to_s }&.value
+    end
+
+    # Store a cookie as given, bypassing the request checks (an embedder or a
+    # test setting up state). A nil `domain` makes it host-only for `host`.
+    def set!(name, value, domain: nil, host: nil, path: "/", expires: nil, secure: false, http_only: false,
+             same_site: nil, host_only: nil)
+      dom = (domain || host || "").to_s.sub(/\A\./, "").downcase
+      cookie = Cookie.new(
+        name: name.to_s, value: value.to_s, domain: dom, path: path || "/", expires: expires,
+        secure: secure ? true : false, http_only: http_only ? true : false,
+        host_only: host_only.nil? ? domain.nil? : host_only, same_site: same_site
+      )
+      @mutex.synchronize { insert(cookie) }
+      cookie
+    end
+
+    # Remove the cookie named `name` with this domain and path (any, when
+    # nil).
+    def delete(name, domain: nil, path: nil)
+      @mutex.synchronize do
+        @cookies.reject! do |c|
+          c.name == name.to_s && (domain.nil? || c.domain == domain.to_s.sub(/\A\./, "").downcase) &&
+            (path.nil? || c.path == path)
+        end
+      end
+      nil
+    end
+
+    def clear
+      @mutex.synchronize { @cookies = [] }
+      nil
+    end
+
+    # Every unexpired cookie as a plain Hash, for #import!.
+    def export
+      all.map { |c| c.to_h.except(:creation) }
+    end
+
+    # Restore a cookie from an #export Hash (symbol or string keys), keeping
+    # its host-only flag; an expired one is skipped.
+    def import!(attrs)
+      h = attrs.to_h.transform_keys(&:to_sym)
+      expires = h[:expires]
+      expires = Time.parse(expires) if expires.is_a?(String)
+      cookie = Cookie.new(
+        name: h[:name].to_s, value: h[:value].to_s, domain: h[:domain].to_s.sub(/\A\./, "").downcase,
+        path: h[:path] || "/", expires: expires, secure: h[:secure] ? true : false,
+        http_only: h[:http_only] ? true : false, host_only: h[:host_only] ? true : false,
+        same_site: h[:same_site]
+      )
+      @mutex.synchronize { insert(cookie) unless expired?(cookie) }
+      nil
+    end
+
+    # The jar's current time (a Time), which its expiries are measured
+    # against.
+    def now = @clock.call
+
+    private
+
+    def set_cookie_values(headers)
+      pairs = headers.respond_to?(:each_pair) ? headers.each_pair.to_a : Array(headers)
+      pairs.flat_map do |name, value|
+        next [] unless name.to_s.casecmp?("set-cookie")
+
+        Array(value).flat_map { |v| v.to_s.split("\n") }
+      end
+    end
+
+    # RFC 6265bis §5.6 "The Set-Cookie Header Field": the name, value and
+    # recognized attributes, or nil for a string to ignore.
+    def parse(string)
+      return nil if string.match?(CONTROL_CHARACTERS)
+
+      name_value, _, unparsed = string.partition(";")
+      if name_value.include?("=")
+        name, _, value = name_value.partition("=")
+      else
+        name = ""
+        value = name_value
+      end
+      name = trim(name)
+      value = trim(value)
+      return nil if name.bytesize + value.bytesize > MAX_NAME_VALUE_OCTETS
+
+      attrs = {}
+      unparsed.split(";").each do |av|
+        key, _, val = av.partition("=")
+        key = trim(key).downcase
+        val = trim(val)
+        next if val.bytesize > MAX_ATTRIBUTE_VALUE_OCTETS
+
+        process_attribute(attrs, key, val)
+      end
+      {name: name, value: value, attrs: attrs}
+    end
+
+    def trim(string) = string.to_s.gsub(/\A[ \t]+|[ \t]+\z/, "")
+
+    def process_attribute(attrs, key, val)
+      case key
+      when "expires"
+        time = parse_cookie_date(val)
+        attrs[:expires] = time if time
+      when "max-age"
+        return unless val.match?(/\A-?\d+\z/)
+
+        attrs[:max_age] = val.to_i
+      when "domain"
+        attrs[:domain] = val.sub(/\A\./, "").downcase unless val.empty?
+      when "path"
+        attrs[:path] = val.start_with?("/") ? val : nil
+        attrs[:path_given] = true
+      when "secure"
+        attrs[:secure] = true
+      when "httponly"
+        attrs[:http_only] = true
+      when "samesite"
+        attrs[:same_site] = {"strict" => "Strict", "lax" => "Lax", "none" => "None"}.fetch(val.downcase, "Default")
+      end
+    end
+
+    # RFC 6265bis §5.7 "Storage Model", given the parsed string.
+    def store_parsed(parsed, record, http)
+      name = parsed[:name]
+      value = parsed[:value]
+      attrs = parsed[:attrs]
+      return nil if name.empty? && value.empty?
+      # A cookie with no name must not look like a prefixed one.
+      return nil if name.empty? && value.match?(/\A__(secure|host)-/i)
+
+      expires = expiry_of(attrs)
+      host = record[:host]
+      domain_attr = attrs[:domain].to_s
+      if !domain_attr.empty? && public_suffix?(domain_attr)
+        return nil unless domain_attr == host
+
+        domain_attr = ""
+      end
+      if domain_attr.empty?
+        host_only = true
+        domain = host
+      else
+        return nil unless domain_match?(host, domain_attr)
+
+        host_only = false
+        domain = domain_attr
+      end
+      path = attrs[:path] || default_path(record[:path])
+      secure = attrs[:secure] == true
+      return nil if secure && !record[:secure]
+
+      http_only = attrs[:http_only] == true
+      return nil if http_only && !http
+      # Leave secure cookies alone: an insecure request cannot shadow one.
+      return nil if !secure && !record[:secure] && shadows_secure_cookie?(name, domain, path)
+
+      same_site = attrs[:same_site] || "Default"
+      return nil if same_site == "None" && !secure
+      return nil if name.match?(/\A__secure-/i) && !secure
+      return nil if name.match?(/\A__host-/i) && !(secure && host_only && path == "/")
+
+      cookie = Cookie.new(name: name, value: value, domain: domain, path: path, expires: expires,
+                          secure: secure, http_only: http_only, host_only: host_only, same_site: same_site)
+      old = @cookies.find { |c| same_key?(c, cookie) }
+      return nil if old&.http_only && !http
+
+      if expired?(cookie)
+        @cookies.delete(old) if old
+        return nil
+      end
+      insert(cookie, creation: old&.creation)
+      cookie
+    end
+
+    def same_key?(a, b)
+      a.name == b.name && a.domain == b.domain && a.host_only == b.host_only && a.path == b.path
+    end
+
+    def insert(cookie, creation: nil)
+      @cookies.reject! { |c| same_key?(c, cookie) }
+      cookie.creation = creation || (@sequence += 1)
+      @cookies << cookie
+      cookie
+    end
+
+    # RFC 6265bis "Storage Model" step 16: a secure cookie of the name whose
+    # domain matches either way, and under whose path the new cookie's path
+    # falls (the new path path-matches the stored one).
+    def shadows_secure_cookie?(name, domain, path)
+      @cookies.any? do |c|
+        c.secure && c.name == name &&
+          (domain_match?(domain, c.domain) || domain_match?(c.domain, domain)) && path_match?(c.path, path)
+      end
+    end
+
+    # Max-Age wins over Expires; both are capped at 400 days, and a Max-Age of
+    # zero or less is the earliest representable time (an immediate delete).
+    def expiry_of(attrs)
+      cap = now + MAX_AGE_CAP_SECONDS
+      if attrs.key?(:max_age)
+        seconds = attrs[:max_age]
+        return EARLIEST if seconds <= 0
+
+        return [now + seconds, cap].min
+      end
+      return nil unless attrs[:expires]
+
+      [attrs[:expires], cap].min
+    end
+
+    def expired?(cookie)
+      cookie.expires && cookie.expires <= now
+    end
+
+    def evict_expired
+      @cookies.reject! { |c| expired?(c) }
+    end
+
+    # A single-label domain stands in for a public suffix (no list here).
+    def public_suffix?(domain)
+      !domain.include?(".") && !ip_address?(domain)
+    end
+
+    def ip_address?(host)
+      host.match?(/\A\d+\.\d+\.\d+\.\d+\z/) || host.start_with?("[")
+    end
+
+    # RFC 6265bis "domain-match".
+    def domain_match?(string, domain)
+      return true if string == domain
+      return false if ip_address?(string)
+
+      string.end_with?(".#{domain}")
+    end
+
+    def domain_matches_cookie?(cookie, host)
+      cookie.host_only ? cookie.domain == host : domain_match?(host, cookie.domain)
+    end
+
+    # RFC 6265bis "path-match".
+    def path_match?(cookie_path, request_path)
+      return true if cookie_path == request_path
+      return false unless request_path.start_with?(cookie_path)
+
+      cookie_path.end_with?("/") || request_path[cookie_path.length] == "/"
+    end
+
+    # RFC 6265bis "default-path" of a request path.
+    def default_path(request_path)
+      return "/" if request_path.empty? || !request_path.start_with?("/")
+
+      idx = request_path.rindex("/")
+      idx.zero? ? "/" : request_path[0...idx]
+    end
+
+    # The host, path and whether the URL is secure (a "secure protocol" is the
+    # user agent's call: https, wss, and — as Chrome and Firefox do — a
+    # loopback host), for an http(s)/ws(s) URL; nil for any other.
+    def request_record(url)
+      record = Internal::UrlParser.parse(url.to_s)
+      return nil unless %w[http https ws wss].include?(record.scheme)
+
+      host = record.host.to_s.downcase
+      path = Internal::UrlParser.serialize_path(record)
+      secure = %w[https wss].include?(record.scheme) || Internal::Origin.trustworthy_record?(record)
+      {host: host, path: path.empty? ? "/" : path, secure: secure}
+    rescue Internal::UrlParser::Failure
+      nil
+    end
+
+    MONTHS = %w[jan feb mar apr may jun jul aug sep oct nov dec].freeze
+    DATE_DELIMITER = /[\x09\x20-\x2F\x3B-\x40\x5B-\x60\x7B-\x7E]+/
+
+    # RFC 6265bis §5.1.1 "Dates": the cookie-date parsing algorithm. nil when
+    # the string is not a date.
+    def parse_cookie_date(string)
+      time = day = month = year = nil
+      string.split(DATE_DELIMITER).each do |token|
+        next if token.empty?
+
+        if time.nil? && (m = token.match(/\A(\d{1,2}):(\d{1,2}):(\d{1,2})(?:\D.*)?\z/))
+          time = m.captures.map(&:to_i)
+        elsif day.nil? && (m = token.match(/\A(\d{1,2})(?:\D.*)?\z/))
+          day = m[1].to_i
+        elsif month.nil? && (idx = MONTHS.index(token[0, 3].downcase))
+          month = idx + 1
+        elsif year.nil? && (m = token.match(/\A(\d{2,4})(?:\D.*)?\z/))
+          year = m[1].to_i
+        end
+      end
+      return nil unless time && day && month && year
+
+      year += 1900 if year.between?(70, 99)
+      year += 2000 if year.between?(0, 69)
+      return nil if day < 1 || day > 31 || year < 1601 || time[0] > 23 || time[1] > 59 || time[2] > 59
+
+      Time.utc(year, month, day, *time)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/dommy/cookie_store.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module Dommy
-  # `cookieStore` — the asynchronous Cookie Store API. Reads and
-  # writes go through the existing `Document#cookie_jar`, so values
-  # set via `document.cookie = ...` round-trip via `cookieStore.get`.
+  # `cookieStore` — the asynchronous Cookie Store API, over the same cookie
+  # jar as `document.cookie` (the window's Dommy::CookieJar), for the
+  # document's URL and as a "non-HTTP" API: an HttpOnly cookie is neither
+  # read nor overwritten. A cookie it sets is Secure, Path=/ and
+  # SameSite=Strict unless told otherwise.
   #
-  # Spec: https://wicg.github.io/cookie-store/
+  # Spec: https://cookiestore.spec.whatwg.org/
   class CookieStore
     include EventTarget
 
@@ -13,51 +15,46 @@ module Dommy
       @window = window
     end
 
-    def get(name_or_options)
-      name = name_or_options.is_a?(Hash) ? (name_or_options["name"] || name_or_options[:name]) : name_or_options
-      raw = cookie_jar.cookies[name.to_s]
-      raw ? PromiseValue.resolve(@window, build_record(name.to_s, raw)) : PromiseValue.resolve(@window, nil)
+    def get(name_or_options = nil)
+      name, url = query_of(name_or_options)
+      found = cookies_for(url).find { |c| name.nil? || c.name == name }
+      PromiseValue.resolve(@window, found && build_record(found))
+    rescue Bridge::TypeError => e
+      PromiseValue.reject(@window, e)
     end
 
-    def get_all(name = nil)
-      records = cookie_jar.cookies.map { |k, v| build_record(k, v) }
-      records = records.select { |r| r["name"] == name.to_s } if name
+    def get_all(name_or_options = nil)
+      name, url = query_of(name_or_options)
+      records = cookies_for(url).select { |c| name.nil? || c.name == name }.map { |c| build_record(c) }
       PromiseValue.resolve(@window, records)
+    rescue Bridge::TypeError => e
+      PromiseValue.reject(@window, e)
     end
 
     alias getAll get_all
 
     def set(name_or_options, value = nil)
-      if name_or_options.is_a?(Hash)
-        opts = name_or_options.transform_keys(&:to_s)
-        name = opts["name"]
-        value = opts["value"]
-      else
-        name = name_or_options
-      end
-
-      cookie_jar.set_cookie("#{name}=#{value}")
-      dispatch_event(
-        CookieChangeEvent.new(
-          "change",
-          "changed" => [build_record(name.to_s, value.to_s)],
-          "deleted" => []
-        )
-      )
+      opts = name_or_options.is_a?(Hash) ? name_or_options.transform_keys(&:to_s) : {"name" => name_or_options, "value" => value}
+      cookie = write(opts)
+      event =
+        if cookie
+          {"changed" => [build_record(cookie)], "deleted" => []}
+        else
+          {"changed" => [], "deleted" => [{"name" => opts["name"].to_s, "value" => nil}]}
+        end
+      dispatch_event(CookieChangeEvent.new("change", event))
       PromiseValue.resolve(@window, nil)
+    rescue Bridge::TypeError => e
+      PromiseValue.reject(@window, e)
     end
 
     def delete(name_or_options)
-      name = name_or_options.is_a?(Hash) ? (name_or_options["name"] || name_or_options[:name]) : name_or_options
-      cookie_jar.cookies.delete(name.to_s)
-      dispatch_event(
-        CookieChangeEvent.new(
-          "change",
-          "changed" => [],
-          "deleted" => [build_record(name.to_s, "")]
-        )
-      )
+      opts = name_or_options.is_a?(Hash) ? name_or_options.transform_keys(&:to_s) : {"name" => name_or_options}
+      write(opts.merge("value" => "", "expires" => 0))
+      dispatch_event(CookieChangeEvent.new("change", "changed" => [], "deleted" => [{"name" => opts["name"].to_s, "value" => nil}]))
       PromiseValue.resolve(@window, nil)
+    rescue Bridge::TypeError => e
+      PromiseValue.reject(@window, e)
     end
 
     include Bridge::Methods
@@ -87,22 +84,80 @@ module Dommy
 
     private
 
-    def cookie_jar
-      # `document.cookie_jar` is private; we reach the same backing
-      # store via the public `document.cookie` round-trip. Easier: use
-      # instance_variable_get on the document.
-      @window.document.instance_variable_get(:@cookie_jar)
+    def document_url = @window.document.url
+
+    # The name a query asks for (nil: any) and the URL it is for — the
+    # document's, or one with the same origin.
+    def query_of(arg)
+      return [nil, document_url] if arg.nil?
+      return [arg.to_s, document_url] unless arg.is_a?(Hash)
+
+      opts = arg.transform_keys(&:to_s)
+      url = document_url
+      if opts["url"]
+        parsed = @window.__internal_parse_url__(opts["url"].to_s)
+        raise Bridge::TypeError, "invalid url" unless parsed && Internal::Origin.of_url(parsed) == @window.origin
+
+        url = parsed
+      end
+      [opts["name"]&.to_s, url]
+    end
+
+    def cookies_for(url)
+      return [] if @window.document.__internal_cookie_averse__?
+
+      @window.cookie_jar.matching(url, http: false)
+    end
+
+    # "Set a cookie" with the store's defaults, through the jar's storage
+    # model: the cookie stored, or nil for one that expires at once, which
+    # deletes its match. A cookie the jar refuses is a TypeError.
+    def write(opts)
+      name = opts["name"].to_s
+      value = opts["value"].to_s
+      if (name + value).match?(Dommy::CookieJar::CONTROL_CHARACTERS) || name.include?("=") || name.include?(";") || value.include?(";")
+        raise Bridge::TypeError, "invalid cookie name or value"
+      end
+      raise Bridge::TypeError, "a nameless cookie's value cannot contain '='" if name.empty? && value.include?("=")
+
+      parts = ["#{name}=#{value}"]
+      domain = opts["domain"]
+      if domain
+        raise Bridge::TypeError, "domain must not start with '.'" if domain.to_s.start_with?(".")
+
+        parts << "Domain=#{domain}"
+      end
+      path = (opts["path"] || "/").to_s
+      raise Bridge::TypeError, "path must start with '/'" unless path.start_with?("/")
+
+      parts << "Path=#{path}"
+      if opts.key?("expires") && !opts["expires"].nil?
+        parts << "Expires=#{Time.at(opts["expires"].to_f / 1000).utc.httpdate}"
+      end
+      parts << "SameSite=#{(opts["sameSite"] || "strict").to_s.capitalize}"
+      parts << "Secure"
+      cookie = @window.document.__internal_cookie_averse__? ? nil : @window.cookie_jar.store(parts.join("; "), document_url, http: false)
+      return cookie if cookie
+      return nil if expired_at_once?(opts)
+
+      raise Bridge::TypeError, "the cookie was refused"
+    end
+
+    def expired_at_once?(opts)
+      expires = opts["expires"]
+      !expires.nil? && expires.to_f / 1000 <= @window.cookie_jar.now.to_f
     end
 
-    def build_record(name, value)
+    def build_record(cookie)
       {
-        "name" => name.to_s,
-        "value" => value.to_s,
-        "domain" => nil,
-        "path" => "/",
-        "expires" => nil,
-        "secure" => false,
-        "sameSite" => "strict"
+        "name" => cookie.name.to_s,
+        "value" => cookie.value.to_s,
+        "domain" => cookie.host_only ? nil : cookie.domain,
+        "path" => cookie.path || "/",
+        "expires" => cookie.expires ? (cookie.expires.to_f * 1000).round : nil,
+        "secure" => cookie.secure ? true : false,
+        "sameSite" => (cookie.same_site || "Default").to_s.downcase.then { |v| v == "default" ? "lax" : v },
+        "partitioned" => false
       }
     end
   end