From 9debabb9a71e0cf18462004ee1b5221c028b1322 Mon Sep 17 00:00:00 2001
From: Andrew Paseltiner <apaseltiner@google.com>
Date: Fri, 5 May 2023 12:06:41 -0400
Subject: [PATCH] Allow OS registration headers to specify multiple URLs (#780)

This does not add any new functionality to the API, as reporting origins
could already redirect to another URL under their control in order to
perform multiple registrations, but does obviate that
bandwidth-wasting anti-pattern.
---
 app_to_web.md                   | 11 ++++-----
 header-validator/test.os.js     |  8 +++++++
 header-validator/validate-os.js | 42 +++++++++++++++++----------------
 index.bs                        | 40 ++++++++++++++++++-------------
 4 files changed, 58 insertions(+), 43 deletions(-)

diff --git a/app_to_web.md b/app_to_web.md
index 1f7e8210cc..19f072dc95 100644
--- a/app_to_web.md
+++ b/app_to_web.md
@@ -54,17 +54,16 @@ background requests will be made and the browser will not set
 `Attribution-Reporting-Eligible` header on `<a>`, `window.open`, `<img>`, or
 `<script>` requests.
 
-If the `Attribution-Reporting-Support` header indicates OS support, the reporting origin can optionally respond to the request with a [string structured header](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-header-structure-15#section-3.3.3) that indicates a desire to use the OS's attribution API instead of the browser's. Note that the API also allows browsers to only support OS-level attribution if they choose.
-```
+If the `Attribution-Reporting-Support` header indicates OS support, the reporting origin can optionally respond to the request with a [list structured header](https://httpwg.org/specs/rfc8941.html#list) containing one or more URLs that indicates a desire to use the OS's attribution API instead of the browser's. Note that the API also allows browsers to only support OS-level attribution if they choose.
+```http
 // Registers a source against a native OS attribution API
-Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-android-source?..."
-
+Attribution-Reporting-Register-OS-Source: "https://adtech.example/register", "https://other-adtech.example/register"
 ```
 
 Trigger registrations will accept a new response header as well:
-```
+```http
 // Registers a trigger against a native OS attribution API
-Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-android-trigger?..."
+Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register", "https://other-adtech.example/register"
 ```
 
 After receiving these headers, the browser will pass these URLs into the underlying OS API with any additional information including:
diff --git a/header-validator/test.os.js b/header-validator/test.os.js
index 816d2ed291..8bee21382e 100644
--- a/header-validator/test.os.js
+++ b/header-validator/test.os.js
@@ -6,6 +6,7 @@ const tests = [
   {input: '"https://a.test/"'},
   {input: '"http://localhost/"'},
   {input: '"http://127.0.0.1/"'},
+  {input: '"https://a.test/", "https://b.test/"'},
 
   // Warnings
   {
@@ -30,6 +31,13 @@ const tests = [
       msg: 'must be a string',
     }],
   },
+  {
+    input: '("https://a.test/")',
+    errors: [{
+      path: [],
+      msg: 'must be a string',
+    }],
+  },
 
   // Invalid URL
   {
diff --git a/header-validator/validate-os.js b/header-validator/validate-os.js
index 08ef766509..cbd519193e 100644
--- a/header-validator/validate-os.js
+++ b/header-validator/validate-os.js
@@ -1,17 +1,17 @@
-async function getParseItemFunctionFromEnvironment() {
-  let parseItem = null
+async function getParseListFunctionFromEnvironment() {
+  let parseList = null
   if (typeof window === 'undefined') {
     // Environment = nodeJS -> Take structured header functions from the locally installed node module
     const structuredHeaderLib = await import('structured-headers')
-    parseItem = structuredHeaderLib.default.parseItem
+    parseList = structuredHeaderLib.default.parseList
   } else {
     // Environment = browser -> Take structured header functions from the lib loaded from the CDN (see HTML)
-    parseItem = window.structuredHeader.parseItem
+    parseList = window.structuredHeader.parseList
   }
-  return parseItem
+  return parseList
 }
 
-const parseItem = await getParseItemFunctionFromEnvironment()
+const parseList = await getParseListFunctionFromEnvironment()
 
 function validateString(item) {
   if (typeof item !== 'string') {
@@ -46,29 +46,31 @@ function validate(str, paramChecks) {
   const errors = []
   const warnings = []
 
-  let item, params
+  let list
   try {
-    [item, params] = parseItem(str)
+    list = parseList(str)
   } catch (err) {
     errors.push({ msg: err.toString() })
     return { errors, warnings }
   }
 
-  const err = validateURL(item)
-  if (err) {
-    errors.push({ msg: err, path: [] })
-  }
-
-  Object.entries(paramChecks).forEach(([param, check]) => {
-    const err = check(params.get(param))
+  for (const [item, params] of list) {
+    const err = validateURL(item)
     if (err) {
-      errors.push({ msg: err, path: [param] })
+      errors.push({ msg: err, path: [] })
     }
-    params.delete(param);
-  });
 
-  for (const key of params.keys()) {
-    warnings.push({ msg: 'unknown parameter', path: [key] })
+    Object.entries(paramChecks).forEach(([param, check]) => {
+      const err = check(params.get(param))
+      if (err) {
+        errors.push({ msg: err, path: [param] })
+      }
+      params.delete(param);
+    });
+
+    for (const key of params.keys()) {
+      warnings.push({ msg: 'unknown parameter', path: [key] })
+    }
   }
 
   return { errors, warnings }
diff --git a/index.bs b/index.bs
index 447a99439b..e40fa21ef1 100644
--- a/index.bs
+++ b/index.bs
@@ -1221,19 +1221,19 @@ To <dfn>process an attributionsrc response</dfn> given a [=suitable origin=]
 1. Let |triggerHeader| be the result of [=header list/get|getting=]
     "`Attribution-Reporting-Register-Trigger`" from |response|'s
     [=response/header list=].
-1. Let |osSourceURL| be the result of
-    [=get an OS-registration URL from a header list|getting an OS-registration URL=]
+1. Let |osSourceURLs| be the result of
+    [=get OS-registration URLs from a header list|getting OS-registration URLs=]
     from |response|'s [=response/header list=] with
     "`Attribution-Reporting-Register-OS-Source`".
-1. Let |osTriggerURL| be the result of
-    [=get an OS-registration URL from a header list|getting an OS-registration URL=]
+1. Let |osTriggerURLs| be the result of
+    [=get OS-registration URLs from a header list|getting OS-registration URLs=]
     from |response|'s [=response/header list=] with
     "`Attribution-Reporting-Register-OS-Trigger`".
 1. If |eligibility| is:
     <dl class="switch">
     : "<code>[=eligibility/navigation-source=]</code>"
     :: Run the following steps:
-        1. If |sourceHeader| and |osSourceURL| are both null or both not
+        1. If |sourceHeader| and |osSourceURLs| are both null or both not
             null, return.
         1. If |sourceHeader| is not null:
             1. Let |source| be the result of running
@@ -1243,13 +1243,13 @@ To <dfn>process an attributionsrc response</dfn> given a [=suitable origin=]
                 [=current wall time=].
             1. If |source| is not null, [=process an attribution source|process=]
                 |source|.
-        1. If |osSourceURL| is not null and the user agent supports OS
-            registrations, process |osSourceURL| according to an
+        1. If |osSourceURLs| is not null and the user agent supports OS
+            registrations, process |osSourceURLs| according to an
             [=implementation-defined=] algorithm.
     : "<code>[=eligibility/event-source-or-trigger=]</code>"
     :: Run the following steps:
         1. If the number of non-null entries in «|sourceHeader|,
-            |triggerHeader|, |osSourceURL|, |osTriggerURL|» is not 1, return.
+            |triggerHeader|, |osSourceURLs|, |osTriggerURLs|» is not 1, return.
         1. If |sourceHeader| is not null:
             1. Let |source| be the result of running
                 [=parse source-registration JSON=] with |sourceHeader|,
@@ -1267,11 +1267,11 @@ To <dfn>process an attributionsrc response</dfn> given a [=suitable origin=]
                 |destinationSite|, |reportingOrigin|, |privateStateTokens|, and
                 |context|'s [=current wall time=].
             1. If |trigger| is not null, [=trigger attribution=] with |trigger|.
-        1. If |osSourceURL| is not null and the user agent supports OS
-            registrations, process |osSourceURL| according to an
+        1. If |osSourceURLs| is not null and the user agent supports OS
+            registrations, process |osSourceURLs| according to an
             [=implementation-defined=] algorithm.
-        1. If |osTriggerURL| is not null and the user agent supports OS
-            registrations, process |osTriggerURL| according to an
+        1. If |osTriggerURLs| is not null and the user agent supports OS
+            registrations, process |osTriggerURLs| according to an
             [=implementation-defined=] algorithm.
 
     </dl>
@@ -2967,14 +2967,20 @@ A user agent MAY retry this algorithm in the event that there was an error.
 
 # Cross App and Web Algorithms # {#cross-app-and-web}
 
-To <dfn noexport>get an OS-registration URL from a header list</dfn> given a
+To <dfn noexport>get OS-registration URLs from a header list</dfn> given a
 [=header list=] |headers| and a [=header name=] |name|:
 
-1. Let |value| be the result of
+1. Let |values| be the result of
     [=header list/get a structured field value|getting=] |name| from |headers|
-    with a type of "`item`".
-1. If |value| is not a [=string=], return null.
-1. Return the result of running the [=URL parser=] on |value|.
+    with a type of "`list`".
+1. If |values| is not a [=list=], return null.
+1. Let |urls| be a new [=list=].
+1. [=list/iterate|For each=] |value| of |values|:
+     1. If |value| is not a [=string=], [=iteration/continue=].
+     1. Let |url| be the result of running the [=URL parser=] on |value|.
+     1. If |url| is failure or null, [=iteration/continue=].
+     1. [=list/Append=] |url| to |urls|.
+1. Return |urls|.
 
 To <dfn>get supported registrars</dfn>: