From 17e10cfabdd459b3b42d631c8aad6c9538a9b014 Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Wed, 24 Jul 2024 09:47:18 -0400 Subject: [PATCH 1/6] Alternate B&A header mechanism to facilitate delaying response to body instead of header. --- FLEDGE_browser_bidding_and_auction_API.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/FLEDGE_browser_bidding_and_auction_API.md b/FLEDGE_browser_bidding_and_auction_API.md index 4b6c7b014..4a78c20ed 100644 --- a/FLEDGE_browser_bidding_and_auction_API.md +++ b/FLEDGE_browser_bidding_and_auction_API.md @@ -84,6 +84,14 @@ and both versions should be accepted. It should be noted that the `fetch()` request using `adAuctionHeaders` can also be used to send `auctionBlob` (e.g. in the request body) and receive the response blob (e.g. in the response body). +#### Alternate header to facilitate delaying response blobs to response body + +The aforementioned Step 3 includes the hash of the response blob in an `Ad-Auction-Result` HTTP response header, which requires that the response blob be available before the HTTP response headers are sent back to the device. If the server operator wants to instead delay inclusion of the response blob until the HTTP response body is sent back to the device, they can instead omit the `Ad-Auction-Result` HTTP header and instead: + +1. Generate a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.html) nonce on their server. +2. Instead of returning the `Ad-Auction-Result` header, return a `Ad-Auction-Result-Nonce` header passing the nonce, e.g. `Ad-Auction-Result-Nonce: 5b3e87f7-d48c-4376-908f-623f92f13740`. Like `Ad-Auction-Result`, `Ad-Auction-Result-Nonce` can accept a comma-separated list instead of a single value if desired. +3. Pass the nonce in a TBD field of the [SelectAdRequest](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L282) to the [SellerFrontEnd service](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L267). + ### Step 4: Complete auction in browser Now the auction can be completed by passing the response blob to `runAdAuction()` as part of a specially configured auction configuration: From b251ab8aca05701f1e45d305a3045b56885b33e0 Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Tue, 6 Aug 2024 15:24:24 -0400 Subject: [PATCH 2/6] mention how nonce gets back to browser behind the scenes --- FLEDGE_browser_bidding_and_auction_API.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/FLEDGE_browser_bidding_and_auction_API.md b/FLEDGE_browser_bidding_and_auction_API.md index 4a78c20ed..fec8d4f82 100644 --- a/FLEDGE_browser_bidding_and_auction_API.md +++ b/FLEDGE_browser_bidding_and_auction_API.md @@ -92,6 +92,8 @@ The aforementioned Step 3 includes the hash of the response blob in an `Ad-Aucti 2. Instead of returning the `Ad-Auction-Result` header, return a `Ad-Auction-Result-Nonce` header passing the nonce, e.g. `Ad-Auction-Result-Nonce: 5b3e87f7-d48c-4376-908f-623f92f13740`. Like `Ad-Auction-Result`, `Ad-Auction-Result-Nonce` can accept a comma-separated list instead of a single value if desired. 3. Pass the nonce in a TBD field of the [SelectAdRequest](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L282) to the [SellerFrontEnd service](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L267). +Behind the scenes, the Bidding and Auction servers will pass back the nonce to the browser which verifies that it matches nonce from the `Ad-Auction-Result-Nonce` header. + ### Step 4: Complete auction in browser Now the auction can be completed by passing the response blob to `runAdAuction()` as part of a specially configured auction configuration: @@ -474,7 +476,11 @@ Prior to compression and encryption, the AuctionResult is encoded as CBOR with t "description": "Boolean to indicate that there is no remarketing winner from the auction. AuctionResult may be ignored by the client (after decryption) if this is set to true." }, "winReportingUrls": { "$ref": "#/$defs/winReportingUrlsDef" }, - "error": { "$ref": "#/$defs/errorDef" } + "error": { "$ref": "#/$defs/errorDef" }, + "nonce": { + "type": "byte string", + "description": "32 byte UUIDv4 nonce that was passed to SelectAdRequest. Browser enforces that this matches value passed via Ad-Auction-Result-Nonce header." + } } } ``` From 8301c87f7e891b009f5ab837f0c4e5f34ac05dcf Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Mon, 30 Dec 2024 14:54:28 -0500 Subject: [PATCH 3/6] tweak to string UUIDv4 representation for easier matching --- FLEDGE_browser_bidding_and_auction_API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE_browser_bidding_and_auction_API.md b/FLEDGE_browser_bidding_and_auction_API.md index fec8d4f82..e0a711c2e 100644 --- a/FLEDGE_browser_bidding_and_auction_API.md +++ b/FLEDGE_browser_bidding_and_auction_API.md @@ -478,8 +478,8 @@ Prior to compression and encryption, the AuctionResult is encoded as CBOR with t "winReportingUrls": { "$ref": "#/$defs/winReportingUrlsDef" }, "error": { "$ref": "#/$defs/errorDef" }, "nonce": { - "type": "byte string", - "description": "32 byte UUIDv4 nonce that was passed to SelectAdRequest. Browser enforces that this matches value passed via Ad-Auction-Result-Nonce header." + "type": "string", + "description": "UUIDv4 nonce that was passed to SelectAdRequest, in standard UUIDv4 string representation: 32 lower-case hexadecimal characters with blocks of 8, 4, 4, 4, and 12 separated by dashes as per RFC4122. Browser enforces that this matches exactly the string passed via the Ad-Auction-Result-Nonce header." } } } From 74e0730352ccf3e9fd7640f545c46ca04b019fcb Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Fri, 14 Mar 2025 09:30:02 -0400 Subject: [PATCH 4/6] add more explanation/motivation --- FLEDGE_browser_bidding_and_auction_API.md | 37 ++++++++++++++++++----- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/FLEDGE_browser_bidding_and_auction_API.md b/FLEDGE_browser_bidding_and_auction_API.md index e0a711c2e..05683768c 100644 --- a/FLEDGE_browser_bidding_and_auction_API.md +++ b/FLEDGE_browser_bidding_and_auction_API.md @@ -86,13 +86,36 @@ It should be noted that the `fetch()` request using `adAuctionHeaders` can also #### Alternate header to facilitate delaying response blobs to response body -The aforementioned Step 3 includes the hash of the response blob in an `Ad-Auction-Result` HTTP response header, which requires that the response blob be available before the HTTP response headers are sent back to the device. If the server operator wants to instead delay inclusion of the response blob until the HTTP response body is sent back to the device, they can instead omit the `Ad-Auction-Result` HTTP header and instead: - -1. Generate a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.html) nonce on their server. -2. Instead of returning the `Ad-Auction-Result` header, return a `Ad-Auction-Result-Nonce` header passing the nonce, e.g. `Ad-Auction-Result-Nonce: 5b3e87f7-d48c-4376-908f-623f92f13740`. Like `Ad-Auction-Result`, `Ad-Auction-Result-Nonce` can accept a comma-separated list instead of a single value if desired. -3. Pass the nonce in a TBD field of the [SelectAdRequest](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L282) to the [SellerFrontEnd service](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L267). - -Behind the scenes, the Bidding and Auction servers will pass back the nonce to the browser which verifies that it matches nonce from the `Ad-Auction-Result-Nonce` header. +The aforementioned Step 3 includes the hash of the response blob in an +`Ad-Auction-Result` HTTP response header, which requires that the response blob +be available *before* the HTTP response headers are sent back to the device. +The server operator may want to instead delay inclusion of the response blob +until the HTTP response body is sent back to the device. If the response is +[streamed](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) back +to the device, the response blob could even come *after* other data that is +available earlier. One example of when this might be useful is if this other +data [fullfills Promises for on-device auction signals](FLEDGE.md#211-providing-signals-asynchronously) +to unblock on-device auctions so they proceed concurrently to auctions running +on B&A servers. This delaying inclusion of the response blob can be accomplished +by omitting the `Ad-Auction-Result` HTTP header and instead: + +1. Generate a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.html) nonce on + their server. +1. Instead of returning the `Ad-Auction-Result` header, return a + `Ad-Auction-Result-Nonce` header passing the nonce, e.g. + `Ad-Auction-Result-Nonce: 5b3e87f7-d48c-4376-908f-623f92f13740`. Like + `Ad-Auction-Result`, `Ad-Auction-Result-Nonce` can accept a comma-separated + list instead of a single value if desired. +1. Pass the nonce in a TBD field of the + [SelectAdRequest](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L282) + to the [SellerFrontEnd service](https://github.com/privacysandbox/bidding-auction-servers/blob/4a7accd09a7dabf891b5953e5cdbb35d038c83c6/api/bidding_auction_servers.proto#L267). + +Behind the scenes, the Bidding and Auction servers will include the nonce inside +the response blob so it's passed back to the browser which verifies that it +matches nonce from the `Ad-Auction-Result-Nonce` header. + +For information about this flow can be found +[here](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/protected_audience_auctions_mixed_mode.md#server-side-auctions). ### Step 4: Complete auction in browser From f6b7129c8055448bfd638fea89384e611c97fcc2 Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Fri, 14 Mar 2025 09:33:04 -0400 Subject: [PATCH 5/6] fix two typos --- FLEDGE_browser_bidding_and_auction_API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE_browser_bidding_and_auction_API.md b/FLEDGE_browser_bidding_and_auction_API.md index 05683768c..90bd39218 100644 --- a/FLEDGE_browser_bidding_and_auction_API.md +++ b/FLEDGE_browser_bidding_and_auction_API.md @@ -101,7 +101,7 @@ by omitting the `Ad-Auction-Result` HTTP header and instead: 1. Generate a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.html) nonce on their server. -1. Instead of returning the `Ad-Auction-Result` header, return a +1. Instead of returning the `Ad-Auction-Result` header, return an `Ad-Auction-Result-Nonce` header passing the nonce, e.g. `Ad-Auction-Result-Nonce: 5b3e87f7-d48c-4376-908f-623f92f13740`. Like `Ad-Auction-Result`, `Ad-Auction-Result-Nonce` can accept a comma-separated @@ -112,7 +112,7 @@ by omitting the `Ad-Auction-Result` HTTP header and instead: Behind the scenes, the Bidding and Auction servers will include the nonce inside the response blob so it's passed back to the browser which verifies that it -matches nonce from the `Ad-Auction-Result-Nonce` header. +matches the nonce from the `Ad-Auction-Result-Nonce` header. For information about this flow can be found [here](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/protected_audience_auctions_mixed_mode.md#server-side-auctions). From f2eb9239b780741ffb0b13d03c2912a4ae23f06a Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Fri, 14 Mar 2025 09:33:44 -0400 Subject: [PATCH 6/6] fix another typo --- FLEDGE_browser_bidding_and_auction_API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE_browser_bidding_and_auction_API.md b/FLEDGE_browser_bidding_and_auction_API.md index 90bd39218..5921058ba 100644 --- a/FLEDGE_browser_bidding_and_auction_API.md +++ b/FLEDGE_browser_bidding_and_auction_API.md @@ -114,7 +114,7 @@ Behind the scenes, the Bidding and Auction servers will include the nonce inside the response blob so it's passed back to the browser which verifies that it matches the nonce from the `Ad-Auction-Result-Nonce` header. -For information about this flow can be found +More information about this flow can be found [here](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/protected_audience_auctions_mixed_mode.md#server-side-auctions). ### Step 4: Complete auction in browser