// 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.

syntax = "proto3";
package traffic_annotation;

// chrome_settings_full_runtime.proto is a version of the following proto
// without lite runtime optimization:
// out/Debug/gen/components/policy/proto/chrome_settings.proto
import "chrome_settings_full_runtime.proto";

// Describes a specific kind of network traffic based on a fine-grained
// semantic classification of all network traffic generated by Chrome.
// Used for auditing purposes. Please refer to
// "/docs/network_traffic_annotations.md" for users guide.
message NetworkTrafficAnnotation {
  // This is a globally unique identifier that must stay unchanged while the
  // network request carries the same semantic meaning. If the network request
  // gets a new meaning, this ID needs to be changed.
  // The purpose of this ID is to give humans a chance to reference
  // NetworkTrafficAnnotations externally even when those change a little bit
  // (e.g. adding a new piece of data that is sent along with a network
  // request).
  // IDs of one component should have a shared prefix so that sorting all
  // NetworkTrafficAnnotations by unique_id groups those that belong to the same
  // component together.
  // For example:
  //   "spellchecker_lookup"
  string unique_id = 1;

  // Encapsulates information about the code location that generates this kind
  // of network traffic.
  message TrafficSource {
    // File name where the network request is triggered.
    // This is typically filled by the extractor and does not need to be
    // specified in the source code. For manual whitelisting this needs to be
    // specified.
    string file = 1;

    // Function name where the network request is instantiated.
    // This is typically filled by the extractor and does not need to be
    // specified in the source code. For manual whitelisting this needs to be
    // specified.
    string function = 2;

    // __LINE__ in file, where the AuditPolicy object is instantiated.
    // This is typically filled by the extractor and does not need to be
    // specified in the source code.
    // For whitelisted network requests in third_party/ that cannot be properly
    // annotated in the source code, this attribute is empty.
    int32 line = 3;

    // For whitelisted network requests in third_party/ that cannot be properly
    // annotated in the source code, this distinguishes between the first,
    // second, ... annotated call.
    // For annotations in the source code, this is not used because the line
    // attribute uniquely identifies the network request.
    int32 call_number = 4;
  }

  TrafficSource source = 2;

  // Meta information about the network request.
  message TrafficSemantics {
    // What component triggers the request. The components should be human
    // readable and don’t need to reflect the components/ directory. Avoid
    // abbreviations.
    // Examples: Online Spellcheck, Safe Browsing, WebView.
    string sender = 1;

    // Plaintext description of the network request in language that is
    // understandable by admins (ideally also users). Please avoid acronyms.
    // Please describe the feature and the feature's value proposition as well.
    // Examples:
    // - Google Chrome can provide smarter spell-checking by sending text you
    //   type into the browser to Google's servers, allowing you to use the same
    //   spell-checking technology used by Google products, such as Docs.
    //   If the feature is enabled, Chrome will send the entire contents of text
    //   fields as you type in them to Google along with the browser’s default
    //   language. Google returns a list of suggested spellings, which will be
    //   displayed in the context menu.
    // - A network request that comes from web content (a page the user visits)
    string description = 2;

    // What triggered the network request. Use a textual description. This
    // should be a human readable string.
    // For things that are clearly part of the website (resource load, form
    // submission, fetch by a service worker,...), you *may* just put “website”
    // here.
    string trigger = 3;

    // What nature of data is being sent. This should be a human readable
    // string. Any user data and/or PII should be pointed out.
    // Examples: “log files from /var/...”, “statistics about foobar”, “the
    // signature of a form of a website”, “installed extensions and their
    // version”, “a word on a website the user tapped on”
    string data = 4;

    enum Destination {
      // Do not use this value. It's just a placeholder for default value.
      UNSPECIFIED = 0;
      // A website the user visits or interacts with. The distinction from a
      // google owned service can be difficult when the user navigates to
      // google.com or searches with the omnibar. Therefore follow the following
      // guideline: If the source code has hardcoded that the request goes to
      // Google (e.g. for ZeroSuggest), use GOOGLE_OWNED_SERVICE. If the request
      // can go to other domains and is perceived as a part of a website rather
      // than a native browser feature, use WEBSITE. Use LOCAL if the request is
      // processed locally and does not go to network, otherwise use OTHER. If
      // OTHER is used, please add plain text description in 'destination_other'
      // tag.
      WEBSITE = 1;
      // A Google owned service, like SafeBrowsing, spellchecking, ...
      GOOGLE_OWNED_SERVICE = 2;
      // Does not go to the network and just fetches a resource locally.
      LOCAL = 3;
      // Other endpoints, e.g. a service hosting a PAC script. In case of doubt,
      // use this category. We will audit it in the future to see whether we
      // need more categories.
      OTHER = 1000;
    }
    Destination destination = 5;

    // Human readable description in case the destination points to OTHER.
    string destination_other = 6;
  }

  TrafficSemantics semantics = 3;

  message TrafficPolicy {
    enum CookiesAllowed {
      // Do not use this value. It's just a placeholder for default value.
      UNSPECIFIED = 0;
      // Cookies are never used.
      NO = 1;
      // Cookies/channel IDs/... can be sent or saved (use if at least one is
      // correct).
      YES = 2;
    }
    CookiesAllowed cookies_allowed = 1;

    // If a request sends or stores cookies/channel IDs/... (i.e. if
    // cookies_allowed is true), we want to know which cookie store is being
    // used. The answer to this question can typically be derived from the
    // URLRequestContext that is being used.
    // The three most common cases will be:
    // - If cookies_allowed is false, leave this field unset.
    // - If the profile's default URLRequestContext is being used (e.g. from
    //   Profile::GetRequestContext()), this means that the user's normal
    //   cookies are sent. In this case, put "user" here.
    // - If the system URLRequestContext is being used (for example via
    //   io_thread()->system_url_request_context_getter()), put "system" here.
    // Otherwise, please explain (e.g. SafeBrowsing uses a separate cookie
    // store).
    string cookies_store = 2;

    // Human readable description of how to enable/disable a feature that
    // triggers this network request by a user (e.g. “Disable ‘Use a web service
    // to help resolve spelling errors.’ in settings under Advanced”).
    string setting = 3;

    // Policy configuration(s) that disable or limit this network request.
    // This would be a text serialized protobuf of any enterprise policy.
    // see out/Debug/gen/components/policy/proto/chrome_settings.proto
    repeated enterprise_management.ChromeSettingsProto chrome_policy = 4;

    // Justification for not having a policy that disables this feature.
    string policy_exception_justification = 5;
  }

  TrafficPolicy policy = 4;

  // Human readable extra comments, if required.
  string comments = 5;
};

// NetworkTrafficAnnotations that were extracted from the source code.
message ExtractedNetworkTrafficAnnotation {
  repeated NetworkTrafficAnnotation network_traffic_annotation = 1;
};

// NetworkTrafficAnnotations that had to go into a whitelist file because the
// source code could not be annotated (e.g. because it is in a third-party
// library).
message WhitelistedNetworkTrafficAnnotations {
  repeated NetworkTrafficAnnotation network_traffic_annotation = 1;
};

// All NetworkTrafficAnnotations from a Chromium configuration.
message NetworkTrafficAnnotations {
  ExtractedNetworkTrafficAnnotation extracted_network_traffic_annotations = 1;
  WhitelistedNetworkTrafficAnnotations whitelisted_network_traffic_annotations =
      2;
};