blink_apis.proto

// Copyright 2020 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 identifiability.blink_apis;

message Snapshot {
  string chromium_revision = 1;

  repeated InterfaceLike interfaces = 2;
  repeated InterfaceLike namespaces = 3;
  repeated Dictionary dictionaries = 4;
  repeated Enumeration enumerations = 5;
  repeated Operation callback_functions = 6;
  repeated InterfaceLike callback_interfaces = 7;
  repeated Typedef typedefs = 8;
}

// Type of HighEntropy.
enum HighEntropyType {
  // Invalid value. Means that the field is uninitialized.
  HIGH_ENTROPY_UNSPECIFIED = 0;

  // Not a source of identifiable information.
  HIGH_ENTROPY_BENIGN = 1;

  // A source of identifiable information. But the surface doesn't have
  // a classification.
  HIGH_ENTROPY_UNCLASSIFIED = 2;

  // A source of identifiable information. The mapping from the inputs to the
  // output of the annotated API directly conveys the identifiable information.
  HIGH_ENTROPY_DIRECT = 3;
}

// Includes both WebIDL defined extended attributes as well as Chromium specific
// custom extended attributes.
//
// The latter are described in:
// https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/renderer/bindings/IDLExtendedAttributes.md
// Next ID: 13
message ExtendedAttributes {
  // https://heycam.github.io/webidl/#CrossOriginIsolated
  bool cross_origin_isolated = 1;

  message Exposed {
    string interface = 1;
    string member = 2;
  }

  // https://heycam.github.io/webidl/#Exposed
  // One value for each interface/partial interface/etc..
  repeated Exposed exposed = 2;

  // https://heycam.github.io/webidl/#Global
  bool global = 3;

  // https://heycam.github.io/webidl/#SameObject
  bool same_object = 4;

  // https://heycam.github.io/webidl/#SecureContext
  bool secure_context = 5;

  // https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#HighEntropy_m_a_c
  // Ideally this must always be one of the well defined values. However, the
  // HIGH_ENTROPY_UNSPECIFIED value should also be interpreted as
  // NOT_HIGH_ENTROPY.
  HighEntropyType high_entropy = 6;

  // Value of MeasureAs or the autogenerated use counter value. Empty or
  // undefined string is equivalent to no use counter.
  //
  // https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#measure_i_m_a_c
  string use_counter = 7;

  // The numeric value of the Use Counter feature constant.
  int64 use_counter_feature_value = 12;

  // Value of [RuntimeEnabled]
  // https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#runtimeenabled_i_m_a_c
  // Empty or undefined string is equivalent to there not being
  // a `RuntimeEnabled` attribute.
  string runtime_enabled = 8;

  // Cross origin exposure. The [CrossOrigin=(Setter)] and
  // [CrossOrigin=(Getter)] options are separated out into two distinct booleans
  // for easier access.
  // https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#crossorigin_m_a
  bool cross_origin_getter = 9;
  bool cross_origin_setter = 10;

  // https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#implementedas_i_m_s_a
  // Empty or undefined string is equivalent to an absent [ImplementedAs]
  // attribute.
  string implemented_as = 11;
}

// Represents an interface [^1], mixins or partial interface [^2], callback
// interface [^3], or namespace [^4].
//
// [^1]: https://heycam.github.io/webidl/#idl-interfaces
// [^2]: https://heycam.github.io/webidl/#idl-interface-mixins
// [^3]: https://heycam.github.io/webidl/#idl-callback-interfaces
// [^4]: https://heycam.github.io/webidl/#idl-namespaces
message InterfaceLike {
  // Must be non-empty and must satisfy the requirements outlined in
  // https://heycam.github.io/webidl/#idl-names . This should be trivially
  // satisfied for all valid WebIDLs in the Chromium tree.
  string name = 1;

  // If this interface is defined to inherit from another interface, the latter
  // is described here. Empty or undefined strings are interpreted as meaning
  // that the interface does not inherit from another.
  string inherits_from = 2;

  // Extended attributes for the interface. Some may percolate down to the
  // members.
  ExtendedAttributes extended_attributes = 3;

  // Members
  repeated Attribute attributes = 4;
  repeated Operation operations = 5;
  repeated Constant constants = 6;

  SourceLocation source_location = 30;
}

