Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Spec "Referer" and "Origin" headers in reporting beacons. #164

Merged
merged 10 commits into from
Oct 2, 2024
Merged

Spec "Referer" and "Origin" headers in reporting beacons. #164

Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
9969495
spec referer and origin headers in reporting beacons
blu25 May 31, 2024
eee3fc2
replace stored ad root origin with parameter in sourceSnapshotParams
blu25 Jun 6, 2024
1b343e6
start addressing comments
blu25 Jun 21, 2024
db5423b
refactor ancestor root origin into helper algorithm
blu25 Jul 11, 2024
dc01c60
address review comments
blu25 Jul 24, 2024
e1b77ea
Merge branch 'master' into liam-referer-origin-header
blu25 Aug 14, 2024
309c1cf
add non-normative explanatory section
blu25 Aug 14, 2024
e961d33
address comments
blu25 Sep 20, 2024
52729d8
use initiator's referrer policy
blu25 Oct 1, 2024
cb7f4e5
Update spec.bs
blu25 Oct 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 152 additions & 30 deletions spec.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -727,12 +727,21 @@ A <dfn export for=fencedframetype>pending event</dfn> is a [=struct=] with the f

: <dfn>event</dfn>
:: a [=fencedframetype/destination event=]

: <dfn>request initiator</dfn>
:: an [=origin=]

: <dfn>initiator referrer policy</dfn>
:: a [=referrer policy=]
</dl>

A <dfn export for=fencedframetype>reporting destination info</dfn> is a [=struct=] with the
following [=struct/items=]:

<dl export dfn-for="reporting destination info">
: <dfn>reporting url declarer origin</dfn>
:: an [=origin=]

: <dfn>reporting url map</dfn>
:: a [=map=] whose [=map/keys=] are [=strings=] and whose [=map/values=] are [=URLs=]

Expand Down Expand Up @@ -761,17 +770,21 @@ be sent.

<div algorithm>
In order to <dfn export>finalize a reporting destination</dfn>, given a [=fencedframetype/fenced
frame reporting map=] |reporting map|, a {{FenceReportingDestination}} |destination|, a [=map=]
|destination map| whose [=map/keys=] are [=strings=] and whose [=map/values=] are [=urls=], and
|macro map|, which is either null or a [=map=] whose [=map/keys=] are [=strings=] and whose
[=map/values=] are [=strings=], run these steps:
frame reporting map=] |reporting map|, a {{FenceReportingDestination}} |destination|, an
[=origin=] |reporting url declarer origin|, a [=map=] |destination map| whose [=map/keys=] are
[=strings=] and whose [=map/values=] are [=urls=], and |macro map|, which is either null or a
[=map=] whose [=map/keys=] are [=strings=] and whose [=map/values=] are [=strings=], run these
steps:

1. [=Assert=] that |reporting map|[|destination|] is a [=list=] (i.e., that |destination|'s
metadata has not yet been finalized).

1. Let |pending event list| be |reporting map|[|destination|].

1. [=map/Set=] |reporting map|[|destination|] to a [=struct=] with the following [=struct/items=]:
: [=reporting destination info/reporting url declarer origin=]
:: |reporting url declarer origin|

: [=reporting destination info/reporting url map=]
:: |destination map|

Expand All @@ -780,7 +793,9 @@ be sent.

1. [=list/For each=] |pending event| of |pending event list|:

1. [=Send a beacon=] with |destination map| and |pending event|'s [=pending event/event=].
1. [=Send a beacon=] with |destination map|, |pending event|'s [=pending event/event=],
|pending event|'s [=pending event/request initiator=], and |pending event|'s [=pending
event/initiator referrer policy=].
</div>

A <dfn export for=fencedframetype>fenced frame reporting metadata</dfn> is a [=struct=] with the
Expand Down Expand Up @@ -859,7 +874,8 @@ A <dfn for=fencedframetype>destination event</dfn> is either a

<div algorithm>
In order to <dfn>send a beacon</dfn> with a [=fencedframetype/reporting destination info=]
|destination info| and a [=fencedframetype/destination event=] |event|, run these steps:
|destination info|, a [=fencedframetype/destination event=] |event|, an [=origin=]
|request initiator|, and a [=referrer policy=] |initiator referrer policy| run these steps:

1. Let |destination url| be an empty [=string=].

