components/attribution_reporting/registration.mojom

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

module attribution_reporting.mojom;

import "components/attribution_reporting/source_registration_time_config.mojom";
import "components/attribution_reporting/trigger_data_matching.mojom";
import "components/attribution_reporting/debug_types.mojom";
import "mojo/public/mojom/base/int128.mojom";
import "mojo/public/mojom/base/time.mojom";
import "services/network/public/mojom/schemeful_site.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

// Encapsulates a potentially trustworthy origin. Equivalent to
// attribution_reporting::SuitableOrigin.
struct SuitableOrigin {
  url.mojom.Origin origin;
};

// Filter data for selectively matching attribution sources and triggers.
// See https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#optional-attribution-filters
// for details.
struct FilterData {
  // Map of filter name to a possibly empty set of values. Must not contain
  // `source_type` or `_lookback_window` keys.
  map<string, array<string>> filter_values;
};

// Internal structure to support the lookback window implementation.
struct FilterConfig {
  mojo_base.mojom.TimeDelta? lookback_window;
  map<string, array<string>> filter_values;
};

// Filters for selectively matching attribution sources and triggers.
// See https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#optional-attribution-filters
// for details.
struct FilterPair {
  // If non-empty, this trigger will be ignored unless the attributed source's
  // filter data matches.
  array<FilterConfig> positive;

  // If non-empty, this trigger will be ignored unless the attributed source's
  // filter data does *NOT* match.
  array<FilterConfig> negative;
};

// See https://github.com/WICG/attribution-reporting-api/blob/main/AGGREGATE.md#attribution-source-registration
// for details.
struct AggregationKeys {
  map<string, mojo_base.mojom.Uint128> keys;
};

// Struct containing the trigger-side aggregatable data.
struct AggregatableTriggerData {
  mojo_base.mojom.Uint128 key_piece;
  array<string> source_keys;
  FilterPair filters;
};

// Target site(s) where a source can be attributed.
struct DestinationSet {
  array<network.mojom.SchemefulSite> destinations;
};

// Reporting configuration that controls the early reporting time windows for a
// source.
struct EventReportWindows {
  mojo_base.mojom.TimeDelta start_time;
  array<mojo_base.mojom.TimeDelta> end_times;
};

// https://wicg.github.io/attribution-reporting-api/#trigger-data-set
struct TriggerDataSet {
  array<uint32> trigger_data;
};

// Aggregatable contribution for aggregatable debug types.
struct AggregatableDebugReportingContribution {
  mojo_base.mojom.Uint128 key_piece;
  uint32 value;
};

// Configuration for aggregatable debug reporting.
struct AggregatableDebugReportingConfig {
  mojo_base.mojom.Uint128 key_piece;
  map<DebugDataType,
      AggregatableDebugReportingContribution> debug_data;
  SuitableOrigin? aggregation_coordinator_origin;
};

// Configuration for source-side aggregatable debug reporting.
struct SourceAggregatableDebugReportingConfig {
  int32 budget;
  AggregatableDebugReportingConfig config;
};

// Target identifiers used for pre-attribution filtering.
struct AttributionScopesSet {
  array<string> scopes;
};

// Configuration for attribution scopes.
struct AttributionScopesData {
  AttributionScopesSet attribution_scopes_set;

  // Represents the number of distinct attribution scopes allowed per
  // destination for a source's reporting origin.
  uint32 attribution_scope_limit;

  // Represents the maximum number of trigger states for an event source type
  // sources per destination for a source's reporting origin.
  uint32 max_event_states;
};

// Defines aggregatable names and their associated budget for a trigger to
// selectively contribute to.
struct AggregatableNamedBudgetDefs {
  map<string, int32> budgets;
};

struct SourceRegistration {
  DestinationSet destinations;

  // Data that will be sent in attribution reports to identify this source.
  uint64 source_event_id = 0;

  // Specifies how long this source is eligible for attribution.
  mojo_base.mojom.TimeDelta expiry;

  TriggerDataSet trigger_data;

  EventReportWindows event_report_windows;

  // Specifies how many event-level reports can be generated across all trigger
  // specs for the source.
  int32 max_event_level_reports;

  // Specifies how long after source registration an aggregatable
  // report can be generated with this source.
  mojo_base.mojom.TimeDelta aggregatable_report_window;

  // Priority for this source.
  int64 priority = 0;

  // A key that is propagated through the Attribution Reporting API for
  // debugging purposes.
  uint64? debug_key;

  FilterData filter_data;

  AggregationKeys aggregation_keys;

  // Specifies whether to enable verbose debug reporting.
  bool debug_reporting = false;

  // Controls how trigger data is matched against the source's trigger specs.
  TriggerDataMatching trigger_data_matching;

