Private Aggregation API

[Exposed=(InterestGroupScriptRunnerGlobalScope,SharedStorageWorklet),
 SecureContext]
interface PrivateAggregation {
  undefined contributeToHistogram(PAHistogramContribution contribution);
  undefined enableDebugMode(optional PADebugModeOptions options = {});
};

dictionary PAHistogramContribution {
  required bigint bucket;
  required long value;
  bigint filteringId = 0;
};

dictionary PADebugModeOptions {
  required bigint debugKey;
};

The contributeToHistogram(PAHistogramContribution contribution) method steps are:

1. If contribution["bucket"] is not contained in the range 0 to 2¹²⁸, exclusive, throw a RangeError.

2. If contribution["value"] is negative, throw a RangeError.

3. Let scopingDetails be this's scoping details.

4. Let batchingScope be the result of running scopingDetails’ get batching scope steps.

5. Let filteringIdMaxBytes be the default filtering ID max bytes.

6. If pre-specified report parameters map[batchingScope] exists:

   1. Set filteringIdMaxBytes to pre-specified report parameters map[batchingScope]'s filtering ID max bytes.

7. If contribution["filteringId"] is not contained in the range 0 to 256^{filteringIdMaxBytes}, exclusive, throw a RangeError.

8. Let entry be a new contribution cache entry with the items:

   contribution

   contribution

   batching scope

   batchingScope

   debug scope

   The result of running scopingDetails’ get debug scope steps.

9. Append entry to the contribution cache.

Ensure errors are of an appropriate type, e.g. InvalidAccessError is deprecated.

