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

@@ -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:

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
   {

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 }

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>: