Shared Storage API

1. Introduction

This section is not normative.

In order to prevent cross-site user tracking, browsers are partitioning all forms of storage by top-frame site; see Client-Side Storage Partitioning. But, there are many legitimate use cases currently relying on unpartitioned storage.

This document introduces a new storage API that is intentionally not partitioned by top-frame site (though still partitioned by context origin), in order to serve a number of the use cases needing unpartitioned storage. To limit cross-site reidentification of users, data in Shared Storage may only be read in a restricted environment, called a worklet, and any output from the worklet is in the form of a fenced frame or a private aggregation report. Over time, there may be additional ouput gates included in the standard.

a.example randomly assigns users to groups in a way that is consistent cross-site.

Inside an a.example iframe:

function generateSeed() { … }
await window.sharedStorage.worklet.addModule('experiment.js');

// Only write a cross-site seed to a.example’s storage if there isn’t one yet.
window.sharedStorage.set('seed', generateSeed(), { ignoreIfPresent: true });

let fencedFrameConfig = await window.sharedStorage.selectURL(
  'select-url-for-experiment',
  [
    {url: "blob:https://a.example/123…", reportingMetadata: {"click": "https://report.example/1..."}},
    {url: "blob:https://b.example/abc…", reportingMetadata: {"click": "https://report.example/a..."}},
    {url: "blob:https://c.example/789…"}
  ],
  { data: { name: 'experimentA' } }
);

// Assumes that the fenced frame 'my-fenced-frame' has already been attached.
document.getElementById('my-fenced-frame').config = fencedFrameConfig;

inside the experiment.js worklet script:

class SelectURLOperation {
  hash(experimentName, seed) { … }

  async run(data, urls) {
    const seed = await this.sharedStorage.get('seed');
    return hash(data.name, seed) % urls.length;
  }
}
register('select-url-for-experiment', SelectURLOperation);

2. The `SharedStorageWorklet` Interface

The SharedStorageWorklet object allows developers to supply module scripts to process Shared Storage data and then output the result through one or more of the output gates. Currently there are two output gates, the private aggregation output gate and the URL-selection output gate.

[Exposed=(Window)]
interface SharedStorageWorklet : Worklet {
};

Each SharedStorageWorklet has an associated boolean module added, initialized to false.

Because adding multiple module scripts via addModule() for the same SharedStorageWorklet would give the caller the ability to store data from Shared Storage in global variables defined in the module scripts and then exfiltrate the data through later call(s) to addModule(), each SharedStorageWorklet can only call addModule() once. The module added boolean makes it possible to enforce this restriction.

When addModule() is called for a worklet, it will run check if module added and update status, and if the result is true, abort the remaining steps in the addModule() call, as detailed in the § 2.1 Monkey Patch for Worklets.

To check if module added and update status for a SharedStorageWorklet worklet, run the following steps:

If worklet’s module added is true, return true.
Otherwise, set Worklet's module added to true.
Return false.

2.1. Monkey Patch for Worklets

This specification will make some modifications to the Worklet standard to accommodate the needs of Shared Storage.

In particular, the addModule() method steps for Worklet will need to be prepended with the following step:

If Worklet has an associated boolean module added, and the result of running check if module added and update status on Worklet is true, return a promise rejected with a TypeError.

Add additional monkey patch pieces for out-of-process worklets.

2.2. The `SharedStorageWorkletGlobalScope`

The SharedStorageWorklet's worklet global scope type is SharedStorageWorkletGlobalScope.

[Exposed=SharedStorageWorklet, Global=SharedStorageWorklet]
interface SharedStorageWorkletGlobalScope : WorkletGlobalScope {
  undefined register(DOMString name,
                     SharedStorageOperationConstructor operationCtor);
};

callback SharedStorageOperationConstructor =
  SharedStorageOperation(optional SharedStorageRunOperationMethodOptions options);

[Exposed=SharedStorageWorklet]
interface SharedStorageOperation {
};

dictionary SharedStorageRunOperationMethodOptions {
  object data;
  boolean resolveToConfig = false;
  boolean keepAlive = false;
};

Each SharedStorageWorkletGlobalScope has an associated environment settings object outside settings, which is the associated SharedStorageWorklet's relevant settings object.

The SharedStorageWorkletGlobalScope's module map's module scripts should each define and register one or more SharedStorageOperations.

Each SharedStorageWorkletGlobalScope also has an associated operation map, which is a map, initially empty, of strings (denoting operation names) to functions.

Currently each SharedStorageOperation registered via register() must be one of the following two types:

SharedStorageRunOperation
SharedStorageSelectURLOperation

The SharedStorageRunOperation is designed to work with output gates that do not need a return value, like the private aggregation service. A SharedStorageRunOperation performs an async operation and returns a promise that resolves to undefined.