Consider accepting an array of contributions. [Issue #44]

The enableDebugMode(optional PADebugModeOptions options) method steps are:

1. Let scopingDetails be this's scoping details.

2. Let debugScope be the result of running scopingDetails’ get debug scope steps.

3. If debug scope map[debugScope] exists, throw a "DataError" DOMException.

   Note: This would occur if enableDebugMode() has already been run for this debug scope.

4. Let debugKey be null.

5. If options was given:

   1. If options["debugKey"] is not contained in the range 0 to 2⁶⁴, exclusive, throw a "DataError" DOMException.

   2. Set debugKey to options["debugKey"].

6. Let debugDetails be a new debug details with the items:

   enabled

   true

   key

   debugKey

7. Optionally, set debugDetails to a new debug details.

   Note: This allows the user agent to make debug mode unavailable globally or just for certain callers.

8. Set debug scope map[debugScope] to debugDetails.

Ensure errors are of an appropriate type, e.g. InvalidAccessError is deprecated.

class ExampleOperation {
  async run(data) {
    privateAggregation.contributeToHistogram(...)  // This is allowed.
  }
}
register('example-operation', ExampleOperation);

privateAggregation.contributeToHistogram(...)  // This would cause an error.

To get the privateAggregation given a PrivateAggregation this:

1. Let scopingDetails be this’s scoping details.

2. If scopingDetails is null, throw a "NotAllowedError" DOMException.

   Note: This indicates the API is not yet available, for example, because the initial execution of the script after loading is not complete.

   Consider improving developer ergonomics here (e.g. a way to detect this case).

3. If this’s allowed to use is false, throw an "InvalidAccessError" DOMException.

4. Return this.

Ensure errors are of an appropriate type, e.g. InvalidAccessError is deprecated.

To append an entry to the contribution cache given a contribution cache entry entry:

1. Append entry to the contribution cache.

To get a debug details given a debug scope debugScope, perform the following steps. They return a debug details.

1. If debug scope map[debugScope] exists, return debug scope map[debugScope].

2. Otherwise, return a new debug details.

To mark a debug scope complete given a debug scope debugScope and an optional debug details or null debugDetailsOverride (default null):

1. Let debugDetails be debugDetailsOverride.

2. If debug scope map[debugScope] exists:

   1. Assert: debugDetailsOverride is null.

      Note: The override can be provided if the debug details have not been set otherwise.

   2. Set debugDetails to debug scope map[debugScope].

   3. Remove debug scope map[debugScope].

   4. If debugDetails’s key is not null, assert: debugDetails’s enabled is true.

3. If debugDetails is null, set debugDetails to a new debug details.

4. For each entry of the contribution cache:

   1. If entry’s debug scope is debugScope, set entry’s debug details to debugDetails.

To determine if a report should be sent deterministically given a pre-specified report parameters preSpecifiedParams, perform the following steps. They return a boolean:

1. If preSpecifiedParams’ context ID is not null, return true.

2. If preSpecifiedParams’ filtering ID max bytes is not the default filtering ID max bytes, return true.

3. Return false.

Note: If a context ID or non-default filtering ID max bytes was specified, a report is sent, even if there are no contributions or there is insufficent budget for the requested contributions. See Protecting against leaks via the number of reports.

To process contributions for a batching scope given a batching scope batchingScope, an origin reportingOrigin, a context type contextType and a moment or null timeout:

1. Let batchEntries be a new list.

2. For each entry of the contribution cache:

   1. If entry’s batching scope is batchingScope:

      1. Assert: entry’s debug details is not null.

         Note: This asserts that the mark a debug scope complete steps were run before the process contributions for a batching scope steps.

      2. Append entry to batchEntries.

3. Let aggregationCoordinator be the default aggregation coordinator.

4. If aggregation coordinator map[batchingScope] exists:

   1. Set aggregationCoordinator to aggregation coordinator map[batchingScope].

   2. Remove aggregation coordinator map[batchingScope].

5. Let preSpecifiedParams be a new pre-specified report parameters.

6. If pre-specified report parameters map[batchingScope] exists:

   1. Set preSpecifiedParams to pre-specified report parameters map[batchingScope].

   2. Remove pre-specified report parameters map[batchingScope].

7. Let isDeterministicReport be the result of determining if a report should be sent deterministically given preSpecifiedParams.

8. If isDeterministicReport is false, assert: timeout is null.

   Note: Timeouts can only be used for deterministic reports.

9. If batchEntries is empty and isDeterministicReport is false, return.

10. Let batchedContributions be a new ordered map.

11. For each entry of batchEntries:

    1. Remove entry from the contribution cache.

    2. Let debugDetails be entry’s debug details.

    3. If batchedContributions[debugDetails] does not exist:

       1. Set batchedContributions[debugDetails] to a new list.

    4. Append entry’s contribution to batchedContributions[debugDetails].

12. If batchedContributions is empty:

    1. Let debugDetails be a new debug details.

    2. Set batchedContributions[debugDetails] to a new list.

13. For each debugDetails → contributions of batchedContributions:

    1. Perform the report creation and scheduling steps with reportingOrigin, contextType, contributions, debugDetails, aggregationCoordinator, preSpecifiedParams and timeout.

Note: These steps break up the contributions based on their debug details as each report can only have one set of metadata.

To determine if an origin is an aggregation coordinator given an origin origin, perform the following steps. They return a boolean.

1. Return whether origin is an aggregation coordinator.

To set the aggregation coordinator for a batching scope given an origin origin and a batching scope batchingScope:

1. Assert: origin is an aggregation coordinator.

2. Set aggregation coordinator map[batchingScope] to origin.

To set the pre-specified report parameters for a batching scope given a pre-specified report parameters params and a batching scope batchingScope:

1. Let contextId be params’ context ID.

2. Assert: contextId is null or contextId’s length is not larger than 64.

3. Let filteringIdMaxBytes be params’ filtering ID max bytes.

4. Assert: filteringIdMaxBytes is contained in the valid filtering ID max bytes range

5. Set pre-specified report parameters map[batchingScope] to params.

To perform the report creation and scheduling steps with an origin reportingOrigin, a context type api, a list of PAHistogramContributions contributions, a debug details debugDetails, an aggregation coordinator aggregationCoordinator, a pre-specified report parameters preSpecifiedParams and a moment or null timeout:

1. Assert: reportingOrigin is a potentially trustworthy origin.

2. Optionally, return.

   Note: This implementation-defined condition is intended to allow user agents to drop reports for a number of reasons, for example user opt-out or an origin not being enrolled.

3. Let mergedContributions be a new list.

4. For each contribution of contributions:

   1. Let hasProcessedContribution be false.

   2. For each mergedContribution of mergedContributions:

      1. If contribution and mergedContribution have both the same bucket and the same filteringId:

         1. Add contribution’s value to mergedContribution’s value.

         2. Set hasProcessedContribution to true.

         3. Break.

   3. If hasProcessedContribution is false, append contribution to mergedContributions.

5. Let truncatedContributions be a new list.

6. If mergedContributions has a size greater than maximum report contributions[api]:

   1. For each n of the range 0 to maximum report contributions[api], exclusive:

      1. Append mergedContributions[n] to truncatedContributions.

7. Otherwise, set truncatedContributions to mergedContributions.

8. Let contributionSum be 0.

9. For each contribution of truncatedContributions:

   1. Assert: contribution["value"] is non-negative.

   2. Add contribution["value"] to contributionSum.

10. Let currentWallTime be the current wall time.

11. Let sufficientBudget be the result of consuming budget if permitted given contributionSum, reportingOrigin, api and currentWallTime.

    Allow for some of the contributions to still be approved even if there isn’t enough budget for the entire report. Note that this change would require the merging step to be postponed until after budgeting and the truncation step modified to account for the later merging.

12. If sufficientBudget is false:

    1. Let isDeterministicReport be the result of determining if a report should be sent deterministically given preSpecifiedParams.

    2. If isDeterministicReport is false, return.

    3. Empty truncatedContributions.

13. Let report be the result of obtaining an aggregatable report given reportingOrigin, api, truncatedContributions, debugDetails, aggregationCoordinator, preSpecifiedParams, timeout and currentWallTime.

14. Append report to the user agent’s aggregatable report cache.

To consume budget if permitted given an integer value, an origin origin, a context type api and a moment currentTime, perform implementation-defined steps. They return a boolean, which indicates whether there is sufficient 'contribution budget' left to send the requested contribution value (or multiple contributions with a sum of values equal to value). This budget should be bound to usage over time, e.g. the contribution sum over the last 24 hours. The algorithm should assume that the contribution will be sent if and only if true is returned, i.e. it should consume the budget in that case. If value is zero, this algorithm should return true.

To obtain an aggregatable report given an origin reportingOrigin, a context type api, a list of PAHistogramContributions contributions, a debug details debugDetails, an aggregation coordinator aggregationCoordinator, a pre-specified report parameters preSpecifiedParams, a [=moment] or null timeout and a moment currentTime, perform the following steps. They return an aggregatable report.

1. Assert: reportingOrigin is a potentially trustworthy origin.

2. Let reportTime be the result of running obtain a report delivery time given currentTime and timeout.

3. Let report be a new aggregatable report with the items:

   reporting origin

   reportingOrigin

   original report time

   reportTime

   report time

   reportTime

   contributions

   contributions

   api

   api

   report ID

   The result of generating a random UUID.

   debug details

   debugDetails

   aggregation coordinator

   aggregationCoordinator

   context ID

   preSpecifiedParams’ context ID

   filtering ID max bytes

   preSpecifiedParams’ filtering ID max bytes

   queued

   false

4. Return report.

To obtain a report delivery time given a moment currentTime and a moment or null timeout, perform the following steps. They return a moment.

1. If timeout is not null:

   1. Return timeout.

2. If automation local testing mode enabled is true, return currentTime.

3. Let r be a random double between 0 (inclusive) and 1 (exclusive) with uniform probability.

4. Return currentTime + minimum report delay + r * randomized report delay.

To attempt to queue reports for sending given a list of aggregatable reports reports:

1. For each report of reports, run these steps in parallel:

   1. Run these steps, but abort when the user agent shuts down:

      1. If report’s queued value is true, return.

      2. Set report’s queued value to true.

      3. Let currentWallTime be the current wall time.

      4. If report’s report time is before currentWallTime, set report’s report time to currentWallTime plus an implementation-defined random non-negative duration.

         Note: On startup, it is possible the user agent will need to send many reports whose report times passed while the browser was closed. Adding random delay prevents temporal joining of reports.

      5. Wait until the current wall time is equal to or after report’s report time.

      6. Optionally, wait a further implementation-defined non-negative duration.

         Note: This is intended to allow user agents to optimize device resource usage and wait for the user agent to be online.

      7. Run attempt to deliver a report with report.

   2. If aborted, set report’s queued value to false.

      Note: It might be more practical to perform this step when the user agent next starts up.

To attempt to deliver a report given an aggregatable report report:

1. Let url be the result of obtaining a reporting endpoint given report’s reporting origin and report’s api.

2. Let data be the result of serializing an aggregatable report given report.

3. If data is an error, remove report from the aggregatable report cache.

   Do we need to queue this task?

4. Let request be the result of creating a report request given url and data.

5. Queue a task to fetch request with processResponse being the following steps:

   1. Let shouldRetry be an implementation-defined boolean. The value should be false if no error occurred.

   2. If shouldRetry is true:

      1. Set report’s report time to the current wall time plus an implementation-defined non-negative duration.

      2. Set report’s queued value to false.

   3. Otherwise, remove report from the aggregatable report cache.

To obtain a reporting endpoint given an origin reportingOrigin and context type api, perform the following steps. They return a URL.

1. Assert: reportingOrigin is a potentially trustworthy origin.

2. Let path be the concatenation of «".well-known/private-aggregation/report-", api».

   Register this well-known directory. [Issue #67]

3. Let base be the result on running the URL parser on the serialization of reportingOrigin.

4. Assert: base is not failure.

5. Let result be the result of running the URL parser on path with base.

6. Assert: result is not failure.

7. Return result.

To create a report request given a URL url and a byte sequence body:

1. Let request be a new request with the following properties:

   method

   "POST"

   URL

   url

   header list

   «("Content-Type", "application/json")»

   unsafe-request flag

   set

   body

   body

   client

   null

   window

   "no-window"

   service-workers mode

   "none"

   initiator

   ""

   referrer

   "no-referrer"

   mode

   "cors"

   credentials mode

   "omit"

   cache mode

   "no-store"

2. Return request.

To serialize an aggregatable report given an aggregatable report report, perform the following steps. They return a byte sequence or an error.

1. Let aggregationServicePayloads be the result of obtaining the aggregation service payloads given report.

2. If aggregationServicePayloads is an error, return aggregationServicePayloads.

3. Let data be an ordered map of the following key/value pairs:

   "aggregation_coordinator_origin"

   report’s aggregation coordinator, serialized.

   "aggregation_service_payloads"

   aggregationServicePayloads

   "shared_info"

   The result of obtaining a report’s shared info given report.

4. Let debugKey be report’s debug details's key.

5. If debugKey is not null, set data["debug_key"] to debugKey.

6. Let contextId be report’s context ID.

7. If contextId is not null, set data["context_id"] to contextId.

8. Return the byte sequence resulting from executing serialize an infra value to JSON bytes on data.

To obtain the aggregation service payloads given an aggregatable report report, perform the following steps. They return a list of maps or an error.

1. Let publicKeyTuple be the result of obtaining the public key for encryption given report’s aggregation coordinator.

2. If publicKeyTuple is an error, return publicKeyTuple.

3. Let (pkR, keyId) be publicKeyTuple.

4. Let plaintextPayload be the result of obtaining the plaintext payload given report.

5. Let sharedInfo be the result of obtaining a report’s shared info given report.

6. Let encryptedPayload be the result of encrypting the payload given plaintextPayload, pkR and sharedInfo.

7. If encryptedPayload is an error, return encryptedPayload.

8. Let aggregationServicePayloads be a new list.

9. Let aggregationServicePayload be an ordered map of the following key/value pairs:

   "key_id"

   keyId

   "payload"

   encryptedPayload, base64 encoded

10. If report’s debug details's enabled field is true:

    1. Set aggregationServicePayload[debug_cleartext_payload] to plaintextPayload, base64 encoded.

11. Append aggregationServicePayload to aggregationServicePayloads.

12. Return aggregationServicePayloads.

To obtain the public key for encryption given an aggregation coordinator aggregationCoordinator, perform the following steps. They return a tuple consisting of a public key and a string, or an error.

1. Let url be a new URL record.

2. Set url’s scheme to aggregationCoordinator’s scheme.

3. Set url’s host to aggregationCoordinator’s host.

4. Set url’s port to aggregationCoordinator’s port.

5. Set url’s path to «".well-known", "aggregation-service", "v1", "public-keys"».

6. Return an implementation-defined tuple consisting of a public key from url and a string that should uniquely identify the public key or, in the event that the user agent failed to obtain the public key from url, an error. This step may be asynchronous.

Specify this in terms of fetch. Add details about which encryption standards to use, length requirements, etc.

Note: The user agent is encouraged to enforce regular key rotation. If there are multiple keys, the user agent can independently pick a key uniformly at random for every encryption operation.

To obtain the plaintext payload given an aggregatable report report, perform the following steps. They return a byte sequence.

1. Let payloadData be a new list.

2. Let contributions be report’s contributions.

3. Let maxContributions be maximum report contributions[api].

4. Assert: contributions’ size is not greater than maxContributions.

5. While contributions’ size is less than maxContributions:

   1. Let nullContribution be a new PAHistogramContribution with the items:

      bucket

      0

      value

      0

      filteringId

      0

   2. Append nullContribution to contributions.

   Note: This padding protects against the number of contributions being leaked through the encrypted payload size, see discussion below.

6. For each contribution of report’s contributions:

   1. Let filteringIdMaxBytes be report’s filtering id max bytes.

   2. Assert: contribution["filteringId"] is contained in the range 0 to 256^{filteringIdMaxBytes}, exclusive.

   3. Let contributionData be an ordered map of the following key/value pairs:

      "bucket"

      The result of encoding an integer for the payload given contribution["bucket"] and 16.

      "value"

      The result of encoding an integer for the payload given contribution["value"] and 4.

      "id"

      The result of encoding an integer for the payload given contribution[="filteringId"] and filteringIdMaxBytes.

   4. Append contributionData to payloadData.

7. Let payload be an ordered map of the following key/value pairs:

   "data"

   payloadData

   "operation"

   "histogram"

8. Return the byte sequence resulting from CBOR encoding payload.

To encrypt the payload given a byte sequence plaintextPayload, public key pkR and a string sharedInfo, perform the following steps. They return a byte sequence or an error.

1. Let info be the result of UTF-8 encoding the concatenation of « "aggregation_service", sharedInfo ».

2. Let (kem_id, kdf_id, aead_id) be (0x0020, 0x0001, 0x0003).

   Note: The ciphersuite triple above is composed of HPKE algorithm identifiers, specifying the KEM as DHKEM(X25519, HKDF-SHA256), the KDF function as HKDF-SHA256 and the AEAD function as ChaCha20Poly1305.

3. Let (enc, hpkeContext) be the result of setting up an HPKE sender’s context by calling SetupBaseS() with a public key pkR, application-supplied information info, KEM kem_id, KDF kdf_id, and AEAD aead_id. If this operation fails, return an error.

   Note: For clarity, we explicitly passed the KEM, KDF, and AEAD identifiers to SetupBaseS() above, even though RFC9180 omits the parameters from its pseudocode.

4. Let aad be `` (an empty byte sequence).

5. Let ciphertext be the result of sealing the payload by calling ContextS.Seal() on the hpkeContext object with additional authenticated data aad and plaintext plaintextPayload. If this operation fails, return an error.

6. Let encryptedPayload be the concatenation of the byte sequences « enc, ciphertext ».

   Note: The length of the encapsulated symmetric key enc generated by our chosen KEM is exactly 32 bytes, as shown in RFC9180’s table of KEM IDs.

7. Return the byte sequence encryptedPayload.

To encode an integer for the payload given an integer intToEncode and an integer byteLength, return the representation of intToEncode as a big-endian byte sequence of length byteLength, left padding with zeroes as necessary.

To obtain a report’s shared info given an aggregatable report report, perform the following steps. They return a string.

1. Let scheduledReportTime be the duration from the UNIX epoch to report’s original report time.

2. Let sharedInfo be an ordered map of the following key/value pairs:

   "api"

   report’s api

   "report_id"

   report’s report ID

   "reporting_origin"

   The serialization of report’s reporting origin

   "scheduled_report_time"

   The number of seconds in scheduledReportTime, rounded down to the nearest number of whole seconds and serialized

   "version"

   "1.0"

3. Return the result of serializing an infra value to a json string given sharedInfo.

The remote end steps are:

1. If parameters is not a JSON-formatted Object, return a WebDriver error with error code invalid argument.

2. Let enabled be the result of getting a property named "enabled" from parameters.

3. If enabled is undefined or is not a boolean, return a WebDriver error with error code invalid argument.

4. Set automation local testing mode enabled to enabled.

5. Return success with data null.

Note: Without this, aggregatable reports would be subject to delays, making testing difficult.

partial interface InterestGroupScriptRunnerGlobalScope {
  readonly attribute PrivateAggregation privateAggregation;
};

dictionary PASignalValue {
  required DOMString baseValue;
  double scale;
  (bigint or long) offset;
};

dictionary PAExtendedHistogramContribution {
  required (PASignalValue or bigint) bucket;
  required (PASignalValue or long) value;
  bigint filteringId = 0;
};

[Exposed=InterestGroupScriptRunnerGlobalScope, SecureContext]
partial interface PrivateAggregation {
  undefined contributeToHistogramOnEvent(
      DOMString event, PAExtendedHistogramContribution contribution);
};

dictionary AuctionReportBuyersConfig {
  required bigint bucket;
  required double scale;
};

dictionary AuctionReportBuyerDebugModeConfig {
  boolean enabled = false;

  // Must only be provided if `enabled` is true.
  bigint? debugKey;
};

partial dictionary AuctionAdConfig {
  sequence<bigint> auctionReportBuyerKeys;
  record<DOMString, AuctionReportBuyersConfig> auctionReportBuyers;
  AuctionReportBuyerDebugModeConfig auctionReportBuyerDebugModeConfig;
};

The contributeToHistogramOnEvent(DOMString event, PAExtendedHistogramContribution contribution) method steps are:

1. Let scopingDetails be this's scoping details.

2. If event starts with "reserved." and « "reserved.always", "reserved.loss", "reserved.win" » does not contain event, return.

   Note: No error is thrown to allow forward compatibility if additional reserved event types are added later.

3. Let bucket be contribution["bucket"].

4. If bucket is a PASignalValue:

   1. If bucket["baseValue"] is not a valid signal base value, throw a TypeError.

   2. If bucket["offset"] is not a bigint, throw a TypeError.

5. Otherwise, if contribution["bucket"] is not contained in the range 0 to 2¹²⁸, exclusive, throw a TypeError.

   Make the error type consistent with contributeToHistogram(contribution).

6. Let value be contribution["value"].

7. If value is a PASignalValue:

   1. If value["baseValue"] is not a valid signal base value, throw a TypeError.

   2. If value["offset"] is a bigint, throw a TypeError.

8. Otherwise, if contribution["value"] is negative, throw a TypeError.

9. If contribution["filteringId"] is not contained in the range 0 to 256^{default filtering ID max bytes}, exclusive, throw a TypeError.

   Make the error types on validation issues here and above consistent with contributeToHistogram(contribution).

   Note: It is not currently possible to set a non-default filtering ID max bytes for Protected Audience.

10. Let batchingScope be null.

11. If event starts with "reserved.", set batchingScope to the result of running scopingDetails’ get batching scope steps.

    Note: Each non-reserved event will have a different batching scope that is created later.

12. Let entry be a new on event contribution cache entry with the items:

    contribution

    contribution

    batching scope

    batchingScope

    debug scope

    The result of running scopingDetails’ get debug scope steps.

    worklet function

    The worklet function that is currently being executed.

13. Let global be this's relevant global object.

14. Let auctionConfig be global’s auction config.

15. Let ig be the result of maybe obtaining an interest group given global.

16. Let cacheMap be auctionConfig’s per-bid or seller on event contribution cache.

17. If cacheMap[ig] does not exist, set cacheMap[ig] to a new on event contribution cache.

18. Let onEventContributionCache be cacheMap[ig].

19. If onEventContributionCache[event] does not exist, set onEventContributionCache[event] to a new list.

20. Append entry to onEventContributionCache[event].

Ensure errors are of an appropriate type, e.g. InvalidAccessError is deprecated.

Consider accepting an array of contributions. [Issue #44]

dictionary ProtectedAudiencePrivateAggregationConfig {
  USVString aggregationCoordinatorOrigin;
};

partial dictionary AuctionAdConfig {
  ProtectedAudiencePrivateAggregationConfig privateAggregationConfig;
};

partial dictionary AuctionAdInterestGroup {
  ProtectedAudiencePrivateAggregationConfig privateAggregationConfig;
};

17. If group["privateAggregationConfig"] exists:

    1. Let aggregationCoordinator be the result of obtaining the Private Aggregation coordinator given group["privateAggregationConfig"].

    2. If aggregationCoordinator is a DOMException, then throw aggregationCoordinator.

    3. Set interestGroup’s Private Aggregation coordinator to aggregationCoordinator.

6. Set auctionConfig’s permissions policy state to a new permissions policy state with the items:

   private aggregation enabled

   The result of determining whether global’s associated Document is allowed to use the "private-aggregation" policy-controlled feature.

31. If config["auctionReportBuyerKeys"] exists:

    1. Let interestGroupBuyers be auctionConfig’s interest group buyers.

    2. If interestGroupBuyers is null, set interestGroupBuyers to a new list.

    3. For each index of the range 0 to config["auctionReportBuyerKeys"]'s size, exclusive:

       1. Let key be config["auctionReportBuyerKeys"][index].

       2. If key is not contained in the range 0 to 2¹²⁸, exclusive, throw a TypeError.

       3. If index is equal to or greater than interestGroupBuyers’ size, continue.

          Note: Continue is used (instead of break) to match validation logic for all given buyer keys.

       4. Let origin be interestGroupBuyers[index].

       5. Set auctionConfig’s auction report buyer keys[origin] to key.

          Check behavior when an origin is repeated in interestGroupBuyers.

32. If config["auctionReportBuyers"] exists:

    1. For each reportType → reportBuyerConfig of config["auctionReportBuyers"]:

       1. If « "interestGroupCount", "bidCount", "totalGenerateBidLatency", "totalSignalsFetchLatency" » does not contain reportType, continue.

          Note: No error is thrown to allow forward compatibility if additional report types are added later.

          Should these strings be dash delimited?

       2. If reportBuyerConfig["bucket"] is not contained in the range 0 to 2¹²⁸, exclusive, throw a TypeError.

          Consider validating the case where the bucket used (after summing) is too large. Currently, the implementation appears to overflow. See protected-audience/1040.

       3. Set auctionConfig’s auction report buyers[reportType] to reportBuyerConfig.

33. Set auctionConfig’s auction report buyer debug details to a new debug details.

34. If config["auctionReportBuyerDebugModeConfig"] exists:

    1. Let debugModeConfig be config["auctionReportBuyerDebugModeConfig"].

    2. Let enabled be debugModeConfig["enabled"].

    3. Let debugKey be debugModeConfig["debugKey"].

    4. If debugKey is not null:

       1. If debugKey is not contained in the range 0 to 2⁶⁴, exclusive, throw a TypeError.

       2. If enabled is false, throw a TypeError.

    5. Set auctionConfig’s auction report buyer debug details to a new debug details with the items:

       enabled

       enabled

       key

       debugKey

35. If config["privateAggregationConfig"] exists:

    1. Let aggregationCoordinator be the result of obtaining the Private Aggregation coordinator given config["privateAggregationConfig"].

    2. If aggregationCoordinator is a DOMException, return failure.

    3. Set auctionConfig’s seller Private Aggregation coordinator to aggregationCoordinator.

Make all map indexing links (throughout the spec) where possible, i.e. matching this section.

1. Process the Private Aggregation contributions for an auction given auctionConfig and leadingBidInfo.

12. Set global’s privateAggregation's allowed to use to auctionConfig’s permissions policy state's private aggregation enabled.

13. Let debugScope be a new debug scope.

14. Set global’s privateAggregation's scoping details to a new scoping details with the items:

    get batching scope steps

    An algorithm that performs the following steps:

    1. Let origin be realm’s settings object's origin.

    2. Let ig be the result of maybe obtaining an interest group given realm’s global object.

    3. Let aggregationCoordinator be null.

    4. If ig is not null, set aggregationCoordinator to ig’s Private Aggregation coordinator.

    5. Otherwise, set aggregationCoordinator to auctionConfig’s seller Private Aggregation coordinator.

    6. If aggregationCoordinator is null, set aggregationCoordinator to the default aggregation coordinator.

    7. Return the result of running get or create a batching scope given origin, aggregationCoordinator and auctionConfig.

    get debug scope steps

    An algorithm that returns debugScope.

2. Let debugDetails be the result of get a debug details given debugScope.

3. Let ig be the result of maybe obtaining an interest group given global.

4. Let onEventContributionCache be auctionConfig’s per-bid or seller on event contribution cache[ig].

5. For each event → entries of onEventContributionCache:

   1. For each onEventEntry of entries:

      1. If onEventEntry’s debug scope is debugScope, set onEventEntry’s debug details to debugDetails.

6. Mark a debug scope complete given debugScope.

7. Set global’s auction config to auctionConfig.

2. Set global’s auction config to auctionConfig.

2. Set global’s auction config to auctionConfig.

3. Set global’s interest group to ig.

16. The length of the serialization of ig’s Private Aggregation coordinator if the field is not null.

"privateAggregationConfig"

1. If value is not a map whose keys are strings, jump to the step labeled Abort update.

2. If value["aggregationCoordinatorOrigin"] exists:

   1. If value["aggregationCoordinatorOrigin"] is not a string, jump to the step labeled Abort update.

   2. Let aggregationCoordinator be the result of obtaining the Private Aggregation coordinator given value["aggregationCoordinatorOrigin"].

   3. If aggregationCoordinator is a DOMException, jump to the step labeled Abort update.

   4. Otherwise, set ig’s Private Aggregation coordinator to aggregationCoordinator.

To process the Private Aggregation contributions for an auction given an auction config auctionConfig and a leading bid info leadingBidInfo:

1. Let winnerOrigin be null.

2. If leadingBidInfo’s leading bid is not null, set winnerOrigin to leadingBidInfo’s leading bid’s interest group’s owner.

3. For each ig → onEventContributionCache of auctionConfig’s per-bid or seller on event contribution cache:

   1. Let origin be null.

   2. If ig is null, set origin to auctionConfig’s seller.

   3. Otherwise, set origin to ig’s owner.

   4. For each event → entries of onEventContributionCache:

      1. If event is "reserved.win" or does not start with "reserved.":

         1. If origin is not winnerOrigin, return.

      2. If event is "reserved.loss" and origin is winnerOrigin, return.

      3. For each onEventEntry of entries:

         1. Let filledInContribution be the result of filling in the contribution given onEventEntry’s contribution and leadingBidInfo.

            Once protected-audience/627 is resolved, align 'filling in' logic with forDebuggingOnly.

         2. If event does not start with "reserved.":

            1. Store event, filledInContribution, onEventEntry’s debug details in the FencedFrameConfig as appropriate.

               Note: Each non-reserved event will have a different batching scope.

               Once protected-audience/616 and any successors are landed, align integration and fill in fenced frame’s report a private aggregation event.

            2. Continue.

         3. Let entry be a new contribution cache entry with the items:

            contribution

            filledInContribution

            batching scope

            onEventEntry’s batching scope

            debug scope

            onEventEntry’s debug scope

            debug details

            onEventEntry’s debug details

         4. Append entry to the contribution cache.

4. Let sellerBatchingScope be the result of getting or creating a batching scope given auctionConfig’s seller, auctionConfig’s seller Private Aggregation coordinator, and auctionConfig.

5. Let auctionReportBuyersDebugScope be a new debug scope.

6. For each reportType → reportBuyerConfig of auctionConfig’s auction report buyers:

   1. For each buyerOrigin → buyerOffset of auctionConfig’s auction report buyer keys:

      1. Let bucket be the sum of buyerOffset and reportBuyerConfig’s bucket.

         Handle overflow here or in validation. See protected-audience/1040.

      2. Let value be the result (a double) of switching on reportType:

         "interestGroupCount"

         The number of interest groups in the user agent's interest group set whose owner is buyerOrigin.

         "bidCount"

         The number of valid bids generated by interest groups whose owner is buyerOrigin.

         "totalGenerateBidLatency"

         The sum of execution time in milliseconds for all generateBid() calls in the auction for interest groups whose owner is buyerOrigin.

         "totalSignalsFetchLatency"

         The total time spent fetching trusted buyer signals in milliseconds, or 0 if the interest group didn’t fetch any trusted signals.

         None of the above values

         Assert: false

         Note: This enum value is validated in validate and convert auction ad config.

         More formally spec the values here.

      3. Set value to the result of multiplying reportBuyerConfig’s scale with value.

      4. Set value to the maximum of 0.0 and value.

      5. Set value to the result of converting value to an integer by truncating its fractional part.

      6. Set value to the minimum of value and 2³¹−1.

      7. Let contribution be a new PAHistogramContribution with the items:

         bucket

         bucket

         value

         value

         filteringId

         0

         Consider allowing the filtering ID to be set here.

      8. For each ig of the user agent's interest group set whose owner is buyerOrigin:

         1. If seller capabilities don’t allow this reporting, continue.

            Align behavior with seller capabilities handling once protected-audience/966 is resolved.

         2. Let entry be a new contribution cache entry with the items:

            contribution

            contribution

            batching scope

            sellerBatchingScope

            debug scope

            auctionReportBuyersDebugScope

         3. Append entry to the contribution cache.

7. Mark a debug scope complete given auctionReportBuyersDebugScope and auctionConfig’s auction report buyer debug details.

8. For each (origin, aggregationCoordinator) → batchingScope of auctionConfig’s batching scope map:

   1. Process contributions for a batching scope given batchingScope, origin, "protected-audience" and null.

Verify interaction with component auctions.

Use [=map/For each=] where possible.

To get or create a batching scope given an origin origin, an aggregation coordinator aggregationCoordinator and an auction config auctionConfig, perform the following steps. They return a batching scope.

1. Let batchingScopeMap be auctionConfig’s batching scope map.

2. Let tuple be (origin, aggregationCoordinator).

3. If batchingScopeMap[tuple] does not exist:

   1. Set batchingScopeMap[tuple] to a new batching scope.

   2. If aggregationCoordinator is not null, set the aggregation coordinator for a batching scope given aggregationCoordinator and batchingScopeMap[tuple].

4. Return batchingScopeMap[tuple].

To fill in the contribution given a PAExtendedHistogramContribution contribution and a leading bid info leadingBidInfo, perform the following steps. They return a PAHistogramContribution.

1. Let bucket be contribution["bucket"].

2. If bucket is a PASignalValue, set bucket to the result of filling in the signal value given bucket, 2¹²⁸−1 and leadingBidInfo.

3. Let value be contribution["value"].

4. If value is a PASignalValue, set value to the result of filling in the signal value given value, 2³¹−1 and leadingBidInfo.

5. Let filledInContribution be a new PAHistogramContribution with the items:

   bucket

   bucket

   value

   value

   filteringId

   contribution["filteringId"]

6. Return filledInContribution.

To fill in the signal value given a PASignalValue value, an integer maxAllowed and a leading bid info leadingBidInfo, perform the following steps. They return an integer.

1. Assert: value["baseValue"] is a valid signal base value.

2. Let returnValue be the result of determining a signal’s numeric value given value["baseValue"] and leadingBidInfo.

3. If value["scale"] exists, set returnValue to the result of multiplying value["scale"] with returnValue.

4. Set returnValue to the result of converting returnValue to an integer by truncating its fractional part.

5. If value["offset"] exists, set returnValue to the result of adding returnValue to value["offset"].

6. Clamp returnValue to the range 0 to maxAllowed, inclusive, and return the result.

To determine a signal’s numeric value given a signal base value signalBaseValue and a leading bid info leadingBidInfo, perform the following steps. They return a double.

1. If signalBaseValue is "winning-bid":

   1. If leadingBidInfo’s leading bid is null, return 0.

   2. Otherwise, return leadingBidInfo’s leading bid’s bid.

2. If signalBaseValue is "highest-scoring-other-bid":

   1. If leadingBidInfo’s highest scoring other bid is null, return 0.

   2. Otherwise, return leadingBidInfo’s highest scoring other bid’s bid.

3. If signalBaseValue is "script-run-time":

   1. Return the number of milliseconds of CPU time that the calling function (e.g. generateBid()) took to run.

4. If signalBaseValue is "signals-fetch-time": Switch on the associated worklet function:

   generate-bid

   Return the number of milliseconds it took for the trusted bidding signals fetch to complete, or 0 if no fetch was made.

   score-ad

   Return the number of milliseconds it took for the trusted scoring signals fetch to complete or 0 if no fetch was made.

   report-result

   report-win

   Return 0.

   Consider disallowing this in the latter two worklet functions.

5. If signalBaseValue is "bid-reject-reason":

   1. If the bid did not succeed purely because it didn’t meet the required k-anonymity threshold, return 8.

   2. Let bidRejectReason be "not-available".

   3. If the seller provided a reject reason, set bidRejectReason to that value.

   4. If bidRejectReason is:

      "not-available"

      Return 0.

      "invalid-bid"

      Return 1.

      "bid-below-auction-floor"

      Return 2.

      "pending-approval-by-exchange"

      Return 3.

      "disapproved-by-exchange"

      Return 4.

      "blocked-by-publisher"

      Return 5.

      "language-exclusions"

      Return 6.

      "category-exclusions"

      Return 7.

      None of the above values

      Assert: false

      Note: this enum value is validated in scoreAd().

      Verify this once protected-audience/627 is resolved.

      Once protected-audience/594 lands, update this mapping to align.

      Verify handling when the bid was not rejected.

      Consider disallowing this from reportWin() and reportResult().

To maybe obtain an interest group given an InterestGroupScriptRunnerGlobalScope global, perform the following steps. They return an interest group or null:

1. Switch on global’s type:

   InterestGroupBiddingScriptRunnerGlobalScope

   Return global’s interest group.

   InterestGroupScoringScriptRunnerGlobalScope

   Return null.

   InterestGroupReportingScriptRunnerGlobalScope

   Return global’s interest group.

To obtain the Private Aggregation coordinator given a ProtectedAudiencePrivateAggregationConfig config, perform the following steps. They return an aggregation coordinator, null or a DOMException.

1. If config["aggregationCoordinatorOrigin"] does not exist, return null.

2. Return the result of obtaining the Private Aggregation coordinator given config["aggregationCoordinatorOrigin"].

To obtain the Private Aggregation coordinator given a USVString originString, perform the following steps. They return an aggregation coordinator or a DOMException.

1. Let url be the result of running the URL parser on originString.

2. If url is failure or null, return a new DOMException with name "SyntaxError".

   Consider throwing an error if the path is not empty.

3. Let origin be url’s origin.

4. If the result of determining if an origin is an aggregation coordinator given origin is false, return a new DOMException with name "DataError".

5. Return origin.