  // Controls the epsilon parameter used for obtaining a randomized response for
  // the containing source registration. Must be greater than or equal to 0.
  // https://wicg.github.io/attribution-reporting-api/#obtain-a-randomized-source-response
  double event_level_epsilon;

  // Specifies aggregatable debug reporting configuration.
  SourceAggregatableDebugReportingConfig aggregatable_debug_reporting_config;

  // Specifies the priority of the destination in regards to source destination
  // limit.
  int64 destination_limit_priority;

  // Controls the scopes the source can be attributed to along with the amount
  // limit of scopes and the max number of event states. Logic pertaining to
  // scopes are ignored if this field is null.
  AttributionScopesData? attribution_scopes_data;

  // Specifies how the aggregatable budget should be allocated across specified
  // names for triggers to selectively contribute to.
  AggregatableNamedBudgetDefs aggregatable_named_budget_defs;
};

// Mojo representation of the trigger configuration provided by a reporting
// origin. This data is provided arbitrarily by certain subresources on a
// page which invoke Attribution Reporting.
struct EventTriggerData {
  // Value which identifies this trigger in attribution reports, determined by
  // reporting origin.
  uint64 data = 0;

  // Priority of this trigger relative to other attributed triggers for a
  // source. Reports created with high priority triggers will be reported over
  // lower priority ones.
  int64 priority = 0;

  // Key which allows deduplication against existing attributions for the same
  // source.
  uint64? dedup_key;

  FilterPair filters;
};

struct AggregatableDedupKey {
  // Key which allows deduplication against existing attributions for the same
  // source.
  uint64? dedup_key;

  FilterPair filters;
};

struct AggregatableValuesValue {
  uint32 value;
  uint64 filtering_id;
};

struct AggregatableValues {
  // A map of aggregation key identifier and the corresponding aggregatable
  // values value.
  map<string, AggregatableValuesValue> values;

  FilterPair filters;
};

struct AggregatableNamedBudgetCandidate {
  // Name to allocate budget towards as specified by the source registration. If
  // no name is provided the trigger's contribution will subtract from the total
  // budget.
  string? name;

  FilterPair filters;
};

// Represents a request from a reporting origin to trigger attribution on a
// given site. See:
// https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#triggering-attribution
struct TriggerRegistration {
  // List of all event trigger data objects declared by the event trigger
  // header. This data is arbitrarily set by the reporting origin.
  array<EventTriggerData> event_triggers;

  FilterPair filters;

  // List of all aggregatable trigger data objects declared by the trigger
  // header.
  array<AggregatableTriggerData> aggregatable_trigger_data;

  // List of all aggregatable values for matching a contribution value with a
  // source's aggregation key.
  array<AggregatableValues> aggregatable_values;

  // A key that is propagated through the Attribution Reporting API for
  // debugging purposes.
  uint64? debug_key;

  // List of all aggregatable dedup keys for deduplication against existing
  // aggregatable reports for the same source.
  array<AggregatableDedupKey> aggregatable_dedup_keys;

  // Specifies whether to enable verbose debug reporting.
  bool debug_reporting = false;

  // Specifies the deployment option for the aggregation service. The default
  // deployment will be used if not set.
  SuitableOrigin? aggregation_coordinator_origin;

  // Specifies whether to include source registration time in aggregatable
  // reports.
  SourceRegistrationTimeConfig source_registration_time_config;

  // Specifies the context ID associated with the trigger. The context ID
  // cannot be empty or longer than 64 bytes.
  string? trigger_context_id;

  // Specifies the maximum size of filtering ids within `aggregatable_values`.
  uint8 aggregatable_filtering_id_max_bytes;

  // Specifies the aggregatable debug reporting configuration.
  AggregatableDebugReportingConfig aggregatable_debug_reporting_config;

  // Specifies the scopes that this trigger can attribute to.
  AttributionScopesSet attribution_scopes;

  // List of all aggregatable named budgets for matching with source side
  // budgets to contribute to.
  array<AggregatableNamedBudgetCandidate> aggregatable_named_budget_candidates;
};

// Represents a source or trigger registration item that will be passed to the OS, if supported.
struct OsRegistrationItem {
  // The URL to which the OS will make a request in order to retrieve the actual
  // source or trigger registration.
  url.mojom.Url url;
  // Specifies whether to enable verbose debug reporting.
  bool debug_reporting;
};

// Represents a source or trigger registration that will be passed to the OS, if supported.
// A registration may contain multiple registration items.
struct OsRegistration {
  // The registrations to which the OS will make a request in order to retrieve the actual
  // source or trigger registration.
  array<OsRegistrationItem> items;
};