A SharedStorageSelectURLOperation is an SharedStorageOperation that takes in a list of SharedStorageUrlWithMetadatas (i.e. dictionaries containing strings representing URLs each wrapped with optional metadata), performs an async operation, and then returns a promise to a long integer index specifying which of these URLs should be selected.

[Exposed=SharedStorageWorklet]
interface SharedStorageRunOperation : SharedStorageOperation {
  Promise<undefined> run(object data);
};

[Exposed=SharedStorageWorklet]
interface SharedStorageSelectURLOperation : SharedStorageOperation {
  Promise<long> run(object data,
                    FrozenArray<SharedStorageUrlWithMetadata> urls);
};

2.3. Registering a Worklet

The register(name, operationCtor) method steps are:

If name is missing or empty, throw a TypeError.
Let operationMap be this SharedStorageWorkletGlobalScope's operation map.
If operationMap contains an entry with key name, throw a TypeError.
If operationCtor is missing, throw a TypeError.
If the result of running IsConstructor() with operationCtor is false, throw a TypeError.
Let prototype be the result of running operationCtor’s [[GetPrototypeOf]]() method.
If prototype is not an object, throw a TypeError.
Let run be the result of running GetMethod() with prototype and "run".
If run is undefined, throw a TypeError.
Set the value of operationMap[name] to run.

3. Shared Storage’s Backend

The Shared Storage API will integrate into the Storage API as below, via registering a new storage endpoint.

3.1. Monkey Patch for the Storage Model

This standard will add a new storage type "shared" to the Storage Model.

A user agent holds a shared storage shed for storage endpoints of type "shared".

This standard will also register a storage endpoint of type "shared" with storage identifier "sharedStorage" and quota 5⁴ * 2¹⁶ bytes (i.e. 39.0625 mebibytes).

This quota is calculated from the current implementation. Consider bringing the current implementation in line with the spec for storage endpoints "localStorage" and "sessionStorage", i.e. 5 * 2²⁰ bytes. For example, decreasing the per-origin entry limit from 10,000 to 1,280 would achieve this.

A shared storage shed is a map of origins to storage shelves. It is initially empty.

Note: Unlike storage sheds, whose keys are storage keys, shared storage sheds use origins as keys directly. Shared storage will be intentionally excluded from client-side storage partitioning.

For each storage shelf in a shared storage shed, the storage shelf's bucket map currently has only a single key of "default".

A user agent's shared storage shed holds all shared storage data.

To obtain a shared storage shelf, given a shared storage shed shed and an environment settings object environment, run these steps:

Let origin be environment’s origin.
If origin is an opaque origin, then return failure.
If the user has disabled shared storage, then return failure.
If shed[origin] does not exist, then set shed[origin] to the result of running create a shared storage shelf with type "shared".
Return shed[origin].

To create a shared storage shelf, run these steps:

Let shelf be a new storage shelf.
Set shelf’s bucket map["default"] to the result of running create a shared storage bucket.
Return shelf.

A shared storage bucket is a storage bucket in one of a shared storage shed's shelves.

To create a shared storage bucket, run these steps:

Let endpoint be the storage endpoint with storage identifier "sharedStorage".
Let bucket be a new shared storage bucket.
Set bucket’s bottle map["sharedStorage"] to a new storage bottle whose quota is endpoint’s quota.
Return bucket.

Note: Currently, a shared storage bucket's bottle map has size 1, since there is only one storage endpoint registered with type "shared".

To obtain a shared storage bottle map, given an environment settings object environment, run these steps:

Let shed be the user agent's shared storage shed.
Let shelf be the result of running obtain a shared storage shelf with shed and environment.
If shelf is failure, then return failure.
Let bucket be shelf’s bucket map["default"].
Let bottle be bucket’s bottle map["sharedStorage"].
Let proxyMap be a new storage proxy map whose backing map is bottle’s map.
Append proxyMap to bottle’s proxy map reference set.
Return proxyMap.

3.2. The Shared Storage Database

A browsing context has an associated shared storage database, which provides methods to store, retrieve, delete, clear, and purge expired data, and additional methods as below. The data in the database take the form of entries.

Each shared storage database has a shared storage database queue, which is the result of starting a new parallel queue. This queue is used to run each of the shared storage database's methods when calls to them are initiated from that browsing context.

Each entry consists of a key and a value struct.

An entry's key is a string.

User agents may specify the maximum length of a key.

Since keys are used to organize and efficiently retrieve entries, keys must appear at most once in any given shared storage database.

An entry's value struct is a struct composed of string value and DOMHighResTimeStamp last updated (from the Unix Epoch).

User agents may specify the maximum length of a value.

User agents may specify a default entry lifetime, the default duration between when an entry is stored and when it expires. If the user agent specifies a default entry lifetime, then it should have a timer periodically purge expired entries from the database.

