// 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.
//
// See `content/browser/fenced_frame/fenced_frame_config.h` for a high-level
// description of the FencedFrameConfig information flow.

module blink.mojom;

import "services/network/public/mojom/schemeful_site.mojom";
import "services/network/public/mojom/permissions_policy/permissions_policy.mojom";
import "services/network/public/mojom/permissions_policy/permissions_policy_feature.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "url/mojom/url.mojom";
import "url/mojom/origin.mojom";

enum ReportingDestination {
  kBuyer,
  kSeller,
  kComponentSeller,
  kSharedStorageSelectUrl,
  kDirectSeller,
};

// The fenced frame config's "mode" describes a set of functionalities that it
// should have. (In the future, the concept of a "mode" will be removed, and
// replaced with individual fields controlling each functionality.)
// The mode is a function of the API that creates the config. Protected Audience
// and Shared Storage use kOpaqueAds mode, and the WebIDL FencedFrameConfig()
// constructor uses kDefault mode.
// https://github.com/WICG/fenced-frame/blob/master/explainer/modes.md
enum DeprecatedFencedFrameMode {
  kDefault = 0,
  kOpaqueAds = 1,
};

// In order to represent that a value exists in a different process but is
// hidden from this process, we use a union of a type T and this singleton enum
// `Opaque`. (This is used by a more privileged process to censor information
// that is being sent to a less privileged process, based on fenced
// frame-specific privacy policies.
enum Opaque {
  kOpaque
};

// Unlike event-level reporting through reportEvent(), automatic beacons only
// support a few specified types. Once the event type string is validated in
// setReportEventDataForAutomaticBeacons(), they are converted into an enum
// and used as the key in the automatic beacon info mapping stored in the
// browser.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum AutomaticBeaconType {
  kDeprecatedTopNavigation = 0,
  kTopNavigationStart = 1,
  kTopNavigationCommit = 2
};

union PotentiallyOpaqueURL {
  url.mojom.Url transparent;
  Opaque opaque;
};

union PotentiallyOpaqueSize {
  gfx.mojom.Size transparent;
  Opaque opaque;
};

union PotentiallyOpaqueBool {
  bool transparent;
  Opaque opaque;
};

struct AdAuctionData {
  url.mojom.Origin interest_group_owner;
  string interest_group_name;
};

union PotentiallyOpaqueAdAuctionData {
  AdAuctionData transparent;
  Opaque opaque;
};

union PotentiallyOpaqueConfigVector {
  array<FencedFrameConfig> transparent;
  Opaque opaque;
};

struct URNConfigPair {
  url.mojom.Url urn;
  FencedFrameConfig config;
};

union PotentiallyOpaqueURNConfigVector {
  array<URNConfigPair> transparent;
  Opaque opaque;
};

struct SharedStorageBudgetMetadata {
  network.mojom.SchemefulSite site;
  double budget_to_charge;
  bool top_navigated;
};

union PotentiallyOpaqueSharedStorageBudgetMetadata {
  SharedStorageBudgetMetadata transparent;
  Opaque opaque;
};

// Stores information about the frame's parent's permissions policy. Normally
// this information is inaccessible due to the fenced frame boundary, but this
// is needed when calculating permissions inheritance. This information will be
// used to build a copy of the fenced frame's parent's permissions policy.
struct ParentPermissionsInfo {
  array<network.mojom.ParsedPermissionsPolicyDeclaration>
      parsed_permissions_policy;
  url.mojom.Origin origin;
};

// The `FencedFrameConfig` struct is used to transfer a redacted version
// (`blink::RedactedFencedFrameConfig`) of `content::FencedFrameConfig` from the
// browser process, to the renderer process, where the redaction process is
// specific to whether the target renderer is either a fenced frame's embedder
// or a frame inside the fenced frame tree. For more documentation on the
// redaction process, see the comments above `content::FencedFrameConfig`. In
// brief, this is a collection of properties that the browser process exposes to
// an embedder that may wish to load into a fenced frame. The config will
// determine the fenced frame's behavior, but it may have certain fields
// redacted (marked as opaque) in order to preserve privacy. For example:
// * This object is returned to the caller of APIs that use fenced frames,
//   so that they can inspect the (unredacted) information inside and then
//   load it into a fenced frame.
// * When nested frames are declared in the above APIs, the top-level
//   frame will be given access to these objects in order to load the nested
//   configs.
struct FencedFrameConfig {
  // This is the actual URL that will be loaded into the fenced frame when
  // navigated to. It can be opaque because for the current use cases (Protected
  // Audience, shared storage), we never want to expose anything about the
  // actual resource beyond its existence, to the embedder of a fenced frame.
  PotentiallyOpaqueURL? mapped_url;

  PotentiallyOpaqueSize? container_size;

