Merge pull request #335 from patcg-individual-drafts/yao-per-epoch-in…

…tro-delay

[spec & explainer] Make the epoch introduction delay per-site per-epoch

README.md

@@ -88,7 +88,7 @@ The topics will be inferred by the browser. The browser will leverage a classifi
     * The 5% noise is introduced to ensure that each topic has a minimum fraction of members as well as to provide some amount of plausible deniability.
     * The reason that each site gets associated with only one of the user's topics for that epoch is to ensure that callers on different sites for the same user see different topics. This makes it harder to reidentify the user across sites.
         * e.g., site A might see topic ‘cats’ for the user, but site B might see topic ‘automobiles’. It’s difficult for the two to determine that they’re looking at the same user.
-    * The beginning of a week is per-user and per-site. That is, for the same user, site A may see the new week's topics introduced at a different time than site B. This is to make it harder to correlate the same user across sites via the time that they change topics.
+    * The beginning of a week is per-user, per-site, and per-epoch. That is, for the same user, site A may see the new week's topics introduced at a different time than site B, and for the same user and site, the duration of a topic may not be exactly one week. This is to make it harder to correlate the same user across sites via the time that they change topics, or via the time interval between two changes.
 * Not every API caller will receive a topic. Only callers that observed the user visit a site about the topic in question within the past three weeks can receive the topic. If the caller (specifically the site of the calling context) did not call the API in the past for that user on a site about that topic, then the topic will not be included in the array returned by the API. The exception to this filtering is the 5% random topic, that topic will not be filtered.
     * Note that observing a topic also includes observing the topic's entire ancestry tree. For instance, observing `/Arts & Entertainment/Humor/Live Comedy` also counts as having observed `/Arts & Entertainment/Humor/` and `/Arts & Entertainment`.
     * This is to prevent the direct dissemination of user information to more parties than the technology that the API is replacing (third-party cookies).

spec.bs

@@ -359,7 +359,7 @@ spec: html; urlPrefix: https://www.rfc-editor.org/rfc/
     1. If |epochs| is empty, then return an empty [=list=].
     1. Let |numEpochs| be |epochs|'s [=list/size=].
     1. Let |lastEpochTime| be |epochs|[|numEpochs| − 1]'s [=epoch/time=].
-    1. Let |epochSwitchTimeDecisionMessageArray| be the concatenation of "epoch-switch-time-decision|" and |callerContext|'s [=topics caller context/top level context domain=].
+    1. Let |epochSwitchTimeDecisionMessageArray| be the concatenation of "epoch-switch-time-decision|", |lastEpochTime|, and |callerContext|'s [=topics caller context/top level context domain=].
     1. Let |epochSwitchTimeDecisionHmacOutput| be the output of the [=HMAC algorithm=], given input parameters: whichSha=SHA256, key=user agent's [=user agent/user topics state=]'s [=user topics state/hmac key=], and message_array=|epochSwitchTimeDecisionMessageArray|.
     1. Let |epochSwitchTimeDecisionHash| be 64-bit truncation of |epochSwitchTimeDecisionHmacOutput|.
     1. Let |epochSwitchTimeDelayIntroduction| be a [=duration=] of (|epochSwitchTimeDecisionHash| % 172800) seconds (i.e. 172800 is 2 days in seconds).
@@ -382,7 +382,7 @@ spec: html; urlPrefix: https://www.rfc-editor.org/rfc/
   </div>
 
   <div class="note">
-    This roughly returns 3 recently calculated epochs, either counting back from the last epoch, or from the second to the last epoch. The decision depends on whether some fixed duration (between 0 and 2 days, sticky to a user agent & site) has passed since the last epoch was calculated. This essentially adds a per-site fixed delay to the epoch switch time, to make it harder to correlate the same user across sites via the time that topics are changed. The HMAC helps to compute the per-site delay on the fly, without needing to store extra data for each site.
+    This roughly returns 3 recently calculated epochs, either counting back from the last epoch, or from the second to the last epoch. The decision depends on whether some fixed duration (between 0 and 2 days, sticky to a user agent, site, and the last epoch) has passed since the last epoch was calculated. This essentially adds a per-site per-epoch fixed delay to the epoch switch time, to make it harder to correlate the same user across sites via the time that topics are changed, or via the time interval between two changes. The HMAC helps to compute the per-site per-epoch delay on the fly, without needing to store extra data for each site or epoch.
   </div>
 
   <h2 id="get-the-number-of-distinct-versions-in-epochs-header">Get the number of distinct versions in epochs</h2>