3.3. The Database Algorithms

To store an entry in the database, given a shared storage database queue queue, an environment settings object environment, a key key, and a value value, run the following steps on queue:

Let databaseMap be the result of running obtain a shared storage bottle map for environment.
If databaseMap is failure, then return false.
Let valueStruct be a new value struct.
Set valueStruct’s value to value.
Let currentTime be the current wall time.
Set valueStruct’s last updated to currentTime.
Set databaseMap[key] to valueStruct.
Return true.

To retrieve an entry from the database, given a shared storage database queue queue, an environment settings object environment, and a key key, run the following steps on queue:

Let databaseMap be the result of running obtain a shared storage bottle map for environment.
If databaseMap is failure, then return failure.
If databaseMap does not contain key, return undefined.
Let valueStruct be the result of running Get on databaseMap with key.
If the result of running determine whether an entry is expired with valueStruct is true, return undefined.
Return valueStruct’s value.

To delete an entry from the database, given a shared storage database queue queue, an environment settings object environment, and a key key, run the following steps on queue:

Let databaseMap be the result of running obtain a shared storage bottle map for environment.
If databaseMap is failure, then return false.
Remove databaseMap[key].
Return true.

To clear all entries in the database, given a shared storage database queue queue and an environment settings object environment, run the following steps on queue:

Let databaseMap be the result of running obtain a shared storage bottle map for environment.
If databaseMap is failure, then return false.
Run Clear on databaseMap.
Return true.

To retrieve all entries from the database, given a shared storage database queue queue and an environment settings object environment, run the following steps on queue:

Let databaseMap be the result of running obtain a shared storage bottle map for environment.
If databaseMap is failure, then return failure.
Return the result of running getting the values on databaseMap.

To count entries in the database, given a shared storage database queue queue and an environment settings object environment, run the following steps on queue:

Let databaseMap be the result of running obtain a shared storage bottle map for environment.
If databaseMap is failure, then return failure.
Return databaseMap’s size.

To purge expired entries from the database, given a shared storage database queue queue and an environment settings object environment, run the following steps on queue:

Let databaseMap be the result of running obtain a shared storage bottle map for environment.
If databaseMap is failure, then return false.
For each key key in databaseMap:
1. Let valueStruct be the result of running Get on databaseMap with key.
2. If the result of running determine whether an entry is expired with valueStruct is true, Remove databaseMap[key].
Return true.

To determine whether an entry is expired, given a value struct valueStruct, run the following steps:

Let lastUpdated be valueStruct’s last updated.
Let lifetime be user agent's default entry lifetime.
Let expiration be the sum of lastUpdated and lifetime.
Let currentTime be the current wall time.
If expiration is less than or equal to currentTime, return true.
Otherwise, return false.

4. The `SharedStorage` Interface

The SharedStorage interface is the base for derived interfaces WindowSharedStorage and WorkletSharedStorage, which are exposed to the Window and the SharedStorageWorklet, respectively.

Methods that allow the setting and/or deleting of data are exposed to both the Window and the SharedStorageWorklet and hence are declared in the base SharedStorage interface, although their implementations may vary depending on their environment. This makes it possible to modify the data in Shared Storage from multiple contexts.

Meanwhile, methods for running SharedStorageOperations, along with the worklet attribute which is used to call addModule(), are declared in WindowSharedStorage and exposed to the Window only, as these are the means by which the Window interacts with the SharedStorageWorklet.

On the other hand, methods for getting data from the shared storage database are declared in WorkletSharedStorage and exposed to the SharedStorageWorklet only, in order to carefully control the flow of data read from the database.

[Exposed=(Window,SharedStorageWorklet)]
interface SharedStorage {
  Promise<any> set(DOMString key,
                   DOMString value,
                   optional SharedStorageSetMethodOptions options = {});
  Promise<any> append(DOMString key,
                      DOMString value);
  Promise<any> delete(DOMString key);
  Promise<any> clear();
};

dictionary SharedStorageSetMethodOptions {
  boolean ignoreIfPresent = false;
};

4.1. The `WindowSharedStorage` interface

The WindowSharedStorage interface is as follows.

typedef (USVString or FencedFrameConfig) SharedStorageResponse;

[Exposed=(Window)]
interface WindowSharedStorage : SharedStorage {
  Promise<any> run(DOMString name,
                   optional SharedStorageRunOperationMethodOptions options = {});
  Promise<SharedStorageResponse> selectURL(DOMString name,
                               FrozenArray<SharedStorageUrlWithMetadata> urls,
                               optional SharedStorageRunOperationMethodOptions options = {});

  readonly attribute SharedStorageWorklet worklet;
};

4.1.1. Window Setter/Deleter Methods

The set(key, value, options) method steps are:

Let promise be a new promise.
Let context be WindowSharedStorage's Window's browsing context.
Assert that context is not null.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
If value’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. If options["ignoreIfPresent"] is true and the result of running retrieve an entry from the database with queue, environment, and key is not undefined, resolve promise with undefined and abort these steps.
2. Run store an entry in the database with queue, environment, key, and value.
3. Resolve promise with undefined.
Return promise.

The append(key, value) method steps are:

Let promise be a new promise.
Let context be WindowSharedStorage's Window's browsing context.
Assert that context is not null.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
If value’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Let currentValue be the result of running retrieve an entry from the database with queue, environment, and key.
2. If currentValue is failure, resolve promise with undefined and abort these steps.
3. If currentValue is not undefined:
  1. Let list be a new list.
  2. Append currentValue to list.
  3. Append value to list.
  4. Set value to the result of running concatenate on list.
4. Run store an entry in the database with queue, environment, key, and value.
5. Resolve promise with undefined.
Return promise.

The delete(key) method steps are:

Let promise be a new promise.
Let context be WindowSharedStorage's Window's browsing context.
Assert that context is not null.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Run delete an entry from the database with queue, environment, and key.
2. Resolve promise with undefined.
Return promise.

The clear() method steps are:

Let promise be a new promise.
Let context be WindowSharedStorage's Window's browsing context.
Assert that context is not null.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Run clear all entries in the database with queue and environment.
2. Resolve promise with undefined.
Return promise.

4.1.2. `SharedStorageUrlWithMetadata` and Reporting

A SharedStorageUrlWithMetadata object is a dictionary containing a string representing a URL and, optionally, a reportingMetadata object.

dictionary SharedStorageUrlWithMetadata {
  required USVString url;
  object reportingMetadata;
};

If a SharedStorageUrlWithMetadata object contains a non-empty reportingMetadata object in the form of a dictionary whose keys are eventTypes and whose values are strings that parse to valid URLs, then these eventType-URL pairs will be registered for later access within any fenced frame that loads the SharedStorageResponse resulting from this selectURL() call.

Inside a fenced frame with eventType-URL pairs that have been registered through selectURL() with reportingMetadata objects, if fence.reportEvent() is called on a FenceEvent with a destination containing "shared-storage-select-url" and that FenceEvent's corresponding eventType is triggered, then the FenceEvent's eventData will be sent as a beacon to the registered URL for that eventType.

To validate reporting metadata, given an object reportingMetadata, run the following steps:

If reportingMetadata is empty, return true.
If reportingMetadata is not a dictionary, return false.
For each eventType -> urlString of reportingMetadata, if the result of running get the canonical URL string if valid with urlString is undefined, return false.
Return true.

To get the canonical URL string if valid, given a string urlString, run the following steps:

Let url be the result of running a URL parser on urlString.
If url is not a valid URL, return undefined.
Otherwise, return the result of running a URL serializer on url.

To register reporting metadata, given an object reportingMetadata and a "fenced frame config struct" fencedFrameConfigStruct, run the following steps:

If reportingMetadata is empty, return.
Assert that reportingMetadata is a dictionary.
Let reportingUrlMap be an empty map.
For each eventType -> urlString of reportingMetadata:
1. Let url be the result of running a URL parser on urlString.
2. Assert that url is a valid URL.
3. Set reportingUrlMap[eventType] to url.
Store reportingUrlMap inside a "fenced frame reporter" class associated with fencedFrameConfigStruct. Both of these still need to be added to the draft Fenced Frame specification.

4.1.3. Entropy Budgets

Because bits of entropy can leak via selectURL(), the user agent will need to maintain budgets to limit these leaks.

4.1.3.1. Navigation Entropy Budget

If a user activates a fenced frame whose FencedFrameConfig was generated by selectURL() and thereby initiates a top-frame navigation, this will reveal to the landing page that its URL was selected, which is a leak in entropy bits of up to logarithm base 2 of the number of input URLs for the call to selectURL(). To mitigate this, a user agent will set a per-calling origin navigation entropy allowance.

A calling origin for selectURL() is the origin of an environment that makes a selectURL() call.

A navigation entropy allowance is a maximum allowance of entropy bits that are permitted to leak via fenced frames initiating top-frame navigations during a given navigation budget epoch for a given calling calling origin. This allowance is defined by the user agent and is calling origin-agnostic.

A user agent will define a fixed predetermined duration navigation budget lifetime.

An navigation budget epoch is any interval of time whose duration is the navigation budget lifetime.

To keep track of how this navigation entropy allowance is used, the user agent uses a shared storage navigation budget table, which is a map of calling origins to navigation entropy ledgers.

An navigation entropy ledger is a list of bit debits.

A bit debit is a struct containing a double bits, indicating a value in entropy bits, along with a DOMHighResTimeStamp timestamp (from the Unix Epoch).