  PotentiallyOpaqueSize? content_size;

  PotentiallyOpaqueBool? deprecated_should_freeze_initial_size;

  PotentiallyOpaqueAdAuctionData? ad_auction_data;

  PotentiallyOpaqueConfigVector? nested_configs;

  PotentiallyOpaqueSharedStorageBudgetMetadata? shared_storage_budget_metadata;

  // This is the internal URN that represents this config in the browser-side
  // `FencedFrameURLMapping`. When this config is navigated to via a fenced
  // frame, it is this internal urn:uuid that we send to the browser to navigate
  // to the actual browser-side `content::FencedFrameConfig` object that
  // represents this instance of this struct. `blink::IsValidUrnUuidURL()` will
  // always be true when called with this urn.
  url.mojom.Url urn_uuid;

  // The fenced frame's mode (default or opaque-ads).
  // TODO(crbug.com/1347953): This field is not yet used.
  // TODO(crbug.com/1347953): Decompose this field into flags that directly
  // control the frame's behavior, e.g. sandbox flags. We don't want the
  // concept of a mode to stick around in the future.
  DeprecatedFencedFrameMode mode;

  // APIs like Protected Audience and Shared Storage require specific features
  // to be enabled in the loaded frame. If an embedder is allowed to set
  // arbitrary permissions on a fenced frame, it can be used as a fingerprinting
  // channel. Instead, each API sets a list of feature permissions that a fenced
  // frame needs to enable to be allowed to load. Only used for fenced frames
  // with a fixed permissions policy.
  array<network.mojom.PermissionsPolicyFeature> effective_enabled_permissions;

  // Fenced frames with a flexible permissions policy are allowed to inherit
  // certain permissions policies from their parent. However, a fenced frame's
  // renderer process doesn't have access to its parent. Instead, we give it
  // this information through the fenced frame config so that it can calculate
  // permissions inheritance. Only non-null for non-opaque fenced frames (i.e.
  // fenced frames whose mode = DeprecatedFencedFrameMode::kDefault).
  ParentPermissionsInfo? parent_permissions_info;
};

// The `FencedFrameProperties` struct is used to transfer a redacted version
// (`blink::RedactedFencedFrameProperties`) of `content::FencedFrameProperties`
// across processes. In brief, this is a collection of properties that is being
// or has already been loaded into a fenced frame and determines its behavior,
// but may have certain fields redacted (marked as opaque) in order to preserve
// privacy.
// For example:
// * When a `FencedFrameConfig` (see above) is loaded into a fenced frame, a
//   `FencedFrameProperties` object is generated from the config and is
//   sent to the fenced frame's renderer upon navigation commit. These
//   properties are used to determine availability of certain APIs, store
//   nested configs, etc.
struct FencedFrameProperties {
  PotentiallyOpaqueURL? mapped_url;

  PotentiallyOpaqueSize? container_size;

  PotentiallyOpaqueSize? content_size;

  PotentiallyOpaqueBool? deprecated_should_freeze_initial_size;

  PotentiallyOpaqueAdAuctionData? ad_auction_data;

  // If this is a navigation to the result of an InterestGroup auction, this
  // is a list of URNs that map to auction component URLs. Null, otherwise.
  // When non-null, always contains exactly kMaxAdAuctionAdComponents=20 URNs
  // to avoid use as a data sidechannel between auction worklets and the
  // fenced frames their results are loaded in.
  PotentiallyOpaqueURNConfigVector? nested_urn_config_pairs;

  PotentiallyOpaqueSharedStorageBudgetMetadata? shared_storage_budget_metadata;

  DeprecatedFencedFrameMode mode;

  array<network.mojom.PermissionsPolicyFeature> effective_enabled_permissions;

  // Fenced frames with a flexible permissions policy are allowed to inherit
  // certain permissions policies from their parent. However, a fenced frame's
  // renderer process doesn't have access to its parent. Instead, we give it
  // this information through the fenced frame config so that it can calculate
  // permissions inheritance. Only non-null for non-opaque fenced frames (i.e.
  // fenced frames whose mode = DeprecatedFencedFrameMode::kDefault).
  ParentPermissionsInfo? parent_permissions_info;

  // Whether the document this config belongs to is cross-origin to the document
  // that owns the fenced frame config. Equivalent to
  // FencedFrameEntity::kCrossOriginContent in the browser-side config.
  bool is_cross_origin_content;

  // Whether the original document loaded with this config opted in to
  // cross-origin event-level reporting. That is, if the document was served
  // with the `Allow-Cross-Origin-Event-Reporting=true` response header. This is
  // the first half of the opt-in process for a cross-origin subframe to send a
  // `reportEvent()` beacon using this config's reporting metadata successfully.
  bool allow_cross_origin_event_reporting;
};