Expand Down Expand Up @@ -947,11 +963,21 @@ A <dfn for=fencedframetype>destination event</dfn> is either a
beacons](https://wicg.github.io/attribution-reporting-api/#ref-for-request-service-workers-mode).

: [=request/origin=]
:: <span class=XXX>Get the origin from somewhere, like the [implementation
does](https://source.chromium.org/chromium/chromium/src/+/refs/heads/main:content/browser/fenced_frame/fenced_frame_reporter.cc;l=384;drc=183dd920ea5d6aed92e007c40e226f1f840c0567)</span>.
:: |request initiator| if |event| is a [=fencedframetype/destination URL event=], and
|destination info|'s [=reporting destination info/reporting url declarer origin=] otherwise.
blu25 marked this conversation as resolved.
Show resolved Hide resolved
blu25 marked this conversation as resolved.
Show resolved Hide resolved

Note: The reporting destination for a [=fencedframetype/destination URL event=] is determined
by the {{Document}} that calls {{Fence/reportEvent()}}, as opposed to a [=fencedframetype/
destination enum event=] or [=fencedframetype/automatic beacon event=] whose reporting
destinations are determined in the worklet that created the [=fenced frame config=] that
loaded this {{Document}}. We set the [=request/origin=] to the [=origin=] of the {{Document}}
or worklet that determined the reporting destination to prevent cross-site request forgery.

: [=request/referrer=]
:: `"no-referrer"`
:: |request initiator|
blu25 marked this conversation as resolved.
Show resolved Hide resolved

: [=request/referrer policy=]
:: |initiator referrer policy|

: [=request/mode=]
:: `"cors"`
Expand All @@ -974,8 +1000,9 @@ A <dfn for=fencedframetype>destination event</dfn> is either a

<div algorithm>
In order to <dfn>report an event</dfn> using a [=fencedframetype/fenced frame reporter=]
|reporter| with a {{FenceReportingDestination}} |destination|, and a
[=fencedframetype/destination event=] |event|, run these steps:
|reporter| with a {{FenceReportingDestination}} |destination|, an [=origin=] |request initiator|,
a [=referrer policy=] |initiator referrer policy| and a [=fencedframetype/destination event=]
blu25 marked this conversation as resolved.
Show resolved Hide resolved
|event|, run these steps:

1. Let |metadata| be |reporter|'s
[=fenced frame reporter/fenced frame reporting metadata reference=].
Expand Down Expand Up @@ -1012,6 +1039,12 @@ A <dfn for=fencedframetype>destination event</dfn> is either a
: [=pending event/event=]
:: |event|

: [=pending event/request initiator=]
:: |request initiator|

: [=pending event/initiator referrer policy=]
:: |initiator referrer policy|

1. [=list/Append=] |newEvent| to |reporting map|[|destination|].

1. Return.
Expand All @@ -1021,7 +1054,8 @@ A <dfn for=fencedframetype>destination event</dfn> is either a
1. [=Assert=] that |reporting map|[|destination|] is a [=map=] (i.e., that |destination|'s
metadata has been finalized).

1. [=Send a beacon=] with |reporting map|[|destination|] and |event|.
1. [=Send a beacon=] with |reporting map|[|destination|], |event|, |request initiator|, and
|initiator referrer policy|.
</div>

<div algorithm>
Expand Down Expand Up @@ -1648,6 +1682,14 @@ Several APIs specific to fenced frames are defined on the {{Fence}} interface.

1. If |instance|'s [=fenced frame config instance/fenced frame reporter=] is null, then return.

1. Let |document| be [=this=]'s [=relevant global object=]'s [=associated Document=].

1. Let |request initiator| be [=this=]'s [=relevant settings object=]'s [=environment settings
object/origin=].

1. Let |initiator referrer policy| be |document|'s [=Document/policy container=]'s [=policy
container/referrer policy=].

1. If |event| is a {{DOMString}}:

1. If [=this=]'s [=relevant settings object=]'s [=environment settings object/origin=] and
Expand Down Expand Up @@ -1686,8 +1728,8 @@ Several APIs specific to fenced frames are defined on the {{Fence}} interface.
* |destinationURL| [=url/scheme=] is not "`https`";

1. Run [=report an event=] using |instance|'s [=fenced frame config instance/fenced frame
reporter=] with {{FenceReportingDestination/buyer}} and a
[=fencedframetype/destination URL event=] that is |event|'s
reporter=] with {{FenceReportingDestination/buyer}}, |request initiator|, |initiator
referrer policy| and a [=fencedframetype/destination URL event=] that is |event|'s
{{FenceEvent/destinationURL}}.

1. Otherwise:
Expand All @@ -1696,8 +1738,6 @@ Several APIs specific to fenced frames are defined on the {{Fence}} interface.

1. [=exception/Throw=] a {{TypeError}}.

1. Let |document| be [=this=]'s [=relevant global object=]'s [=associated Document=].