Bit debits whose timestamps precede the start of the current navigation budget epoch are said to be expired.

When a leak occurs, its value in entropy bits is calculated and stored for that calling origin, along with the current time as a timestamp, together as a bit debit in the shared storage navigation budget table.

A calling origin's remaining navigation budget is the navigation entropy allowance minus any bit debits whose timestamps are within the current navigation budget epoch.

selectURL()'s argument "urls" is its input URL list.

When an calling origin has insufficient remaining navigation budget, selectURL() will return a SharedStorageResponse (i.e. either a FencedFrameConfig or an opaque URL) for the url in the SharedStorageUrlWithMetadata at the default index in its input URL list.

The default index for a call to selectURL() is implementation-defined in such a way that it is independent from the result of the associated SharedStorageSelectURLOperation's "run" method.

The default index could be defined to be 0.

In this case, whenever the SharedStorageSelectURLOperation's "run" method encounters an error, or whenever there is insufficient remaining navigation budget, the "run" method would return 0, and hence selectURL() would return a SharedStorageResponse for the first url in its input URL list.

The default index could be defined to be input URL list's size minus 1.

In this case, whenever the SharedStorageSelectURLOperation's "run" method encounters an error, or whenever there is insufficient remaining navigation budget, selectURL() would return a SharedStorageResponse for the last url in its input URL list.

To , given a calling calling origin origin, run the following steps:

If origin is opaque, return undefined.
Let maxBits be the user agent's navigation entropy allowance.
If the user agent's shared storage navigation budget table does not contain origin, then return maxBits.
Otherwise, let ledger be user agent's shared storage navigation budget table[origin].
Let debitSum be 0.
For each item bitDebit in ledger, do the following steps:
1. Let debit be bitDebit’s bits.
2. If the result of running check whether a bit debit is expired with bitDebit is false, then increment debitSum by debit.
Return maxBits minus debitSum.

To check whether a bit debit is expired, given a bit debit bitDebit, run the following steps:

Let epochLength be the user agent's navigation budget lifetime.
Let currentTime be the current wall time.
Let threshold be currentTime minus epochLength.
If bitDebit’s timestamp is less than threshold, return true.
Otherwise, return false.

A bit debit will need to be charged to the shared storage navigation budget table for each top-frame navigation initiated by a fenced frame whose FencedFrameConfig was generated via selectURL(), as this can leak cross-site data. Since the bits to charge is calculated during the call to selectURL() but only actually recorded in the shared storage navigation budget table if and when the resulting fenced frame initiates a top-frame navigation, the bits must be stored as a pending shared storage budget debit in the corresponding FencedFrameConfig until this time.

Between beginning navigation and ending navigation, a user agent will perform the charge shared storage navigation budget algorithm.

The "fenced frame config struct" and its boolean has navigated have not yet been added to the draft Fenced Frame specification. Some form of them will be added, although their names are subject to bikeshedding. Fix the names when they are added.

To during a with navigable navigable and Document sourceDocument, run the following steps:

If navigable is not a traversable navigable, return.
Let node be sourceDocument’s node navigable.
While node is not null:
1. If node has a "fenced frame config struct":
  1. Let origin be node’s active document's origin.
  2. Let pendingBits be node’s "fenced frame config struct"'s pending shared storage budget debit.
  3. If pendingBits is greater than 0 and if "fenced frame config struct"'s has navigated is false, run the following steps:
    1. Let ledger be user agent's shared storage navigation budget table[origin].
    2. Let bitDebit be a new bit debit.
    3. Set bitDebit’s bits to pendingBits.
    4. Let currentTime be the current wall time.
    5. Set bitDebit’s timestamp to currentTime.
    6. Append bitDebit to ledger.
    7. Set node’s "fenced frame config struct"'s has navigated to true.
2. Set node to node’s parent.

4.1.3.2. Reporting Entropy Budget

Likewise, each time a call to fence.reportEvent() from a fenced frame originating via selectURL() whose destination contains "shared-storage-select-url" and whose eventType is triggered, there is a leak of up to logarithm base 2 of the number of main input URLs entropy bits. The user agent will need to set a per-page load reporting entropy allowance to restrict the information leaked, with page load referring to a top-level traversable's lifecycle.

A reporting entropy allowance is a maximum allowance of entropy bits that are permitted to leak via fence.reportEvent() during a given page load. This allowance is defined by the user agent.

Each top-level traversable will have a new double shared storage reporting budget associated to it which will be initialized with the value of user agent's reporting entropy allowance upon top-level traversable's creation.

When fence.reportEvent() is called with a destination containing "shared-storage-select-url", it will be necessary to charge shared storage reporting budget as below.

To determine reporting budget to charge, given a Document sourceDocument, run the following steps:

Let debitSum be 0.
Let node be sourceDocument’s node navigable.
While node is not null:
1. If node has a "fenced frame config struct":
  1. Let pendingBits be node’s "fenced frame config struct"'s pending shared storage budget debit.
  2. If pendingBits is greater than 0 and if "fenced frame config struct"'s has reported is false, increment debitSum by pendingBits
2. Set node to node’s parent.
Return debitSum.

The "fenced frame config struct" and its boolean has reported have not yet been added to the draft Fenced Frame specification. Some form of them will be added, although their names are subject to bikeshedding. Fix the names when they are added.

To charge shared storage reporting budget given a Document sourceDocument, run the following steps:

Let toCharge be the result of running determine reporting budget to charge with sourceDocument.
Let node be sourceDocument’s node navigable.
Let topNode be the result of running get the top-level traversable for node.
If topNode’s shared storage reporting budget is less than toCharge, return false.
While node is not null:
1. If node has a "fenced frame config struct" and if node’s "fenced frame config struct"'s pending shared storage budget debit is greater than 0, set node’s "fenced frame config struct"'s has reported to true.
2. Set node to node’s parent.
Decrement topNode’s shared storage reporting budget by toCharge.
Return true.

A user agent may wish to set a timer to periodically purge expired bit debits from all navigation entropy ledgers, as the expired bit debits will no longer be needed.

To , run the following steps:

For each origin -> ledger of user agent's shared storage navigation budget table:
1. For each bitDebit in ledger, if the result of running check whether a bit debit is expired with bitDebit is true, remove bitDebit from ledger.

4.1.4. Run Operation Methods

The run(name, options) method steps are:

Let promise be a new promise.
If addModule() has not yet been called, return a promise rejected with a TypeError.
Let outsideSettings be worklet's relevant settings object.
Let agent be the result of obtaining a worklet agent given outsideSettings.
Run the following steps in agent:
1. If worklet's module map is not empty:
  1. Let operationMap be this SharedStorageWorkletGlobalScope's operation map.
  2. If operationMap contains name:
    1. Let operation be operationMap[name].
    2. If options contains data:
      1. Let argumentsList be a new list.
      2. Append data to argumentsList.
      3. Call operation with argumentsList.
    3. Otherwise, call operation without any arguments list.
2. Resolve promise with undefined.
Return promise.
If options["keepAlive"] is false, upon fulfillment of promise or upon rejection of promise, run terminate a worklet global scope with the associated SharedStorageWorkletGlobalScope.

The selectURL(name, urls, options) method steps are:

Let resultPromise be a new promise.
If urls is empty or exceeds the maximum allowed length, return a promise rejected with a TypeError.
Let urlList be an empty list.
For each urlWithMetadata in urls:
1. If urlWithMetadata has no field "url", return a promise rejected with a TypeError.
2. Otherwise, let urlString be urlWithMetadata["url"].
3. Let serializedUrl be the result of running get the canonical URL string if valid with urlString.
4. If serializedUrl is undefined, return a promise rejected with a TypeError.
5. Otherwise, append serializedUrl to urlList.
6. If urlWithMetadata has field "reportingMetadata":
  1. Let reportingMetadata be urlWithMetadata["reportingMetadata"].
  2. If the result of running validate reporting metadata with reportingMetadata is false, reject promise with a TypeError and abort these steps.
If addModule() has not yet been called, reject promise with a TypeError and abort these steps.
Let fencedFrameConfigStruct be a "fenced frame config struct". Add correct struct name as well as linking when Fenced Frame API updates their draft spec to include it.

The "fenced frame config struct" and the following "obtain a FencedFrameConfig from a fenced frame config struct" algorithm have not yet been added to the draft Fenced Frame specification. Some form of them will be added, although their names are subject to bikeshedding.

If options["resolveToConfig"] is true, resolve resultPromise with the result of running "obtain a FencedFrameConfig from a fenced frame config struct" with fencedFrameConfigStruct. Add correct struct and algorithms names as well as linking when Fenced Frame API updates their draft spec to include it.
Othewise, resolve resultPromise to fencedFrameConfigStruct’s "urn uuid". Add correct struct name and urn:uuid name as well as linking when Fenced Frame API updates their draft spec to include it.
Let indexPromise be a new promise.
Let outsideSettings be worklet's relevant settings object.
Let agent be the result of obtaining a worklet agent given outsideSettings.
Run the following steps in agent:
1. Let index be default index.
2. If worklet's module map is not empty:
  1. Let operationMap be the associated SharedStorageWorkletGlobalScope's operation map.
  2. If operationMap contains name:
    1. Let operation be operationMap[name].
    2. Let argumentsList be a new list.
    3. Append urlList to argumentsList.
    4. If options contains data, append data to argumentsList.
    5. Let operationResult be the result of running Call on operation with argumentsList.
    6. If operationResult has any error(s), then reject indexPromise with a TypeError.
    7. Otherwise:
      1. Set index to the result of casting operationResult to an unsigned long. If this throws an exception, catch it and reject indexPromise with a TypeError.
      2. Otherwise, if index is greater than urlList.size, then reject indexPromise with a TypeError.
