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-level traversable 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-level traversable 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(urls, data) {
    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.

typedef (USVString or FencedFrameConfig) SharedStorageResponse;

enum SharedStorageDataOrigin { "context-origin", "script-origin" };

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

Each SharedStorageWorklet has an associated boolean addModule initiated, initialized to false.

Each SharedStorageWorklet has an associated SharedStorageDataOrigin data origin, initialized to "context-origin".

Each SharedStorageWorklet has an associated boolean has cross-origin data origin, 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 addModule initiated boolean makes it possible to enforce this restriction.

When addModule() is called for a worklet, it will run check if addModule is allowed and update state, and if the result is "DisallowedDueToNonPreferenceError", or if the result is "DisallowedDueToPreferenceError" and the worklet’s has cross-origin data origin is false, it will cause addModule() to fail, as detailed in the § 2.2.6 Monkey Patch for addModule().

To check if user preference setting allows access to shared storage given an environment settings object environment and an origin origin, run the following step:

Using values available in environment and origin as needed, perform an implementation-defined algorithm to return either true or false.

To determine whether shared storage is allowed by context, given an environment settings object environment, an origin origin, and a boolean allowedInOpaqueOriginContext, run these steps:

If environment is not a secure context, then return false.
If allowedInOpaqueOriginContext is false and environment’s origin is an opaque origin, then return false.
If origin is an opaque origin, then return false.
Let globalObject be the current realm's global object.
Assert: globalObject is a Window or a SharedStorageWorkletGlobalScope.
If globalObject is a Window, and if the result of running Is feature enabled in document for origin? on "shared-storage", globalObject’s associated document, and origin returns false, then return false.
If the result of running obtain a site with origin is not enrolled, then return false.
Return true.

Here are the scenarios where the algorithms determine whether shared storage is allowed by context and check if user preference setting allows access to shared storage are used:

For each method under § 4.1.1 Window Setter/Deleter Methods, environment is the current context, and origin is environment’s origin.
For creating a worklet, environment is the environment settings object associated with the Window that created the worklet, and origin is the module script url’s origin.
For running operations on a worklet (from a Window), and for each method under § 4.3.1 Worklet Setter/Deleter Methods (from SharedStorageWorkletGlobalScope), environment is the environment settings object associated with the Window that created the worklet, and origin is the worklet’s global scopes[0]'s realm's settings object's origin.
For § 7.4 Shared Storage Fetch-Related Algorithms, environment is the request’s window, and origin is the request’s current URL's origin.
For § 7.4 Shared Storage Fetch-Related Algorithms, for createWorklet() called with a cross-origin worklet script using the dataOrigin option with value "script-origin" (which would result in a worklet where has cross-origin data origin is true), and for selectURL() and run() that operate on a worklet where has cross-origin data origin is true, allowedInOpaqueOriginContext is true. For other methods, allowedInOpaqueOriginContext is false.

To check if addModule is allowed and update state given a SharedStorageWorklet worklet and a URL moduleURLRecord, run the following steps:

If worklet’s addModule initiated is true, return "DisallowedDueToNonPreferenceError".
Set worklet’s addModule initiated to true.
Let workletDataOrigin be the current settings object's origin.
If worklet’s data origin is "script-origin", set workletDataOrigin to moduleURLRecord’s origin.
Let hasCrossOriginDataOrigin be false.
If workletDataOrigin and the current settings object's origin are not same origin, then set hasCrossOriginDataOrigin to true.
Let allowedInOpaqueOriginContext be hasCrossOriginDataOrigin.
If the result of running determine whether shared storage is allowed by context given the current settings object, workletDataOrigin, and allowedInOpaqueOriginContext is false, return "DisallowedDueToNonPreferenceError".
Set worklet’s has cross-origin data origin to hasCrossOriginDataOrigin.
If the result of running check if user preference setting allows access to shared storage given the current settings object and workletDataOrigin is false, return "DisallowedDueToPreferenceError".
Return "Allowed".

Moreover, each SharedStorageWorklet's list of global scopes, initially empty, can contain at most one instance of its worklet global scope type, the SharedStorageWorkletGlobalScope.

2.1. Run Operation Methods on `SharedStorageWorklet`

To get the select-url result index, given SharedStorageWorklet worklet, DOMString operationName, list of SharedStorageUrlWithMetadatas urlList, and SharedStorageRunOperationMethodOptions options:

Let promise be a new promise.
Let window be worklet’s relevant settings object.
Assert: window is a Window.
If window’s browsing context is null, then return a promise rejected with a TypeError.
If window’s associated document is not fully active, return a promise rejected with a TypeError.
Return promise, and immediately obtain a worklet agent given window and run the rest of these steps in that agent:
1. Assert: worklet’s global scopes's size is 1.
2. Assert: worklet’s module map is not empty.
3. Let globalScope be this's global scopes[0].
4. Let operationMap be globalScope’s operation map.
5. If operationMap does not contain operationName, then queue a global task on the DOM manipulation task source, given window, to reject promise with a TypeError, and abort these steps.
  
  Note: This could happen if register() was never called with operationName.
6. Let operation be operationMap[operationName].
7. Assert: operation’s associated realm is this's relevant realm.
8. Let argumentsList be the list « urlList ».
9. If options contains data, append data to argumentsList.
10. Let index be the result of invoking operation with argumentsList.
11. If an exception was thrown, then queue a global task on the DOM manipulation task source, given window, to reject promise with a TypeError, and abort these steps.
  
  Note: This indicates that either operationCtor’s run() method encounters an error (where operationCtor is the parameter in register()), or the result index is a non-integer value, which violates the selectURL() protocol, and we don’t know which url should be selected.
12. If index is greater than urlList’s size, then queue a global task on the DOM manipulation task source, given window, to reject promise with a TypeError, and abort these steps.
  
  Note: The result index is beyond the input urls' size. This violates the selectURL() protocol, and we don’t know which url should be selected.
13. Queue a global task on the DOM manipulation task source, given window, to resolve promise with index.

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

Let resultPromise be a new promise.
If this's addModule initiated is false, then return a promise rejected with a TypeError.
Let window be this's relevant settings object.
Assert: window is a Window.
Let context be window’s browsing context.
If context is null, then return a promise rejected with a TypeError.
Let document be context’s active document.
Assert: this's global scopes's size is 1.
Let globalScope be this's global scopes[0].
Let workletDataOrigin be globalScope’s realm's settings object's origin.
If the result of running Is feature enabled in document for origin? on "shared-storage-select-url", document, and workletDataOrigin returns false, return a promise rejected with a TypeError.
If this's global scopes is empty, then return a promise rejected with a TypeError.

Note: This can happen if either selectURL() or selectURL() is called before addModule().
If the result of running check whether addModule is finished for globalScope is false, return a promise rejected with a TypeError.
If urls is empty or if urls’s size is greater than 8, return a promise rejected with a TypeError.

Note: 8 is chosen here so that each call of selectURL() can leak at most log2(8) = 3 bits of information when the result fenced frame is clicked. It’s not a lot of information per-call.
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 resultPromise with a TypeError and abort these steps.
Let fencedFrameConfigMapping be window’s associated document's node navigable's traversable navigable's fenced frame config mapping.
Let pendingConfig be a new fenced frame config.
Let urn be the result of running store a pending config on fencedFrameConfigMapping with pendingConfig.
If urn is failure, then return a promise rejected with a TypeError.
Let environment be window’s relevant settings object.
Let allowedInOpaqueOriginContext be this's has cross-origin data origin.
If the result of running determine whether shared storage is allowed by context given environment, workletDataOrigin, and allowedInOpaqueOriginContext is false, return a promise rejected with a TypeError.
If the result of running check if user preference setting allows access to shared storage given environment and workletDataOrigin is false:
1. If this's has cross-origin data origin is false, return a promise rejected with a TypeError.
If options["resolveToConfig"] is true, resolve resultPromise with pendingConfig.
Otherwise, resolve resultPromise with urn.
Let indexPromise be the result of running get the select-url result index, given this, name, urlList, and options.
Upon fulfillment of indexPromise with resultIndex, perform the following steps:
1. Let site be the result of running obtain a site with document’s origin.
2. Let remainingBudget be the result of running determine remaining navigation budget with environment and site.
3. Let pendingBits be the logarithm base 2 of urlList’s size.
4. If pendingBits is greather than remainingBudget, set resultIndex to default index.
5. Let finalConfig be a new fenced frame config.
6. Set finalConfig’s mapped url to urlList[resultIndex].
7. Set finalConfig’s a "pending shared storage budget debit" field to pendingBits.
8. Finalize a pending config on fencedFrameConfigMapping with urn and finalConfig.
9. Let resultURLWithMetadata be urls[resultIndex].
10. If resultURLWithMetadata has field "reportingMetadata", run register reporting metadata with resultURLWithMetadata["reportingMetadata"].
11. If options["keepAlive"] is false, run terminate a worklet global scope with this.
Upon rejection of indexPromise, perform the following steps:
1. Let finalConfig be a new fenced frame config.
2. Set finalConfig’s mapped url to urlList[default index].
3. Finalize a pending config on fencedFrameConfigMapping with urn and finalConfig.
4. If options["keepAlive"] is false, run terminate a worklet global scope with this.
Return resultPromise.

The run(name, options) method steps are:

Let promise be a new promise.
If this's addModule initiated is false, then return a promise rejected with a TypeError.
Let window be this's relevant settings object.
Assert: window is a Window.
If this's global scopes is empty, then return a promise rejected with a TypeError.
Assert: this's global scopes's size is 1.
Let globalScope be this's global scopes[0].
If the result of running check whether addModule is finished for globalScope is false, return a promise rejected with a TypeError.
Let workletDataOrigin be globalScope’s realm's settings object's origin.
Let allowedInOpaqueOriginContext be this's has cross-origin data origin.
If the result of running determine whether shared storage is allowed by context given window, workletDataOrigin, and allowedInOpaqueOriginContext is false, reject promise with a TypeError.
If the result of running check if user preference setting allows access to shared storage given window and workletDataOrigin is false:
1. If this's has cross-origin data origin is false, reject promise with a TypeError.
2. Else, resolve promise with undefined.
3. Return promise.
Return promise, and immediately obtaining a worklet agent given window and run the rest of these steps in that agent:

Note: The promise’s resolution should be before and not depend on the execution inside SharedStorageWorkletGlobalScope. This is because shared storage is a type of unpartitioned storage, and a SharedStorageWorkletGlobalScope can have access to cross-site data, which shouldn’t be leaked via run() (via its success/error result).
1. Queue a global task on the DOM manipulation task source, given window, to resolve promise with undefined.
2. If this's module map is not empty:
  1. Let operationMap be this's SharedStorageWorkletGlobalScope's operation map.
  2. If operationMap contains name:
    1. Let operation be operationMap[name].
    2. Assert: operation’s associated realm is this's relevant realm.
    3. If options contains data:
      1. Let argumentsList be a new list.
      2. Append data to argumentsList.
      3. Invoke operation with argumentsList.
    4. Otherwise, invoke operation without any arguments list.
3. If options["keepAlive"] is false:
  1. Wait for operation to finish running, if applicable.
  2. Run terminate a worklet global scope with this.

2.2. Monkey Patch for Worklets

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

2.2.1. Monkey Patch for set up a worklet environment settings object

The set up a worklet environment settings object algorithm will need to include an additional parameter: Worklet worklet. The step that defines the settingsObject’s origin should be modified as follows:

Let settingsObject be a new environment settings object whose algorithms are defined as follows:

......

The origin
1. Let workletGlobalScope be the global object of realmExecutionContext’s Realm component.
2. If workletGlobalScope is not SharedStorageWorkletGlobalScope, return origin.
3. Assert that worklet is a SharedStorageWorklet.
4. If worklet’s data origin is "context-origin", return outsideSettings’s origin.
5. Let pendingAddedModules be a clone of worklet’s added modules list.
6. Assert: pendingAddedModules’s size is 1.
7. Let moduleURL be pendingAddedModules[0].
8. Return moduleURL’s origin.
......

2.2.2. Monkey Patch for create a worklet global scope

The create a worklet global scope algorithm will need to be modified to pass in the worklet parameter:

Let insideSettings be the result of setting up a worklet environment settings object given realmExecutionContext, outsideSettings, and worklet.

2.2.3. Monkey Patch for fetch a worklet script graph

The algorithm fetch a worklet script graph calls into the fetch a worklet/module worker script graph algorithm, which takes in an algorithm parameter processCustomFetchResponse. The definition of that processCustomFetchResponse parameter will need to include the following step before the step "5. Fetch request, ...":

If fetchClient’s global object is SharedStorageWorkletGlobalScope:
1. Set request’s redirect mode to "error".
  
  Note: For shared storage, redirects are disallowed for the module script request. With this restriction, it’s possible to define and to use the algorithm that gets the realm’s settings object's origin (as described in § 2.2.1 Monkey Patch for set up a worklet environment settings object) as soon as the SharedStorageWorkletGlobalScope is created, as the origin won’t change. This restriction may be removed in a future iteration of the design. If redirects become allowed, presumably, the algorithm that gets the realm’s settings object's origin should be updated to return the final request’s URL's origin after receiving the final request’s response, and the user preference checkings shall only be done after that point.
2. If fetchClient’s origin and settingsObject’s origin are not same origin:
  1. Let dataOriginValue be the serialization of settingsObject’s origin.
  2. Assert that dataOriginValue is not null.
  3. Append the header ("Sec-Shared-Storage-Data-Origin", dataOriginValue) to request’s header list.

2.2.4. The ``Shared-Storage-Cross-Origin-Worklet-Allowed`` HTTP response header

The `Shared-Storage-Cross-Origin-Worklet-Allowed` HTTP response header, along with the traditional CORS headers, can be used to grant a cross-origin site the permission to create a worklet from the module script’s URL's origin, and to run subsequent operations on the worklet using the module script’s URL's origin as the data partition origin for accessing shared storage data, i.e. the origin set in § 2.2.1 Monkey Patch for set up a worklet environment settings object, which becomes the origin used in all WorkletSharedStorage calls to obtain a shared storage bottle map.

Worklets that load cross-origin scripts rely on CORS as a baseline permission mechanism to indicate trusted external origins. However, CORS alone is insufficient for creation of a worklet with cross-origin script whose data partition origin is the script origin. Unlike simple resource sharing, worklets allow the creator site to execute JavaScript within the context of the target origin. To ensure security, an additional response header, `Shared-Storage-Cross-Origin-Worklet-Allowed`, is required from the script origin.

2.2.5. Monkey Patch for HTTP fetch

The following step will be added to the HTTP fetch steps, before checking the redirect status (i.e. "6. If internalResponse’s status is a redirect status, ..."):

If request’s destination is "sharedstorageworklet":
1. Let dataOriginValue be the result of getting "Sec-Shared-Storage-Data-Origin" from request’s header list.
2. If dataOriginValue is not null, then:
  1. Let dataOriginUrl be the result of running a URL parser on dataOriginValue.
  2. Assert that dataOriginUrl is not failure.
  3. Assert that request’s origin is not "client".
  4. Assert that request’s origin and request’s URL's origin are not same origin.
  5. Assert that dataOriginUrl’s origin and request’s URL's origin are same origin.
  6. Let responseHeaders be internalResponse’s header list.
  7. Let allowed be the result of running get a structured field value algorithm given `Shared-Storage-Cross-Origin-Worklet-Allowed`, "item", and responseHeaders as input.
  8. If allowed is false, then return a network error.

Note: It is the responsibility of the site serving the module script to carefully consider the security implications: when the module script’s URL's origin and the worklet’s creator Window origin are not same origin, by sending permissive CORS headers the `Shared-Storage-Cross-Origin-Worklet-Allowed` header on the module script response, the server will be granting the worklet’s creation and subsequent operations on the worklet, while allowing the worklet to use the worklet’s script’s origin as the origin for accessing the shared storage data, i.e. the data partition origin. For example, the worklet’s creator Window could poison and use up the worklet origin’s remaining navigation budget by calling selectURL() or run(), where the worklet origin is the global scope’s realm's settings object's origin.

2.2.6. Monkey Patch for `addModule()`

The addModule() method steps for Worklet will need to include the following step before the step "Let promise be a new promise":

If this is of type SharedStorageWorklet:
1. Let addModuleAllowedResult be the result of running check if addModule is allowed and update state given this and moduleURLRecord.
2. If addModuleAllowedResult is "DisallowedDueToNonPreferenceError":
  1. Return a promise rejected with a TypeError.
3. Else if addModuleAllowedResult is "DisallowedDueToPreferenceError":
  1. If this’s has cross-origin data origin is false, then return a promise rejected with a TypeError.
4. Else:
  1. Assert: addModuleAllowedResult is "Allowed".

On user preferences error, addModule() will be aborted at an early stage. However, the error will only be exposed to the caller for a same-origin worklet (i.e. where the initiator document’s origin is same-origin with the module script’s origin). For a cross-origin worklet, the error will be hidden. This is to prevent a caller from knowing which origins the user has disabled shared storage for via preferences (if a per-origin preference exists for that browser vendor).

A caller may still use timing attacks to know this information, but this is a minor security/privacy issue, as in reality very few users would set such preferences, and doing a wide search would incur a significant performance cost spinning up the worklets.

This rationale also applies to the handling for user preferences error for selectURL() and run().

The penultimate step (i.e. the final indented step), currently "If pendingTasks is 0, then resolve promise.", should be updated to:

If pendingTasks is 0, perform the following steps:
1. If workletGlobalScope has an associated boolean addModule success, set workletGlobalScope’s addModule success to true.
2. Resolve promise.

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

2.3. The `SharedStorageWorkletGlobalScope`

The SharedStorageWorklet's worklet global scope type is SharedStorageWorkletGlobalScope.

The SharedStorageWorklet's worklet destination type is "sharedstorageworklet".

2.3.1. Monkey Patch for request destination

The fetch request’s destination field should additionally include "sharedstorageworklet" as a valid value.

callback RunFunctionForSharedStorageSelectURLOperation = Promise<unsigned long>(sequence<USVString> urls, optional any data);

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

  readonly attribute WorkletSharedStorage sharedStorage;
};

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

