services/network/public/mojom/restricted_cookie_manager.mojom

// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "services/network/public/mojom/cookie_manager.mojom";
import "services/network/public/mojom/site_for_cookies.mojom";
import "mojo/public/mojom/base/time.mojom";
import "url/mojom/url.mojom";
import "url/mojom/origin.mojom";

enum CookieMatchType {
  EQUALS,
  STARTS_WITH,
};

struct CookieManagerGetOptions {
  string name;
  CookieMatchType match_type;
};

// Affects whether http-only cookies are accessible, and the rules used for
// SameSite cookie computations.
enum RestrictedCookieManagerRole {
  // Used for script access to cookies. Will not be able to get to HttpOnly
  // cookies, and will apply SameSite cookies access rules appropriate for
  // script cookie access. OK to give to the renderer.
  SCRIPT,

  // Access to cookies appropriate for network requests --- meant for cases
  // where, for some reason, a fetch needs to be performed by some external
  // library.  Will get HttpOnly cookies, and compute SameSite accessibility
  // appropriate for subresource loading (but NOT for navigations).
  //
  // Should only be used within the browser.
  NETWORK
};

// Capability to access the cookie store on behalf of a single origin.
//
// Instances of this interface are restricted to a single origin, and will
// fail operations on cookies that aren't visible within that origin. Untrusted
// processes, like renderer processes, should only receive
// RestrictedCookieManager instances for the origins that they are allowed to
// represent.
//
// Implementations of this interface must assume all inputs are untrusted, and
// must ensure that a potentially compromised caller process is not able to
// access more than the cookies visible to the RestrictedCookieManager's origin.
//
// TODO(pwnall): Make this a strict subset of CookieManager. At the moment (Q2
// 2018) the interface is diverged from CookieManager to allow its primary user
// (the Web Platform's Async Cookies API) to iterate quickly.
interface RestrictedCookieManager {
  // Returns some of the cookies that would be sent in a request to |url|.
  //
  // |url| is an URL capable of receiving HTTP requests. |site_for_cookies| is
  // the "site for cookies" values defined in RFC 6265bis, and roughly maps to
  // the URL of the top-level frame in Document contexts, and to the script URL
  // in service workers. |top_frame_origin| is the actual origin of the top
  // level frame or the script url for service workers. |site_for_cookies| is
  // used to determine if a cookie is accessed in a third-party context.
  // |top_frame_origin| is used to check for content settings.
  // |options| filters the returned list of cookies. The returned cookies
  // include CookieAccessResult information of the cookie.
  // Any information contained in the CookieInclusionStatus::WarningReasons
  // as part of CookieAccessResult in the included cookies may be passed to an
  // untrusted renderer.
  GetAllForUrl(
      url.mojom.Url url, SiteForCookies site_for_cookies,
      url.mojom.Origin top_frame_origin,
      CookieManagerGetOptions options,
      // TODO(https://crbug.com/1296161): Delete this arg when partitioned cookies
      // Origin Trial is over.
      bool partitioned_cookies_runtime_feature_enabled) => (
      array<CookieWithAccessResult> cookies);

  // Sets a canonical cookie. |status| must be an inclusion status as defined
  // by the C++ net::CookieInclusionStatus::IsInclude() method. It is expected
  // that exclusion reasons have been taken care of on the renderer side.
  SetCanonicalCookie(CanonicalCookie cookie,
                     url.mojom.Url url,
                     SiteForCookies site_for_cookies,
                     url.mojom.Origin top_frame_origin,
                     CookieInclusionStatus status) => (bool success);

  // Subscribes to changes in the cookies transmitted in a request to an URL.
  //
  // The subscription is canceled by closing the pipe.
  AddChangeListener(url.mojom.Url url, SiteForCookies site_for_cookies,
                    url.mojom.Origin top_frame_origin,
                    pending_remote<CookieChangeListener> listener) => ();

  // Sets a cookie.  If setting of this cookie is not permitted either by web
  // platform rules, or user preferences, the attempt will be silently ignored.
  // This does not extend to passing in a |url| that does not match the origin
  // RestrictedCookieManager is bound to --- that will be treated as the
  // renderer violating security rules.
  //
  // The implementation may block, e.g. while cookies are still being loaded, or
  // to serialize with other operations.
  [Sync]
  SetCookieFromString(url.mojom.Url url, SiteForCookies site_for_cookies,
                      url.mojom.Origin top_frame_origin,
                      string cookie,
                      // TODO(https://crbug.com/1296161): Delete this arg when
                      // partitioned cookies Origin Trial is over.
                      bool partitioned_cookies_runtime_feature_enabled) => ();

  // Used to get cookies for the given URL. Cookies that are blocked by user
  // preferences will be skipped, down to potentially returning an empty string.
  // The implementation may block, e.g. while cookies are still being loaded, or
  // to serialize with other operations.
  //
  // Passing in |url| that does not match the origin RestrictedCookieManager
  // is bounded to will be treated as the renderer violating security rules.
  [Sync]
  GetCookiesString(url.mojom.Url url,
                   SiteForCookies site_for_cookies,
                   url.mojom.Origin top_frame_origin,
                   // TODO(https://crbug.com/1296161): Delete this arg when
                   // partitioned cookies Origin Trial is over.
                   bool partitioned_cookies_runtime_feature_enabled) => (
                   string cookies);

  // Used to check if cookies are enabled for the given URL in context of a
  // given site.
  //
  // Passing in |url| that does not match the origin RestrictedCookieManager
  // is bounded to will be treated as the renderer violating security rules.
  [Sync]
  CookiesEnabledFor(
      url.mojom.Url url,
      SiteForCookies site_for_cookies,
      url.mojom.Origin top_frame_origin) => (bool cookies_enabled);

  // TODO(https://crbug.com/1296161): Delete this method when the partitioned cookies
  // Origin Trial is over.
  ConvertPartitionedCookiesToUnpartitioned(url.mojom.Url url);
};