Private Aggregation API

[Exposed=(InterestGroupScriptRunnerGlobalScope,SharedStorageWorklet),
 SecureContext]
interface PrivateAggregation {
  undefined contributeToHistogram(PAHistogramContribution contribution);
  undefined contributeToHistogramOnEvent(DOMString event,
                                         record<DOMString, any> 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. Let validationResult be the result of validating a histogram contribution given contribution and this’s scoping details.

2. If validationResult is an exception, throw validationResult.

3. Assert: validationResult is a contribution cache entry.

4. Append validationResult to the contribution cache.

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

The contributeToHistogramOnEvent(event, contribution) method steps are:

1. Let defaultProcessingResult be the result of running this’s should perform default contributeToHistogramOnEvent() processing given this, event and contribution.

2. If defaultProcessingResult is an exception, throw defaultProcessingResult.

3. If defaultProcessingResult is false, return.

4. Set contribution to the result of converting contribution’s JavaScript value to the IDL type PAHistogramContribution.

   Note: This throws a TypeError if contribution is not compatible.

5. Let validationResult be the result of validating a histogram contribution given contribution and this’s scoping details.

6. If validationResult is an exception, throw validationResult.

7. Assert: validationResult is a contribution cache entry.

8. If event does not start with "reserved.", throw a TypeError.

9. Let unprefixedEvent be the code unit substring from "reserved."'s length to event’s length within event.

10. If unprefixedEvent is any of the internal error events:

    1. Let maybeContributionCacheEntry’s error event be unprefixedEvent.

    2. Append maybeContributionCacheEntry to the contribution cache.

Note: For forward compatibility, we do not throw an error for unrecognized events that start with "reserved.".

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 and a context type api, 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. Let effectiveMaxContributions be the result of determining the max contributions with api and preSpecifiedParams’ max contributions.

4. Let defaultMaxContributions be default maxContributions by API[api].

5. If effectiveMaxContributions is not defaultMaxContributions, return true.

6. Return false.

Note: It is sometimes necessary to send a 'null report' to conceal the fact that there were no contributions. For instance, it’s possible that budget, which is cross-site data in its own right, was insufficient for the requested contributions. Alternatively, the caller might have chosen to make no contributions after reading cross-site data. In these kinds of scenarios, the absence of a report could reveal cross-site data to the reporting endpoint. 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:

Note: Embedding APIs are expected to set timeout to null if a report isn’t deterministic or if the timeout was already reached, i.e. if it caused this call to be triggered. (A timeout always has to be set for deterministic reports.)

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 and contextType.

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, set batchedContributions[debugDetails] to a new pending contributions.

    4. If entry’s error event is null:

       1. Append entry’s contribution to batchedContributions[debugDetails]'s unconditional contributions.

    5. Otherwise:

       1. Let conditionalContributions be batchedContributions[debugDetails]'s conditional contributions.

       2. If conditionalContributions[errorEvent] does not exist, set conditionalContributions[errorEvent] to a new list.

       3. Append entry’s contribution to conditionalContributions[errorEvent].

12. If batchedContributions is empty:

    1. Let debugDetails be a new debug details.

    2. Set batchedContributions[debugDetails] to a new pending contributions.

13. For each debugDetails → pendingContributions of batchedContributions:

    1. Perform the report creation and scheduling steps with reportingOrigin, contextType, pendingContributions, 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 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.

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. Let maxContributions be params’ max contributions.

6. Assert: maxContributions is null or greater than zero.

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

To validate a histogram contribution given a PAHistogramContribution contribution and a scoping details scopingDetails, perform the following steps. They return a contribution cache entry or an exception.

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

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

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

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

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

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

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

7. Return a new contribution cache entry with the items:

   contribution

   contribution

   batching scope

   batchingScope

   debug scope

   The result of running scopingDetails’ get debug scope steps.

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

To perform the report creation and scheduling steps with an origin reportingOrigin, a context type api, a pending contributions pendingContributions, 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, an origin not being enrolled or a limit on pending reports being reached.

3. Let currentWallTime be the current wall time.

4. Let allUnmergedContributions be the result of compiling all unmerged contributions, given reportingOrigin, api, pendingContributions, preSpecifiedParams, timeout and currentWallTime.

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

6. Let effectiveMaxContributions be the result of determining the max contributions with api and preSpecifiedParams’ max contributions.

7. Let keptMergeKeys be a new set.

8. For each contribution of allUnmergedContributions:

   1. Let mergeKey be contribution’s merge key.

   2. If keptMergeKeys’ size is effectiveMaxContributions and keptMergeKeys does not contain mergeKey, continue.

   3. Otherwise, append mergeKey to keptMergeKeys.

9. Remove all items that have a merge key that is not contained in keptMergeKeys from allUnmergedContributions.

10. Let finalBudgetResults be the result of querying the budget given allUnmergedContributions, reportingOrigin, api, currentWallTime and true.

11. Assert: finalBudgetResults’ size equals allUnmergedContributions’ size.

12. For each i of the range 0 to finalBudgetResults’ size, exclusive:

    1. If finalBudgetResults[i] is false, set allUnmergedContributions[i]'s value to 0.

13. Remove all items from allUnmergedContributions that have a value of 0.

14. Let mergedContributionsMap be a new ordered map.

15. For each contribution of allUnmergedContributions:

    1. Let mergeKey be contribution’s merge key.

    2. If mergedContributionsMap[mergeKey] exists, add contribution’s value to mergedContributionsMap[mergeKey]'s value.

    3. Otherwise, set mergedContributionsMap[mergeKey] to contribution.

16. Let mergedContributions be the mergedContributionsMap’s values.

17. Assert: mergedContributions has a size less than or equal to effectiveMaxContributions,

18. If mergedContributions is empty and isDeterministicReport is false, return.

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

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

To compile all unmerged contributions given an origin reportingOrigin, a context type api, a pending contributions pendingContributions, a pre-specified report parameters preSpecifiedParams, a moment or null timeout, and a moment currentWallTime, perform the following steps. They return a list of PAHistogramContributions.

1. Let wasTimeoutReached be the boolean indicating whether both isDeterministicReport is true and timeout is null.

   Update the timeout being sent from Shared Storage to align.

2. Record the internal error event result given pendingContributions, "contribution-timeout-reached" and wasTimeoutReached.

3. Let provisionalBudgetResults be the result of querying the budget given pendingContributions’ unconditional contributions, reportingOrigin, api, currentWallTime and false.

4. Assert: provisionalBudgetResults’ size equals pendingContributions’ unconditional contributions' size.

5. For each i of the range 0 to provisionalBudgetResults’ size, exclusive:

   1. If provisionalBudgetResults[i] is false, set pendingContributions’ unconditional contributions[i]'s value to 0.

6. Remove all items from pendingContributions’ unconditional contributions that have a value of 0.

7. Let insufficientBudget be a boolean indicating whether any value in provisionalBudgetResults is false.

8. Record the internal error event result given pendingContributions, "insufficient-budget" and insufficientBudget.

9. Let pendingReportLimitReached be a boolean determined by an implementation-defined algorithm.

   Note: This is intended to indicate when a limit on the number of reports simultaneously pending on a budget query was reached (but not exceeded).

10. Record the internal error event result given pendingContributions, "pending-report-limit-reached" and pendingReportLimitReached.

11. Let isEmptyAndWouldBeDropped be a boolean indicating whether both isDeterministicReport is false and pendingContributions’ unconditional contributions is empty.

12. Record the internal error event result given pendingContributions, "empty-report-dropped" and isEmptyAndWouldBeDropped.

13. Let effectiveMaxContributions be the result of determining the max contributions with api and preSpecifiedParams’ max contributions.

14. Let tooManyContributions be false.

15. Let provisionallyApprovedMergeKeys be a new set.

16. For each contribution of pendingContributions’ unconditional contributions:

    1. Let mergeKey be contribution’s merge key.

    2. If provisionallyApprovedMergeKeys’ size is effectiveMaxContributions and provisionallyApprovedMergeKeys does not contain mergeKey, set tooManyContributions to true.

    3. Otherwise, append mergeKey to provisionallyApprovedMergeKeys.

17. Record the internal error event result given pendingContributions, "too-many-contributions" and tooManyContributions.

18. Remove all items that have a merge key that is not contained in provisionallyApprovedMergeKeys from pendingContributions’ unconditional contributions.

19. Let reportSuccess be the boolean indicating whether none of the following are true: isEmptyAndWouldBeDropped, tooManyContributions, insufficientBudget, pendingReportLimitReached.

20. Record the internal error event result given pendingContributions, "report-success" and reportSuccess.

21. Let allUnmergedContributions be a new list.

22. For each errorEvent of all error events:

    1. If pendingContributions’ conditional contributions[errorEvent] does not exist, continue.

    2. Assert: pendingContributions’ triggered error events contains errorEvent or errorEvent is "already triggered external error".

       Note: When an internal error event is determined to not be triggered, its conditional contributions are removed by record the internal error event result

    3. Extend allUnmergedContributions with pendingContributions’ conditional contributions[errorEvent].

23. Extend allUnmergedContributions with pendingContributions’ unconditional contributions.

    Note: Unconditional contributions come last to prioritize successful measurement of errors.

24. Return allUnmergedContributions.

Each PAHistogramContribution contribution has a merge key that is the following tuple: (contribution’s bucket, contribution’s filteringId).

Note: Two PAHistogramContributions for the same report can be merged if and only if they have the same merge key.

To query the budget given a list of PAHistogramContributions contributions, an origin origin, a context type api and a moment currentTime and a boolean consumeIfPermitted, perform the following steps. They return a list of booleans with the same size as contributions.

1. Let resultForEachContribution be a new list of booleans.

2. Let approvedValueSum be 0.

3. For each contribution of contributions:

   1. Let valueToRequest be approvedValueSum + contribution’s value.

      Note: This ensures that the result for each contribution takes into acccount any earlier approved contributions from this call (even if consumeIfPermitted is false).

   2. Let sufficientBudget be a boolean determined by an implementation-defined algorithm given valueToRequest, origin, api and currentTime. This algorithm should bound budget to usage over time, e.g. the contribution sum over the last 24 hours.

   3. If sufficientBudget, add contribution’s value to approvedValueSum.

   4. Append sufficientBudget to resultForEachContribution.

      Note: the ith element in the return value indicates whether there is enough budget left to send contributions[i]'s value.

4. If consumeIfPermitted, consume budget using an implementation-defined algorithm given approvedValueSum, origin, api and currentTime.

5. Return resultForEachContribution.

To record the internal error event result given a pending contributions pendingContributions, an internal error event errorEvent and a boolean wasTriggered, perform the following steps:

1. If wasTriggered, append errorEvent to pendingContributions’ triggered error events.

2. Otherwise, remove pendingContributions’ conditional contributions[errorEvent].

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

   max contributions

   The result of determining the max contributions with api and preSpecifiedParams’ max contributions.

   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 determine the max contributions given a context type api and a positive integer or null maxContributions, perform the following steps. They return a positive integer.

1. If maxContributions is null, return default maxContributions by API[api].

2. If maxContributions is greater than maximum maxContributions, return maximum maxContributions.

3. Return maxContributions.

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 report’s max contributions.

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 given session, URL variables and parameters 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.