message IDLType {
  // This is the string representation of the type. E.g.: "unsigned long long"
  // or "sequence<USVString>" or somesuch. For this database, we leave out a lot
  // of detail which should still be available in this field.
  //
  // The contents of this field is expected to parse as the _Type_ production in
  // the WebIDL spec [^1]. The string may contain references to unresolved
  // typedefs.
  //
  // [1]: https://heycam.github.io/webidl/#prod-Type
  string idl_type_string = 1;

  // Each `depends_on` value is string containing an identifier that maps to
  // another `Interface` or `Dictionary` that's defined in the same snapshot.
  //
  // For example: "( boolean or sequence<Foo> or Bar )" depends on "Foo" and
  // "Bar" types. It also depends on "boolean" but that's a primitive type
  // that's not interesting for this database.
  //
  // All such dependent types must be listed for each type after resolving
  // typedefs.
  repeated string depends_on = 2;

  // Types can have these too. Though none of the attributes we are interested
  // in are likely to show up.
  ExtendedAttributes extended_attributes = 3;
}

// An ordered map.
// https://heycam.github.io/webidl/#idl-dictionaries
message Dictionary {
  // Name of the dictionary.
  string name = 1;
  string inherits_from = 2;

  // Dictionary member.
  // https://heycam.github.io/webidl/#dfn-dictionary-member
  message Member {
    string name = 1;
    ExtendedAttributes extended_attributes = 2;
    IDLType idl_type = 3;
    SourceLocation source_location = 30;
  }

  repeated Member members = 7;

  SourceLocation source_location = 30;
}

// Special operation types.
// https://heycam.github.io/webidl/#dfn-special-operation
enum SpecialOperationType {
  SPECIAL_OP_UNSPECIFIED = 0;  // Operation is not special.
  SPECIAL_OP_GETTER = 1;       // https://heycam.github.io/webidl/#dfn-getter
  SPECIAL_OP_SETTER = 2;       // https://heycam.github.io/webidl/#dfn-setter
  SPECIAL_OP_STRINGIFIER =
      3;  // https://heycam.github.io/webidl/#dfn-stringifier
}

// An Operation represents an interface member, callback interface member, or
// namespace member.
// https://heycam.github.io/webidl/#idl-operations
message Operation {
  string name = 1;
  ExtendedAttributes extended_attributes = 2;
  IDLType return_type = 3;
  repeated IDLType arguments = 4;

  // True for static operations.
  // https://heycam.github.io/webidl/#dfn-static-operation
  bool static = 9;

  // The following fields are only applicable to special operations.
  // https://heycam.github.io/webidl/#dfn-special-operation
  SpecialOperationType special_op_type = 5;

  SourceLocation source_location = 30;
}

// An interface member or a namespace member declaring a data field.
// https://heycam.github.io/webidl/#dfn-attribute
message Attribute {
  string name = 1;
  ExtendedAttributes extended_attributes = 2;
  IDLType idl_type = 3;
  bool is_static = 4;
  bool is_readonly = 5;

  SourceLocation source_location = 30;
}

// A declaration binding a value to a name.
// https://heycam.github.io/webidl/#dfn-attribute
message Constant {
  string name = 1;
  ExtendedAttributes extended_attributes = 2;
  IDLType idl_type = 3;

  // Textual serialization of the value. Should be interpreted as befitting
  // `type`. There should be no expectation that this representation is
  // unambiguously parsable. It's intended solely for human consumption.
  string value = 4;

  SourceLocation source_location = 30;
}

// Defines a type who's valid values are a set of strings.
// https://heycam.github.io/webidl/#dfn-enumeration
message Enumeration {
  string name = 1;

  // Enum values are strings.
  repeated string values = 2;

  SourceLocation source_location = 30;
}

// Declares a new name for a type.
// https://heycam.github.io/webidl/#dfn-typedef
// These are included for completeness.
message Typedef {
  string name = 1;
  IDLType idl_type = 2;

  SourceLocation source_location = 30;
}

message SourceLocation {
  // Relative to the root of the Chromium source tree. So pretty much all
  // strings start with 'third_party/blink/...'
  string filename = 1;

  // 1-based line number. 0 means there's no line-number information.
  int32 line = 2;
}