1. Let |attributionReportingEnabled| be the result of determining whether |document| is
[=allowed to use=] the "<code>{{PermissionPolicy/attribution-reporting}}</code>" feature.

Expand All @@ -1706,8 +1746,8 @@ Several APIs specific to fenced frames are defined on the {{Fence}} interface.
1. [=list/For each=] |destination| of |event|'s {{FenceEvent/destination}}:

1. Run [=report an event=] using |instance|'s [=fenced frame config instance/fenced frame
reporter=] with |destination| and a [=fencedframetype/destination enum event=] with the
following [=struct/items=]:
reporter=] with |destination|, |request initiator|, |initiator referrer policy|, and a
[=fencedframetype/destination enum event=] with the following [=struct/items=]:

: [=destination enum event/type=]
:: |event|'s {{FenceEvent/eventType}}
Expand Down Expand Up @@ -1906,6 +1946,15 @@ event|event-level beacon=] when a fenced frame initiates a successful [=navigate
cases where a [=navigate|navigation=] to a [=top-level traversable=] does not originate from a
<{fencedframe}>.

1. Let |request initiator| be |sourceOrigin| if |config|'s [=fenced frame config instance/is ad
component=] is false, and |sourceSnapshotParams|'s [=source snapshot params/initiator ancestor
root origin=] otherwise.

1. Let |initiator referrer policy| be |sourceSnapshotParams|'s [=source snapshot params/source
policy container=]'s [=policy container/referrer policy=] if |config|'s [=fenced frame config
instance/is ad component=] is false, and |sourceSnapshotParams|'s [=source snapshot
params/initiator ancestor root referrer policy=] otherwise.

1. Let |beacon data| be |sourceSnapshotParams|'s [=source snapshot params/automatic beacon data
map=][|eventType|].

Expand All @@ -1928,8 +1977,8 @@ event|event-level beacon=] when a fenced frame initiates a successful [=navigate
[=fencedframetype/fenced frame reporting map=]'s [=map/keys=]:

1. Run [=report an event=] using |config|'s [=fenced frame config instance/fenced frame
reporter=] with |destination| and an [=fencedframetype/automatic beacon event=] with the
following [=struct/items=]:
reporter=] with |destination|, |request initiator|, |initiator referrer policy|, and an
[=fencedframetype/automatic beacon event=] with the following [=struct/items=]:

: [=automatic beacon event/type=]
:: |eventType|
Expand Down Expand Up @@ -2305,8 +2354,6 @@ To mend the intended distinction between [=top-level traversables=] and [=fenced
[=traversable navigable/unfenced parent=] are both null.
</div>

<br>

<div algorithm>
To get the <dfn noexport for="navigable">top-level traversable</dfn> of a [=navigable=] |inputNavigable|:

Expand Down Expand Up @@ -2684,9 +2731,28 @@ CORP violation report=] algorithm, as leaving it unfenced may cause a privacy le
: <dfn for="source snapshot params">initiator fenced frame config instance</dfn>
:: a [=fenced frame config instance=] or null, initially null.

: <dfn for="source snapshot params">initiator ancestor root origin</dfn>
:: an [=origin=] or null, initially null.
blu25 marked this conversation as resolved.
Show resolved Hide resolved

: <dfn for="source snapshot params">initiator ancestor root referrer policy</dfn>
:: an [=referrer policy=] or null, initially null.

: <dfn for="source snapshot params">target fenced frame config</dfn>
:: a [=fenced frame config=] or null, initially null.

Note: The [=source snapshot params/initiator fenced frame config instance=] is the [=fenced frame
config instance=] that's loaded into a navigation initiator's [=browsing context=], if any exists.
The [=source snapshot params/initiator ancestor root origin=], for component ads, is the origin of
the top-level ad container, if any exists. The [=source snapshot params/initiator ancestor root
referrer policy=], for component ads, is the referrer policy of the top-level ad container, if any
exists. They are used by the [=attempt to send an automatic beacon=] algorithm to compare
[=origin=]s and determine which {{FenceReportingDestination}}s to send beacons and with what
information, if the <{fencedframe}>-initiated navigation succeeds. The [=source snapshot
params/target fenced frame config=] on the other hand, is the non-[=instantiate a
config|instantiated=] [=fenced frame config=] that will be loaded into a <{fencedframe}> element
for navigations targeting fenced frames. These fields do not interact *together* in any meaningful
way.

: <dfn for="source snapshot params">attribution reporting enabled</dfn>
:: a [=boolean=].