3. If indexPromise has not been rejected, resolve indexPromise with index.
4. Upon fulfillment of indexPromise, perform the following steps:
  1. Let resultIndex be the numerical value of indexPromise.
  2. Let context be WindowSharedStorage's Window's browsing context.
  3. Assert that context is not null.
  4. Let origin be context’s active document's origin.
  5. Assert that origin is not opaque.
  6. Let remainingBudget be the result of running determine remaining navigation budget with origin.
  7. Assert that remainingBudget is not undefined.
  8. Let listSize be urlList’s size.
  9. Let pendingBits be the logarithm base 2 of listSize.
  10. If pendingBits is greather than remainingBudget, set resultIndex to default index.
  11. Set fencedFrameConfigStruct’s pending shared storage budget debit to pendingBits.
  12. Set fencedFrameConfigStruct’s url to urlList[resultIndex].
  13. Let resultURLWithMetadata be urls[resultIndex].
  14. If resultURLWithMetadata has field "reportingMetadata", run register reporting metadata with resultURLWithMetadata["reportingMetadata"].
5. Upon rejection of indexPromise, set fencedFrameConfigStruct’s url to urlList[default index].
Return resultPromise.
If options["keepAlive"] is false, upon fulfillment of resultPromise or upon rejection of resultPromise, run terminate a worklet global scope with the associated SharedStorageWorkletGlobalScope.

4.2. The `WorkletSharedStorage` interface

The WorkletSharedStorage interface is as follows.

[Exposed=(SharedStorageWorklet)]
interface WorkletSharedStorage : SharedStorage {
  Promise<DOMString> get(DOMString key);
  Promise<unsigned long> length();
  Promise<double> remainingBudget();

  async iterable<DOMString, DOMString>;
};

4.2.1. Worklet Setter/Deleter Methods

The set(key, value, options) method steps are:

Let promise be a new promise.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Assert that context is not null.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
If value’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. If options["ignoreIfPresent"] is true:
  1. Let currentValue be the result of running retrieve an entry from the database with queue, environment, and key.
  2. If currentValue is failure, reject promise with a TypeError and abort these steps.
  3. If currentValue is not undefined, resolve promise with undefined and abort these steps.
2. If the result of running store an entry in the database with queue, environment, key, and value is false, reject promise with a TypeError.
3. Otherwise, resolve promise with undefined.
Return promise.

The append(key, value) method steps are:

Let promise be a new promise.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Assert that context is not null.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
If value’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Let currentValue be the result of running retrieve an entry from the database with queue, environment, and key.
2. If currentValue is failure, reject promise with a TypeError and abort these steps.
3. If currentValue is not undefined:
  1. Let list be a new list.
  2. Append currentValue to list.
  3. Append value to list.
  4. Set value to the result of running concatenate on list.
4. If the result of running store an entry in the database with queue, environment, key, and value is false, reject promise with a TypeError.
5. Otherwise, resolve promise with undefined.
Return promise.

The delete(key) method steps are:

Let promise be a new promise.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Assert that context is not null.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. If the result of running delete an entry from the database with queue, environment, and key is false, reject promise with a TypeError.
2. Otherwise, resolve promise with undefined.
Return promise.

The clear() method steps are:

Let promise be a new promise.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Assert that context is not null.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. If the result of running clear all entries in the database with queue and environment is false, reject promise with a TypeError.
2. Otherwise, resolve promise with undefined.
Return promise.

4.2.2. Getter Methods

The get(key) method steps are:

Let promise be a new promise.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Assert that context is not null.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Let value be the result of running retrieve an entry from the database with queue, environment, and key.
2. If value is failure, reject promise with a TypeError.
3. Otherwise, if value is undefined, resolve promise with undefined.
4. Otherwise, resolve promise with value.
Return promise.

The length() method steps are:

Let promise be a new promise.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Let numEntries be the result of running count entries in the database with queue and environment.
2. If numEntries is failure, reject promise with a TypeError.
3. Otherwise, resolve promise with numEntries.
Return promise.

The remainingBudget() method steps are:

Let promise be a new promise.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Assert that context is not null.
Let origin be context’s active document's origin.
Assert that origin is not opaque.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Let remainingBudget be the result of running determine remaining navigation budget with origin.
2. Assert that remainingBudget is not undefined.
3. Resolve promise with remainingBudget.
Return promise.

4.2.3. Iteration

Each WorkletSharedStorage async iterator instance has a queue pending entries of entries, initially empty.

