// Copyright 2017 The Chromium Authors
// 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;

option optimize_for = LITE_RUNTIME;

import "chrome_settings.proto";
import "chrome_device_policy.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;

    // __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;
      // A proxy that will forward the traffic to a google owned service.
      PROXIED_GOOGLE_OWNED_SERVICE = 4;
      // 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;

    // Data that is meant to be visible internally, example point of contacts,
    // should be placed inside internal field.
    // This field should not be used in any external reports.
    message Internal {
      // Point-of-contact for questions, issues, or bugs related to
      // this network request.
      message Contact {
        oneof contact_type {
          // Email of a team or individual owner
          string email = 1;
          // OWNERS file within the chromium codebase
          string owners = 2;
        }
      }
      repeated Contact contacts = 1;
    }

    Internal internal = 7;

    // Types of user data sent in this network request
    message UserData {
      enum UserDataType {
        // Placeholder, do not use this value.
        UNSPECIFIED = 0;

        // Any token that identifies an account or
        // requests resources on behalf of a particular user.
        // Example: OAuth2 token.
        ACCESS_TOKEN = 1;

        ADDRESS = 2;
        ANDROID_ID = 3;
        AGE = 4;

        // When a request could contain any arbitrary data,
        // to include personal data. Helpful to provide more
        // specifics in the description.
        ARBITRARY_DATA = 5;

        BIRTH_DATE = 6;
        CREDENTIALS = 7;
        CREDIT_CARD_DATA = 8;
        DEVICE_ID = 9;
        EMAIL = 10;
        FILE_DATA = 11;
        GAIA_ID = 12;
        GENDER = 13;
        GOVERNMENT_ID = 14;
        IMAGE = 15;
        // Request contains information about the user's location, separate
        // from what can be inferred from the IP address.
        LOCATION = 17;
        NAME = 19;
        PHONE = 20;

        // Any data synced from a profile like History,
        // Bookmarks, Autofill, etc.
        PROFILE_DATA = 21;

        // Any URL which reveals personal data or information
        // about a user's browsing habits, like the URL of a
        // website they're visiting/have visited before.
        SENSITIVE_URL = 22;

        // Any data originating from user input, regardless of the specific form
        // (e.g. text fields, search queries, etc.).
        USER_CONTENT = 26;

        USERNAME = 27;

        // Data originating from the content of the current webpage.
        WEB_CONTENT = 28;

        // Hardware or OS information like Manufacturer, Model, etc.
        HW_OS_INFO = 29;

        // Any data related to usage and performance metrics like UMA, UKM, DWA,
        // and Structured Metrics.
        USAGE_AND_PERFORMANCE_METRICS = 30;

        // If a request sends sensitive data/PII that doesn't fall in the
        // categories above, use `OTHER` and provide more details in the `data`
        // field.
        //
        // Can be combined with other data types. e.g. the following is valid:
        //   user_data {
        //     type: ACCESS_TOKEN
        //     type: OTHER
        //   }
        OTHER = 999;

        // `user_data::type` is mandatory in annotations. Use `NONE` if the
        // request doesn't send user data. For instance: fetching a static
        // resource from the public web, using a hard-coded URL.
        NONE = 1000;
      }
      repeated UserDataType type = 1;
    }

    UserData user_data = 8;

    // Date when this annotation was last reviewed
    // in YYYY-MM-DD format.
    string last_reviewed = 9;
  }

  TrafficSemantics semantics = 3;

  // Next tag: 8
  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 non-device enterprise
    // policy.
    // see out/Debug/gen/components/policy/proto/chrome_settings.proto
    repeated enterprise_management.ChromeSettingsProto chrome_policy = 4;

    // Policy configuration(s) that disable or limit this network request.
    // This would be a text serialized protobuf of any device enterprise
    // policy. See components/policy/proto/chrome_device_policy.proto.
    repeated enterprise_management.ChromeDeviceSettingsProto
        chrome_device_policy = 7;

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

    // TODO(b/254273300): add deprecated_policies tag in auditor.py
    repeated string deprecated_policies = 6;
  }

  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;
};