Expand All @@ -2700,14 +2766,6 @@ CORP violation report=] algorithm, as leaving it unfenced may cause a privacy le
:: a [=map=] whose [=map/keys=] are [=fencedframetype/automatic beacon event type=]s and whose
[=map/values=] are null or an [=fencedframetype/automatic beacon data=]

Note: The [=source snapshot params/initiator fenced frame config instance=] is the [=fenced frame
config instance=] that's loaded into a navigation initiator's [=browsing context=], if any exists.
It is used by the [=attempt to send an automatic beacon=] algorithm to compare [=origin=]s and
determine which {{FenceReportingDestination}}s to send beacons to, if the
<{fencedframe}>-initiated navigation succeeds. The [=source snapshot params/target fenced frame
config=] on the other hand, is the non-[=instantiate a config|instantiated=] [=fenced frame
config=] that will be loaded into a <{fencedframe}> element for navigations targeting fenced
frames. These fields do not interact *together* in any meaningful way.
</div>

<div algorithm>
Expand Down Expand Up @@ -2741,6 +2799,57 @@ CORP violation report=] algorithm, as leaving it unfenced may cause a privacy le
[=automatic beacon data/once=] set to true.
</div>

<div algorithm=get-initiator-ancestor>
To <dfn>get the initiator's fenced grand-ancestor's navigable</dfn> of a given {{Document}}
|sourceDocument|:

1. Let |navigable| be |sourceDocument|'s [=node navigable=].

1. While |navigable| is not null and |navigable| is not a [=fenced navigable container/fenced
blu25 marked this conversation as resolved.
Show resolved Hide resolved
navigable=]:

1. Set |navigable| to |navigable|'s [=navigable/parent=].

1. If |navigable| is null, return null.

1. [=Assert=]: |navigable| is a [=fenced navigable container/fenced navigable=].

1. Set |navigable| to |navigable|'s [=navigable/unfenced parent=].

1. While |navigable| is not null and |navigable| is not a [=fenced navigable container/fenced
navigable=]:

1. Set |navigable| to |navigable|'s [=navigable/parent=].

1. Return |navigable|.

<div id="get-initiator-ancestor-root-origin-example" class="example">
Given a {{Document}} embedded inside of a <{fencedframe}>, this algorithm gets the navigable of
the document's nearest fenced frame ancestor's nearest fenced frame ancestor. If no such "fenced
frame grand-ancestor" exists, the algorithm returns null. Therefore, this algorithm only returns
a navigable when given a Document that is, at a minimum, in a fenced frame which is itself in a
fenced frame. For example, for the given frame tree structure:

```
Main frame (A)
blu25 marked this conversation as resolved.
Show resolved Hide resolved
<fencedframe> (B)
<iframe> (C)
<fencedframe> (D)
<iframe> (E)
<fencedframe> (F)
```

The algorithm will return the following given each document:

- `Main frame (A)` will return `null`.
- `<fencedframe> (B)` will return `null`.
- `<iframe> (C)` will return `null`.
- `<fencedframe> (D)` will return `<fencedframe> (B)`.
- `<iframe> (E)` will return `<fencedframe> (B)`.
- `<fencedframe> (F)` will return `<fencedframe> (D)`.
</div>
</div>

<div algorithm=snapshot-source-snapshot-params>
Modify the [=snapshot source snapshot params=] algorithm to return a [=source snapshot params=]
with these additional fields:
Expand All @@ -2749,6 +2858,19 @@ CORP violation report=] algorithm, as leaving it unfenced may cause a privacy le
:: |sourceDocument|'s [=browsing context=]'s [=browsing context/fenced frame
config instance=]

: [=source snapshot params/initiator ancestor root origin=]
:: null if the result of running [=get the initiator's fenced grand-ancestor's navigable=] on
|sourceDocument| is null. Otherwise, |sourceDocument|'s [=get the initiator's fenced
grand-ancestor's navigable|initiator's fenced grand-ancestor's navigable=]'s
[=navigable/active document=]'s [=Document/origin=].

: [=source snapshot params/initiator ancestor root referrer policy=]
:: null if the result of running [=get the initiator's fenced grand-ancestor's navigable=] on
|sourceDocument| is null. Otherwise, |sourceDocument|'s [=get the initiator's fenced
grand-ancestor's navigable|initiator's fenced grand-ancestor's navigable=]'s
[=navigable/active document=]'s [=Document/policy container=]'s [=policy container/referrer
policy=].

: [=source snapshot params/attribution reporting enabled=]
:: The result of determining whether |sourceDocument| is [=allowed to use=] the
"<code>{{PermissionPolicy/attribution-reporting}}</code>" feature
Expand Down
Loading