Each WorkletSharedStorage async iterator instance also has a boolean error, initially false.

The asynchronous iterator initialization steps and get the next iteration result algorithms defined below correspond to those referred to as the asynchronous iterator initialization steps and get the next iteration result algorithms in the Web IDL Standard.

The asynchronous iterator initialization steps for a WorkletSharedStorage async iterator iterator are:

Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
Assert that context is not null.
Let promise be a new promise.
Let environment be context’s active window's relevant settings object.
Let queue be context’s associated shared storage database queue.
Enqueue the following steps on queue:
1. Let entries be the result of running retrieve all entries from the database with queue and environment.
2. If entries is failure, reject promise with a TypeError.
3. Otherwise, resolve promise with entries.
Upon fulfillment of promise, run the following:
1. Let promiseEntries be the value of promise.
2. For each entry entry in promiseEntries, enqueue entry in iterator’s pending entries.
Upon rejection of promise, set iterator’s error to true.

Toget the next iteration result, given a WorkletSharedStorage's async iterator iterator, run the following steps:

Let promise be a new promise.
Enqueue the following steps:
1. If iterator’s error is true, return a promise rejected with a TypeError.
2. If iterator’s pending entries is empty:
  1. Create an object doneObject.
  2. Resolve promise with doneObject and abort these steps.
3. Otherwise, let entry be the result of dequeueing from iterator’s pending entries.
4. Resolve promise with entry.
Return promise.

5. Privacy Considerations

The Shared Storage API attempts to provide the ability to use cross-site data for a range of use cases in a way that better protects user privacy than the use of third-party cookies. Shared Storage’s main privacy safeguard is that read access of the data stored in its storage may only occur within an embedder’s SharedStorageWorklet. Well-defined limits restrict output of data from the SharedStorageWorklet to a minimum.

In particular, an embedder can select a URL from a short list of URLs based on data in their shared storage and then display the result in a fenced frame. The embedder will not be able to know which URL was chosen except through specifc mechanisms that will be better-mitigated in the longer term. Currently, a few bits of entropy can leak each time that the user clicks on the fenced frame to initiate a top-frame navigation and/or the fenced frame calls the fence.reportEvent() API.

An embedder is also able to send aggregatable reports through the Private Aggregation Service, which adds noise in order to achieve differential privacy, uses a time delay to send reports, imposes limits on the number of reports sent, and processes the reports into aggregate data so that individual privacy is protected.

Shared Storage API

Abstract

Status of this document

1. Introduction

2. The `SharedStorageWorklet` Interface

2.1. Monkey Patch for Worklets

2.2. The `SharedStorageWorkletGlobalScope`

2.3. Registering a Worklet

3. Shared Storage’s Backend

3.1. Monkey Patch for the Storage Model

3.2. The Shared Storage Database

3.3. The Database Algorithms

4. The `SharedStorage` Interface

4.1. The `WindowSharedStorage` interface

4.1.1. Window Setter/Deleter Methods

4.1.2. `SharedStorageUrlWithMetadata` and Reporting

4.1.3. Entropy Budgets

4.1.3.1. Navigation Entropy Budget

4.1.3.2. Reporting Entropy Budget

4.1.4. Run Operation Methods

4.2. The `WorkletSharedStorage` interface

4.2.1. Worklet Setter/Deleter Methods

4.2.2. Getter Methods

4.2.3. Iteration

5. Privacy Considerations

Conformance

Document conventions

Conformant Algorithms

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

Issues Index

Shared Storage API

Abstract

Status of this document

1. Introduction

2. The SharedStorageWorklet Interface

2.1. Monkey Patch for Worklets

2.2. The SharedStorageWorkletGlobalScope

2.3. Registering a Worklet

3. Shared Storage’s Backend

3.1. Monkey Patch for the Storage Model

3.2. The Shared Storage Database

3.3. The Database Algorithms

4. The SharedStorage Interface

4.1. The WindowSharedStorage interface

4.1.1. Window Setter/Deleter Methods

4.1.2. SharedStorageUrlWithMetadata and Reporting

4.1.3. Entropy Budgets

4.1.3.1. Navigation Entropy Budget

4.1.3.2. Reporting Entropy Budget

4.1.4. Run Operation Methods

4.2. The WorkletSharedStorage interface

4.2.1. Worklet Setter/Deleter Methods

4.2.2. Getter Methods

4.2.3. Iteration

5. Privacy Considerations

Conformance

Document conventions

Conformant Algorithms

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

Issues Index

2. The `SharedStorageWorklet` Interface

2.2. The `SharedStorageWorkletGlobalScope`

4. The `SharedStorage` Interface

4.1. The `WindowSharedStorage` interface

4.1.2. `SharedStorageUrlWithMetadata` and Reporting

4.2. The `WorkletSharedStorage` interface