Each SharedStorageWorkletGlobalScope has an associated boolean addModule success, which is initialized to false.

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

Each SharedStorageWorkletGlobalScope also has an associated WorkletSharedStorage instance, with the sharedStorage getter algorithm as described below.

2.4. `SharedStorageWorkletGlobalScope` algorithms

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.
Let operationClassInstance be the result of constructing operationCtor, with no arguments.
Let runFunction be Get(operationClassInstance, "run"). Rethrow any exceptions.
Let runIDLFunction be the result of converting runFunction to a Web IDL RunFunctionForSharedStorageSelectURLOperation instance.
Set the value of operationMap[name] to runIDLFunction.

The "name" and "operationCtor" cannot be missing here given WebIDL. Should just check for default/empty values. [Issue #151]

The sharedStorage getter steps are:

If this's addModule success is true, return this's sharedStorage.
Otherwise, throw a TypeError.

To check whether addModule is finished, the step is:

Return the value of addModule success.

2.5. `SharedStorageUrlWithMetadata` and Reporting

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

If a SharedStorageUrlWithMetadata dictionary contains a non-empty reportingMetadata object in the form of a dictionary whose keys are FenceEvent's 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.

reportingMetadata should be a dictionary. [Issue #141]

Inside a fenced frame with eventType-URL pairs that have been registered through selectURL() with reportingMetadata objects, if 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 not a dictionary, return false.
If reportingMetadata is empty, return true.
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 fencedFrameConfigStruct, run the following steps:

If reportingMetadata is empty, return.
Assert: 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: 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]. [Issue #144]

2.6. Entropy Budgets

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

2.6.1. Navigation Entropy Budget

If a user activates a fenced frame whose node document's browsing context's fenced frame config instance was generated by selectURL() and thereby initiates a top-level traversable 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 site navigation entropy allowance.

A calling site for selectURL() is a site.

A navigation entropy allowance is a maximum allowance of entropy bits that are permitted to leak via fenced frames initiating top-level traversable navigations during a given navigation budget epoch for a given calling calling site. This allowance is defined by the user agent and is calling site-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 sites to navigation entropy ledgers.

An navigation entropy ledger is a list of bit debits.

A bit debit is a struct with the following items:

bits: a double
timestamp: a DOMHighResTimeStamp (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 site, along with the current time as a timestamp, together as a bit debit in the shared storage navigation budget table.

A calling site'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 a calling site has insufficient remaining navigation budget, selectURL() will return a SharedStorageResponse (i.e. either a FencedFrameConfig or a urn uuid) 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 registered operation class’s "run" method.

Methods can’t have state attached to them. Many definitions in this section needs improving. [Issue #147]

The default index could be defined to be 0.

In this case, whenever the registered operation class’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 − 1.

In this case, whenever the registered operation class’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 an environment settings object environment and a calling site site, run the following steps:

Assert: site is not an opaque origin.
Let maxBits be the user agent's navigation entropy allowance.
If the user agent's shared storage navigation budget table does not contain site, then return maxBits.
Otherwise, let ledger be user agent's shared storage navigation budget table[site].
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 environment and bitDebit is false, then increment debitSum by debit.
Return maxBits − debitSum.

To check whether a bit debit is expired, given an environment settings object environment and a bit debit bitDebit, run the following steps:

Let epochLength be the user agent's navigation budget lifetime.
Let currentTime be environment’s current wall time.
Let threshold be currentTime − 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-level traversable navigation initiated by a fenced frame whose node document's browsing context's fenced frame config instance 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-level traversable navigation, the bits must be stored as a pending shared storage budget debit in the corresponding fenced frame’s node document's browsing context's fenced frame config instance until this time.

Move the definition of pending shared storage budget debit to fenced frame config instance in the draft [Fenced-Frame] specification. [Issue #148]

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

Need to find a better way to specify timing of the navigation budget charging. [Issue #138]

The boolean shared storage navigation budget charged have not yet been added to fenced frame config instance in 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. [Issue #149]

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

If navigable is not a top-level traversable, return.
Let currentNavigable be sourceDocument’s node navigable.
While currentNavigable is not null:
1. Let site be the result of running obtain a site with currentNavigable’s active document's origin.
2. Let instance be currentNavigable’s node document's browsing context's fenced frame config instance.
3. Set currentNavigable to currentNavigable’s parent.
4. If instance is null or site is an opaque origin, then continue.
5. Let pendingBits be instance’s pending shared storage budget debit.
6. If pendingBits is not greater than 0, or if instance’s shared storage navigation budget charged is true, then continue.
7. Let ledger be user agent's shared storage navigation budget table[site].
8. Let bitDebit be a new bit debit.
9. Set bitDebit’s bits to pendingBits.
10. Let currentTime be the current wall time.
11. Set bitDebit’s timestamp to currentTime.
12. Append bitDebit to ledger.
13. Set instance’s shared storage navigation budget charged to true.

2.6.2. Reporting Entropy Budget

Likewise, each time a call to 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 (i.e. primary main frame’s) lifecycle.

A reporting entropy allowance is a maximum allowance of entropy bits that are permitted to leak via 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 reportEvent() is called with a destination containing "shared-storage-select-url", it will be necessary to charge shared storage reporting budget as below.

Move this to reportEvent() in [Fenced-Frame]. [Issue #150]

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

Let debitSum be 0.
Let currentNavigable be sourceDocument’s node navigable.
While currentNavigable is not null:
1. Let instance be currentNavigable’s initiator fenced frame config instance.
2. Set currentNavigable to currentNavigable’s parent.
3. If instance is null, then continue.
4. Let pendingBits be instance’s pending shared storage budget debit.
5. If pendingBits is greater than 0 and if instance’s shared storage reporting budget charged is false, increment debitSum by pendingBits.
Return debitSum.

The boolean shared storage reporting budget charged have not yet been added to fenced frame config instance in 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. [Issue #149]

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 currentNavigable be sourceDocument’s node navigable.
Let topNode be the result of running get the top-level traversable for currentNavigable.
If topNode’s shared storage reporting budget is less than toCharge, return false.
While currentNavigable is not null:
1. Let instance be currentNavigable’s node document's browsing context's fenced frame config instance.
2. If instance is not null and if instance’s pending shared storage budget debit is greater than 0, set instance’s shared storage reporting budget charged to true.
3. Set currentNavigable to currentNavigable’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.

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, an environment settings object environment, and an origin origin, run these steps:

Let allowedInOpaqueOriginContext be false.
If the result of running determine whether shared storage is allowed by context given environment, origin, and allowedInOpaqueOriginContext is false, then return failure.
If the result of running check if user preference setting allows access to shared storage given environment and origin is false, 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 and an origin origin, 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, environment, and origin.
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, a storage proxy map databaseMap, an environment settings object environment, a key key, and a value value, run the following steps on queue:

Let valueStruct be a new value struct.
Set valueStruct’s value to value.
Let currentTime be the environment’s current wall time.
Set valueStruct’s last updated to currentTime.
Set databaseMap[key] to valueStruct.
If an exception was thrown, then return false.

Note: Errors with storage proxy map databaseMap’s methods are possible depending on its implementation.
Otherwise, return true.

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

If databaseMap does not contain key, return undefined.
Let valueStruct be the result of running Get on databaseMap with key.
If an exception was thrown, then return failure.

Note: Errors with storage proxy map databaseMap’s methods are possible depending on its implementation.
If the result of running determine whether an entry is expired with environment and valueStruct is true, return undefined.
Return valueStruct’s value.

To delete an entry from the database, given a shared storage database queue queue, a storage proxy map databaseMap, and a key key, run the following steps on queue:

Remove databaseMap[key].
If an exception was thrown, then return false.

Note: Errors with storage proxy map databaseMap’s methods are possible depending on its implementation.
Return true.

To clear all entries in the database, given a shared storage database queue queue and a storage proxy map databaseMap, run the following steps on queue:

Run Clear on databaseMap.
If an exception was thrown, then return false.

Note: Errors with storage proxy map databaseMap’s methods are possible depending on its implementation.
Return true.

To retrieve all entries from the database, given a shared storage database queue queue and a storage proxy map databaseMap, run the following steps on queue:

Let values be the result of running getting the values on databaseMap.
If an exception was thrown, then return failure.

Note: Errors with storage proxy map databaseMap’s methods are possible depending on its implementation.
Return values.

To count entries in the database, given a shared storage database queue queue and a storage proxy map databaseMap, run the following steps on queue:

Let size be databaseMap’s size.
If an exception was thrown, then return failure.

Note: Errors with storage proxy map databaseMap’s members are possible depending on its implementation.
Return size.

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

For each key key in databaseMap:
1. Let valueStruct be the result of running Get on databaseMap with key.
2. If an exception was thrown, then return false.
3. If the result of running determine whether an entry is expired with environment and valueStruct is true, Remove databaseMap[key].
4. If an exception was thrown, then return false.
Return true.

To determine whether an entry is expired, given an environment settings object environment and 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 environment’s 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 posting operations to run inside SharedStorageWorkletGlobalScope (i.e. selectURL() and run()), 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.

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

  Promise<SharedStorageWorklet> createWorklet(USVString moduleURL, optional SharedStorageWorkletOptions options = {});

  readonly attribute SharedStorageWorklet worklet;
};

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

dictionary SharedStorageWorkletOptions : WorkletOptions {
  SharedStorageDataOrigin dataOrigin = "context-origin";
};

4.1.1. Window Setter/Deleter Methods

The set(key, value, options) method step is:

Return the result of running set a key-value pair on WindowSharedStorage, key, value, and options.

The append(key, value) method step is:

Return the result of running append a key-value pair on WindowSharedStorage, key, and value.

The delete(key) method step is:

Return the result of running delete a key on WindowSharedStorage and key.

The clear() method step is:

Return the result of running clear all keys on WindowSharedStorage.

To set a key-value pair, given WindowSharedStorage sharedStorage, string key, string value, and SharedStorageSetMethodOptions options, perform the following steps:

Let promise be a new promise.
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 context be sharedStorage’s Window's browsing context.
If context is null, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and environment’s origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's shared storage database queue.
Let realm be the current realm.
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, databaseMap, environment, and key is not undefined:
  1. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
  2. Abort these steps.
2. Run store an entry in the database with queue, databaseMap, environment, key, and value.
3. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

To append a key-value pair, given WindowSharedStorage sharedStorage, string key, and string value, perform the following steps:

Let promise be a new promise.
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 context be sharedStorage’s Window's browsing context.
If context is null, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and environment’s origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's shared storage database queue.
Let realm be the current realm.
Enqueue the following steps on queue:
1. Let currentValue be the result of running retrieve an entry from the database with queue, databaseMap, environment, and key.
2. If currentValue is failure:
  1. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
  2. 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, databaseMap, environment, key, and value.
5. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

To delete a key, given WindowSharedStorage sharedStorage and string key, perform the following steps:

Let promise be a new promise.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let context be sharedStorage’s Window's browsing context.
If context is null, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and environment’s origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's shared storage database queue.
Let realm be the current realm.
Enqueue the following steps on queue:
1. Run delete an entry from the database with queue, environment, and key.
2. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

To clear all keys, given WindowSharedStorage sharedStorage, perform the following steps:

Let promise be a new promise.
Let context be sharedStorage’s Window's browsing context.
If context is null, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and environment’s origin
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's shared storage database queue.
Let realm be the current realm.
Enqueue the following steps on queue:
1. Run clear all entries in the database with queue and environment.
2. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

4.1.2. Run Operation Methods on `WindowSharedStorage`

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

Let sharedStorage be this.
Return sharedStorage.worklet.selectURL(name, urls, options).

The run(name, options) method steps are:

Let sharedStorage be this.
Return sharedStorage.worklet.run(name, options).

4.1.3. Create a new worklet via `WindowSharedStorage`

The createWorklet(moduleURL, options) method steps are:

Let sharedStorageWorklet be a new SharedStorageWorklet.
If options contains dataOrigin, set sharedStorageWorklet’s data origin to options[dataOrigin].
Let addModulePromise be the result of invoking sharedStorageWorklet.addModule(moduleURL, options).
Let resultPromise be a new promise.
Upon fulfillment of addModulePromise, resolve resultPromise to sharedStorageWorklet.
Upon rejection of addModulePromise, reject resultPromise with a TypeError.
Return resultPromise.

4.2. Extension to the `Window` interface

Each Window object has an associated WindowSharedStorage instance sharedStorage, which is created alongside the .Window if Shared Storage is enabled, with the getter below.

partial interface Window {
  [SecureContext] readonly attribute WindowSharedStorage? sharedStorage;
};

The sharedStorage getter steps are:

If this is fully active, return this's sharedStorage.
Otherwise, return null.

4.3. 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.3.1. Worklet Setter/Deleter Methods

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

Let promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
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 context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and realm’s settings object's origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's 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, databaseMap, environment, and key.
  2. If currentValue is failure:
    1. Queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
    2. Abort these steps.
  3. If currentValue is not undefined:
    1. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
    2. Abort these steps.
2. If the result of running store an entry in the database with queue, databaseMap, environment, key, and value is false, queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
3. Otherwise, queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

The append(key, value) method steps are:

Let promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
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 context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and realm’s settings object's origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's 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, databaseMap, environment, and key.
2. If currentValue is failure:
  1. Queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
  2. 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, databaseMap, environment, key, and value is false, queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
5. Otherwise, queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

The delete(key) method steps are:

Let promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and realm’s settings object's origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's 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, queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
2. Otherwise, queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

The clear() method steps are:

Let promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and realm’s settings object's origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's 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, queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
2. Otherwise, queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
Return promise.

4.3.2. Getter Methods

The get(key) method steps are:

Let promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
If key’s length exceeds the maximum length, return a promise rejected with a TypeError.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and realm’s settings object's origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's 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, databaseMap, environment, and key.
2. If value is failure, queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
3. Otherwise, if value is undefined, queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with undefined.
4. Otherwise, queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with value.
Return promise.

The length() method steps are:

Let promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and realm’s settings object's origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's 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, queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
3. Otherwise, queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with numEntries.
Return promise.

The remainingBudget() method steps are:

Let promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let allowedInOpaqueOriginContext be false.
If the result of running determine whether shared storage is allowed by context given environment, realm’s settings object's origin, and allowedInOpaqueOriginContext is false, return a promise rejected with a TypeError.
If the result of running check if user preference setting allows access to shared storage given environment and realm’s settings object's origin is false, return a promise rejected with a TypeError.
Let site be the result of running obtain a site with realm’s settings object's origin.
Assert: site is not an opaque origin.
Let queue be context’s associated database's shared storage database queue.
Enqueue the following steps on queue:
1. Let remainingBudget be the result of running determine remaining navigation budget with site.
2. Resolve queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with remainingBudget.
Return promise.

4.3.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 promise be a new promise.
If the result of running check whether addModule is finished for WorkletSharedStorage's associated SharedStorageWorkletGlobalScope is false, return a promise rejected with a TypeError.
Let context be WorkletSharedStorage's SharedStorageWorkletGlobalScope's outside settings's target browsing context.
If context is null, return a promise rejected with a TypeError.
If context’s active window's associated document is not fully active, return a promise rejected with a TypeError.
Let environment be context’s active window's relevant settings object.
Let realm be the current realm.
Let databaseMap be the result of running obtain a shared storage bottle map given environment and realm’s settings object's origin.
If databaseMap is failure, then return a promise rejected with a TypeError.
Let queue be context’s associated database's 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, queue a global task on the DOM manipulation task source, given realm’s global object, to reject promise with a TypeError.
3. Otherwise, queue a global task on the DOM manipulation task source, given realm’s global object, to 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. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with doneObject.
  3. Abort these steps.
3. Otherwise, let entry be the result of dequeueing from iterator’s pending entries.
4. Queue a global task on the DOM manipulation task source, given realm’s global object, to resolve promise with entry.
Return promise.

5. Triggering Operations Via HTTP Response Header

While setter and deleter operations (e.g.. set(), append(), delete(), clear()) can be initiated via the above APIs for Window or SharedStorageWorkletGlobalScope, setter/deleter operations can alternatively be triggered via HTTP response header.

This will require monkey patches to the HTML and Fetch specifications.

6. HTML Monkey Patches

6.1. `sharedStorageWritable` & `sharedstoragewritable` Attributes

Define the following interface mixin and include it in the IDL interfaces for HTMLIFrameElement and HTMLImageElement:

interface mixin HTMLSharedStorageWritableElementUtils {
  [CEReactions, SecureContext] attribute boolean sharedStorageWritable;
};

HTMLIFrameElement includes HTMLSharedStorageWritableElementUtils;
HTMLImageElement includes HTMLSharedStorageWritableElementUtils;

Add the following boolean content attributes:

iframe: sharedstoragewritable
img: sharedstoragewritable

The IDL attribute sharedStorageWritable must reflect the respective content attribute of the same name.

6.2. HTML Algorithm Modifications

6.2.1. Modification to Update the image data Algorithm

Modify update the image data as follows:

After the step

Set request’s priority to the current state...

add the step

If the element has the sharedstoragewritable attribute present, set request’s shared storage writable to true.

6.2.2. Modification to Create navigation params by fetching Algorithm

Modify as follows:

After the step

Let request be a new request, with ...

add the step

If navigable’s container is an iframe element, and if it has a sharedstoragewritable content attribute, then set request’s shared storage writable to true.

7. Fetch Monkey Patches

7.1. `sharedStorageWritable` Key

A request has an associated boolean shared storage writable. Unless stated otherwise it is false.

The RequestInit dictionary contains a sharedStorageWritable key:

partial dictionary RequestInit {
  boolean sharedStorageWritable;
};

7.2. Fetch Algorithm Modifications

7.2.1. Modification to the Request Constructor Algorithm

Modify the new Request(input, init) constructor as follows:

Before the step

Set this’s request to request.

add the step

If init["sharedStorageWritable"] exists, then set request’s shared storage writable to it.

7.2.2. Modification to HTTP network or cache fetch Algorithm

Modify the HTTP network or cache fetch algorithm as follows:

Before the step

Modify httpRequest’s header list per HTTP. ...

add the step

Append or modify a Sec-Shared-Storage-Writable request header for httpRequest.

7.2.3. Modification to HTTP fetch Algorithm

Modify the HTTP fetch algorithm as follows:

Before the step

If internalResponse’s status is a redirect status: ...

add the step

Handle a Shared-Storage-Write response, given response internalResponse and request request as input.

7.3. Shared Storage HTTP Headers

7.3.1. ``Sec-Shared-Storage-Writable`` Request Header

This specification defines a Sec-Shared-Storage-Writable HTTP request header.

The `Sec-Shared-Storage-Writable` request header is a Structured Header whose value must be a Boolean.

When a request sets `Sec-Shared-Storage-Writable` to true its response will be able to write to shared storage.

7.3.2. ``Shared-Storage-Write`` Response Header

This specification defines a Shared-Storage-Write HTTP response header.

The `Shared-Storage-Write` response header is a Structured Header whose value must be a List. The following list members are defined. Tokens and Strings holding the same sequence of characters are considered equivalent. Byte Sequences representing UTF-8 encoded bytes are also allowed, in order to provide functionality for writing and deleting non-ASCII Unicode keys and values via HTTP headers.

Unknown list members, including types that are neither strings nor Byte Sequences, are skipped, and the rest of the list is processed as if they weren’t present. Members are also skipped if they’re missing required parameters or those parameters have unexpected types.

set
- Required parameters:
  - key (Token, String, or Byte Sequence)
  - value (Token, String, or Byte Sequence)
- Optional parameter:
  - ignore_if_present (Boolean)
- If the parameter value of ignore_if_present is null or false, or if the parameter value of key does not already exist in the shared storage database for the responding server’s origin, set writes the entry consisting of the parameter values for key and value, as the entry's key and entry's value struct's value respectively, in the shared storage database for the responding server’s origin.
- If the parameter value of ignore_if_present is true and the parameter value of key already exists in the shared storage database for the responding server’s origin, then set is a no-op.
append
- Required parameters:
  - key (Token, String, or Byte Sequence)
  - value (Token, String, or Byte Sequence)
- If the parameter value of key already exists in the shared storage database for the responding server’s origin, then append updates the key's entry's value struct's value by appending the parameter value for value to it.
- If the parameter value of key does not already exist in the shared storage database for the responding server’s origin, append is equivalent to set with ignore_if_present false, i.e. append writes the entry consisting of the parameter values for key and value, as the entry's key and entry's value struct's value respectively, in the shared storage database for the responding server’s origin.
delete
- Required parameter:
  - key (Token, String, or Byte Sequence)
- delete erases any entry in the shared storage database for the responding server’s origin for which the key is equal to the parameter value of key.
clear
- clear erases all entries in the shared storage database for the responding server’s origin.

Note: We allow Byte Sequences in order to accommodate Unicode keys and values. Any Byte Sequence will be assumed to be UTF-8 encoded and will fail to parse otherwise.

Add examples.

7.4. Shared Storage Fetch-Related Algorithms

To determine whether a request can currently use shared storage, given a request request, perform the following steps:

Let window to request’s window.
If window is not an environment settings object whose global object is a Window, return false.
Let allowedInOpaqueOriginContext be true.
If the result of running determine whether shared storage is allowed by context given window, request’s current URL's origin, and allowedInOpaqueOriginContext is false, return false.
If the result of running check if user preference setting allows access to shared storage given window and request’s current URL's origin is false, return false.

The determine whether a request can currently use shared storage algorithm needs to take into account "opt-in features", as articulated in https://github.com/w3c/webappsec-permissions-policy/pull/499.

To append or modify a Sec-Shared-Storage-Writable request header, given a request request, perform the following steps:

If request’s shared storage writable is not true, then return.

Note: On a redirect, it is possible for request’s shared storage writable to be true, but for the redirect not to have permission to use shared storage, making the result of running determine whether a request can currently use shared storage on request false.
If the result of running determine whether a request can currently use shared storage on request is false, delete `Sec-Shared-Storage-Writable` from request’s header list.
Otherwise, set a structured field value (`Sec-Shared-Storage-Writable`, true) in request’s header list.

To handle a Shared-Storage-Write response, given a response response and a request request, perform the following steps:

Let sharedStorageWritable the result of running get a structured field value algorithm given `Sec-Shared-Storage-Writable`, "item", and request’s header list as input.
If sharedStorageWritable is null, or sharedStorageWritable is not a Boolean, or the value of sharedStorageWritable is false, return.
Let window to request’s window.
Assert: window is an environment settings object whose global object is a Window.
Let sharedStorage be window’s global object's sharedStorage.
If sharedStorage is null, then return.
Let list be response’s header list.
Let operationsToParse be the result of running get a structured field value algorithm given `Shared-Storage-Write`, "list", and list as input.
If operationsToParse is null or empty, then return.
For each tuple (item, parameters) in operationsToParse, perform the following steps:
1. If item is an Inner List, continue.
2. Assert: item is an Bare Item.
3. Let operationString be the result of running get the string value for item.
4. If operationString is failure, continue.
5. Switch on operationString:
  If operationString is "clear":
  Perform the following steps:
  1. Run clear all keys on sharedStorage.
  2. Continue.
  If operationString is "delete":
  Perform the following steps:
  1. Let key be the result of running obtain a string-like parameter value with parameters and "key".
  2. If key is not null, run delete a key on sharedStorage with key.
  3. Continue.
  If operationString is "append":
  Perform the following steps:
  1. Let key be the result of running obtain a string-like parameter value with parameters and "key".
  2. If key is null, continue.
  3. Let value be the result of running obtain a string-like parameter value with parameters and "value".
  4. If value is not null, run append a key-value pair on sharedStorage with key and value.
  5. Continue.
  If operationString is "set":
  Perform the following steps:
  1. Let key be the result of running obtain a string-like parameter value with parameters and "key".
  2. If key is null, continue.
  3. Let value be the result of running obtain a string-like parameter value with parameters and "value".
  4. If value is null, continue.
  5. Let options be a new SharedStorageSetMethodOptions.
  6. If the result of running obtain a boolean parameter value with parameters and "ignore_if_present" is true, set options["ignoreIfPresent"] to true..
  7. Run set a key-value pair on sharedStorage with key, value, and options.
  8. Continue.
  If operationString is anything else:
  Continue.

To check if string-like for a Bare Item item, do the following:

If the item is a String, Token, or Byte Sequence, return true.
Otherwise, return false.

To get the string value for a Bare Item item, do the following:

If the result of running check if string-like on item is false, return failure.
Switch on the type of item:
If item is a Token:
If item is a String:
Perform the following steps:
1. Assert: item is an ASCII string.
2. Return item.
If item is a Byte Sequence:
Perform the following steps:
1. Let fromUTF8 be the result of running UTF-8 decode on item.
2. If fromUTF8 is an error, return null.
3. Return fromUTF8.

To obtain a string-like parameter value, given a parameters map parameters and a Token paramKey, perform the following steps:

If parameters does not contain paramKey, return null.
If the result of check if string-like for parameters[paramKey] is false, return null.
Return the result of running get the string value for parameters[paramKey].

To obtain a boolean parameter value, given a parameters map parameters and a Token paramKey, perform the following steps:

If parameters does not contain paramKey, return null.
If parameters[paramKey] is not a Boolean, return null.
Return parameters[paramKey].

8. Permissions Policy Integration

This specification defines a policy-controlled feature identified by the string "shared-storage," along with a second policy-controlled feature identified by "shared-storage-select-url".

"shared-storage" gates access to Shared Storage in general, whereas "shared-storage-select-url" adds an exra permission layer to selectURL(). For each of these, the default allowlist is *.

9. Clear Site Data Integration

Add details for Clear Site Data integration.

10. 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-level traversable navigation and/or the fenced frame calls the 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. Run Operation Methods on SharedStorageWorklet

2.2. Monkey Patch for Worklets

2.2.1. Monkey Patch for set up a worklet environment settings object

2.2.2. Monkey Patch for create a worklet global scope

2.2.3. Monkey Patch for fetch a worklet script graph

2.2.4. The `Shared-Storage-Cross-Origin-Worklet-Allowed` HTTP response header

2.2.5. Monkey Patch for HTTP fetch

2.2.6. Monkey Patch for addModule()

2.3. The SharedStorageWorkletGlobalScope

2.3.1. Monkey Patch for request destination

2.4. SharedStorageWorkletGlobalScope algorithms

2.5. SharedStorageUrlWithMetadata and Reporting

2.6. Entropy Budgets

2.6.1. Navigation Entropy Budget

2.6.2. Reporting Entropy Budget

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. Run Operation Methods on WindowSharedStorage

4.1.3. Create a new worklet via WindowSharedStorage

4.2. Extension to the Window interface

4.3. The WorkletSharedStorage interface

4.3.1. Worklet Setter/Deleter Methods

4.3.2. Getter Methods

4.3.3. Iteration

5. Triggering Operations Via HTTP Response Header

6. HTML Monkey Patches

6.1. sharedStorageWritable & sharedstoragewritable Attributes

6.2. HTML Algorithm Modifications

6.2.1. Modification to Update the image data Algorithm

6.2.2. Modification to Create navigation params by fetching Algorithm

7. Fetch Monkey Patches

7.1. sharedStorageWritable Key

7.2. Fetch Algorithm Modifications

7.2.1. Modification to the Request Constructor Algorithm

7.2.2. Modification to HTTP network or cache fetch Algorithm

7.2.3. Modification to HTTP fetch Algorithm

7.3. Shared Storage HTTP Headers

7.3.1. `Sec-Shared-Storage-Writable` Request Header

7.3.2. `Shared-Storage-Write` Response Header

7.4. Shared Storage Fetch-Related Algorithms

8. Permissions Policy Integration

9. Clear Site Data Integration

10. Privacy Considerations

Conformance

Document conventions

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

Informative References

IDL Index

Issues Index

2. The `SharedStorageWorklet` Interface

2.1. Run Operation Methods on `SharedStorageWorklet`

2.2.4. The ``Shared-Storage-Cross-Origin-Worklet-Allowed`` HTTP response header

2.2.6. Monkey Patch for `addModule()`

2.3. The `SharedStorageWorkletGlobalScope`

2.4. `SharedStorageWorkletGlobalScope` algorithms

2.5. `SharedStorageUrlWithMetadata` and Reporting

4. The `SharedStorage` Interface

4.1. The `WindowSharedStorage` interface

4.1.2. Run Operation Methods on `WindowSharedStorage`

4.1.3. Create a new worklet via `WindowSharedStorage`

4.2. Extension to the `Window` interface

4.3. The `WorkletSharedStorage` interface

6.1. `sharedStorageWritable` & `sharedstoragewritable` Attributes

7.1. `sharedStorageWritable` Key

7.3.1. ``Sec-Shared-Storage-Writable`` Request Header

7.3.2. ``Shared-Storage-Write`` Response Header