<pre class='metadata'>

Title: Shared Storage API

Shortname: sharedStorage

Level: 1

Status: CG-DRAFT

Group: WICG

Repository: WICG/shared-storage

URL: https://github.com/WICG/shared-storage

Editor: Camillia Smith Barnes, Google https://google.com, [email protected]

Markup Shorthands: markdown yes

Abstract: Shared Storage is a storage API that is intentionally not partitioned by top-level traversable site (though still partitioned by context origin of course!). To limit cross-site reidentification of users, data in Shared Storage may only be read in a restricted environment that has carefully constructed output gates.

</pre>

<pre class=link-defaults>

spec:infra;

type:dfn;

text:user agent

for:/; text:string

type:dfn;

for:/; text:list

spec:webidl;

type:interface;

text:double

type:dfn;

text:an exception was thrown

spec:html;

type:dfn;

for:realm; text:global object

for:WorkerGlobalScope; text:module map

for:navigable; text:top-level traversable

spec:fenced-frame;

type:dfn;

for:fencedframetype; text:fenced frame reporter

for:browsing context; text:fenced frame config instance

</pre>

<pre class="anchors">

urlPrefix: https://www.ietf.org/rfc/rfc4122.txt

type: dfn; text: urn uuid

spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/

type: dfn

text: worklets; url: worklets.html#worklets

text: added modules list; url: worklets.html#concept-worklet-added-modules-list

text: set up a worklet environment settings object; url: worklets.html#set-up-a-worklet-environment-settings-object

text: fetch a worklet/module worker script graph; url: webappapis.html#fetch-a-worklet/module-worker-script-graph

text: fetch a worklet script graph; url: webappapis.html#fetch-a-worklet-script-graph

text: processCustomFetchResponse; url: webappapis.html#fetching-scripts-processcustomfetchresponse

text: environment; url: webappapis.html#environment

text: obtaining a worklet agent; url: webappapis.html#obtain-a-worklet-agent

text: beginning navigation; url: webappapis.html#beginning-navigation

text: ending navigation; url: webappapis.html#ending-navigation

text: get the top-level traversable; url: webappapis.html#nav-top

text: boolean attributes; url: common-microsyntaxes.html#boolean-attributes

text: content attributes; url: dom.html#concept-element-attributes

text: update the image data; url: images.html#update-the-image-data

text: create navigation params by fetching; url: browsing-the-web.html#create-navigation-params-by-fetchin

spec: url; urlPrefix: https://url.spec.whatwg.org/

type: dfn

text: URL; for: /; url: concept-url

spec: dom; urlPrefix: https://dom.spec.whatwg.org/

type: dfn

text: origin; for: document; url: concept-document-origin

spec: infra; urlPrefix: https://infra.spec.whatwg.org

type: dfn

text: empty; for: map; url: map-is-empty

text: ASCII; url: ascii-code-point

spec: webidl; urlPrefix: https://webidl.spec.whatwg.org

type: dfn

text: Web IDL Standard; url: introduction

text: async iterator; url: idl-async-iterable

text: promise; url: idl-promise

text: promise rejected; url: a-promise-rejected-with

spec: storage; urlPrefix: https://storage.spec.whatwg.org/

type: dfn

text: storage model; url: model

text: storage type; url: storage-type

text: storage identifier; url: storage-identifier

text: storage shed; url: storage-shed

text: storage shelf; url: storage-shelf

text: storage bucket; url: storage-bucket

text: storage bottle; url: storage-bottle

text: quota; for: storage bottle; url: storage-bottle-quota

text: register; for: storage endpoint; url: registered-storage-endpoints

text: quota; for: storage endpoint; url: storage-endpoint-quota

text: bucket map; url: bucket-map

text: bottle map; url: bottle-map

text: storage proxy map; url: storage-proxy-map

text: backing map; url: storage-proxy-map-backing-map

text: proxy map reference set; url: storage-bottle-proxy-map-reference-set

spec: beacon; urlPrefix: https://w3c.github.io/beacon/

type: dfn

text: beacon; url: beacon

spec: ecma; urlPrefix: https://tc39.es/ecma262/

type: dfn

text: call; url: sec-call

text: current realm; url: current-realm

text: casting; url: sec-touint32

text: Get; url: sec-get-o-p

text: [[GetPrototypeOf]](); for: object; url: sec-ordinary-object-internal-methods-and-internal-slots-getprototypeof

text: IsConstructor(); url: sec-isconstructor

spec: storage-partitioning; urlPrefix: https://privacycg.github.io/storage-partitioning/

type: dfn

text: client-side storage partitioning

spec: fetch; urlPrefix: https://fetch.spec.whatwg.org/

type: dfn

text: http network or cache fetch; url: concept-http-network-or-cache-fetch

text: request-constructor; url: dom-request

spec: permissions-policy; urlPrefix: https://www.w3.org/TR/permissions-policy/

type: dfn

text: Is feature enabled in document for origin?; url: algo-is-feature-enabled

spec: attestation; urlPrefix: https://github.com/privacysandbox/attestation

type: dfn

text: enrolled

spec: private-aggregation-api; urlPrefix: https://github.com/patcg-individual-drafts/private-aggregation-api/blob/main/README.md

type: dfn

text: private aggregation

spec: fenced-frame; urlPrefix: https://wicg.github.io/fenced-frame/

type: dfn

text: fenced frame; url: the-fencedframe-element

text: url; for: FencedFrameConfig; url: dom-fencedframeconfig-url

text: initiator fenced frame config instance; for: source snapshot params; url: source-snapshot-params-initiator-fenced-frame-config-instance

text: fence.reportEvent(); url: dom-fence-reportevent

text: FenceEvent; url: dictdef-fenceevent

text: destination; for: FenceEvent; url: dom-fenceevent-destination

text: eventData; for: FenceEvent; url: dom-fenceevent-eventdata

text: eventType; for: FenceEvent; url: dom-fenceevent-eventtype

type: interface

text: FencedFrameConfig; url: fencedframeconfig

spec: rfc8941; urlPrefix: https://httpwg.org/specs/rfc8941.html

type: dfn

text: structured header; url: specify

text: list; for: structured header; url: list

text: parameters; for: structured header; url: param

text: item; for: structured header; url: item

text: string; for: structured header; url: string

text: token; for: structured header; url: token

text: byte sequence; for: structured header; url: binary

text: boolean; for: structured header; url: boolean

text: inner list; for: structured header; url: inner-list

text: bare item; for: structured header; url: item

spec: wikipedia-entropy; urlPrefix: https://en.wikipedia.org/wiki/Entropy_(information_theory)

type: dfn

text: bits of entropy

text: entropy bits

spec: shared-storage-explainer; urlPrefix: https://github.com/WICG/shared-storage

type:dfn

text: legitimate use cases; url: example-scenarios

</pre>

<style>

/* adapted from .XXX at https://resources.whatwg.org/standard.css */

.todo {

color: #D50606;

background: white;

border: solid #D50606;

}

span.todo {

padding-top: 0;

padding-bottom: 0;

}

.todo::before { content: 'TODO: '; }

span.todo::before {

left: 0;

top: -0.25em;

}

</style>

Introduction {#intro}

=====================

<em>This section is not normative.</em>

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|private aggregation report=]. Over time, there may be additional ouput gates included in the standard.

<div class="example">

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

Inside an `a.example` iframe:

<pre class="lang-js">

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;

</pre>

inside the `experiment.js` worklet script:

<pre class="lang-js">

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);

</pre>

</div>

The {{SharedStorageWorklet}} Interface {#worklet}

=================================================

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 {{SharedStorageWorklet/selectURL()|URL-selection}} output gate.

<xmp class='idl'>

typedef (USVString or FencedFrameConfig) SharedStorageResponse;

</xmp>

<xmp class='idl'>

[Exposed=(Window)]

interface SharedStorageWorklet : Worklet {

Promise<SharedStorageResponse> selectURL(DOMString name,

FrozenArray<SharedStorageUrlWithMetadata> urls,

optional SharedStorageRunOperationMethodOptions options = {});

Promise<any> run(DOMString name,

optional SharedStorageRunOperationMethodOptions options = {});

};

</xmp>

Each {{SharedStorageWorklet}} has an associated boolean <dfn for="SharedStorageWorklet">addModule initiated</dfn>, initialized to false.

Each {{SharedStorageWorklet}} has an associated boolean <dfn for="SharedStorageWorklet">cross-origin worklet allowed</dfn>, initialized to false.

Each {{SharedStorageWorklet}} has an associated boolean <dfn for="SharedStorageWorklet">is cross-origin worklet</dfn>, initialized to false.

Because adding multiple [=module scripts=] via {{Worklet/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 {{Worklet/addModule()}}, each {{SharedStorageWorklet}} can only call {{Worklet/addModule()}} once. The [=addModule initiated=] boolean makes it possible to enforce this restriction.

When {{Worklet/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 [=SharedStorageWorklet/is cross-origin worklet=] is false, it will cause {{Worklet/addModule()}} to fail, as detailed in the [[#add-module-monkey-patch]].

<div algorithm>

To <dfn>check if user preference setting allows access to shared storage</dfn> given an [=environment settings object=] |environment| and an [=/origin=] |origin|, run the following step:

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

</div>

<div algorithm>

To <dfn>determine whether shared storage is allowed by context</dfn>, given an [=environment settings object=] |environment|, an [=/origin=] |origin|, and a boolean |allowedInOpaqueOriginContext|, run these steps:

1. If |environment| is not a [=secure context=], then return false.

1. If |allowedInOpaqueOriginContext| is false and |environment|'s [=environment settings object/origin=] is an [=opaque origin=], then return false.

1. If |origin| is an [=opaque origin=], then return false.

1. Let |globalObject| be the [=current realm=]'s [=global object=].

1. [=Assert=]: |globalObject| is a {{Window}} or a {{SharedStorageWorkletGlobalScope}}.

1. If |globalObject| is a {{Window}}, and if the result of running [=Is feature enabled in document for origin?=] on "[=PermissionsPolicy/shared-storage=]", |globalObject|'s [=associated document=], and |origin| returns false, then return false.

1. Return true.

</div>

<div algorithm>

To <dfn>determine whether shared storage is allowed by enrollment and user preference</dfn>, given an [=environment settings object=] |environment| and an [=/origin=] |origin|, run these steps:

1. If the result of running [=obtaining a site|obtain a site=] with |origin| is not [=enrolled=], then return false.

1. Return the result of running [=check if user preference setting allows access to shared storage=] given |environment| and |origin|.

</div>

<div class="note">

Here are the scenarios where the algorithms [=determine whether shared storage is allowed by context=] and [=determine whether shared storage is allowed by enrollment and user preference=] are used:

- For each method under [[#window-setter]], |environment| is the current context, and |origin| is |environment|'s [=environment settings object/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 [=url/origin=].

- For running operations on a worklet (from a {{Window}}), and for each method under [[#worklet-setter]] (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 [=global object/realm=]'s [=realm/settings object=]'s [=environment settings object/origin=].

- For [[#ss-fetch-algo]], |environment| is the request's [=request/window=], and |origin| is the request's [=request/current URL=]'s [=url/origin=].

- For [[#ss-fetch-algo]], for {{WindowSharedStorage/createWorklet()}} called with a cross-origin worklet script, and for {{SharedStorageWorklet/selectURL()}} and {{SharedStorageWorklet/run()}} that operate on a cross-origin worklet created from {{WindowSharedStorage/createWorklet()}}, |allowedInOpaqueOriginContext| is true. For other methods, |allowedInOpaqueOriginContext| is false.

</div>

<div algorithm>

To <dfn>check if addModule is allowed and update state</dfn> given a {{SharedStorageWorklet}} |worklet| and a [=/URL=] |moduleURLRecord|, run the following steps:

1. If |worklet|'s [=addModule initiated=] is true, return "DisallowedDueToNonPreferenceError".

1. Set |worklet|'s [=addModule initiated=] to true.

1. Let |workletOrigin| be |moduleURLRecord|'s [=url/origin=].

1. Let |isCrossOriginWorklet| be false.

1. If |workletOrigin| and the [=current settings object=]'s [=environment settings object/origin=] are not [=same origin=], then set |isCrossOriginWorklet| to true.

1. Let |allowedInOpaqueOriginContext| be |isCrossOriginWorklet|.

1. If the result of running [=determine whether shared storage is allowed by context=] given the [=current settings object=], |workletOrigin|, and |allowedInOpaqueOriginContext| is false, return "DisallowedDueToNonPreferenceError".

1. Set |worklet|'s [=SharedStorageWorklet/is cross-origin worklet=] to |isCrossOriginWorklet|.

1. If |worklet|'s [=cross-origin worklet allowed=] is false, and if |worklet|'s [=SharedStorageWorklet/is cross-origin worklet=] is true, return "DisallowedDueToNonPreferenceError".

1. If the result of running [=determine whether shared storage is allowed by enrollment and user preference=] given the [=current settings object=] and |workletOrigin| is false, return "DisallowedDueToPreferenceError".

1. Return "Allowed".

</div>

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

## Run Operation Methods on {{SharedStorageWorklet}} ## {#run-op-shared-storage-worklet}

<div algorithm>

To <dfn>get the select-url result index</dfn>, given {{SharedStorageWorklet}} |worklet|, {{DOMString}} |operationName|, [=/list=] of {{SharedStorageUrlWithMetadata}}s |urlList|, and {{SharedStorageRunOperationMethodOptions}} |options|:

1. Let |promise| be a new [=promise=].

1. Let |window| be |worklet|'s [=relevant settings object=].

1. [=Assert=]: |window| is a {{Window}}.

1. If |window|'s [=Window/browsing context=] is null, then return a [=promise rejected=] with a {{TypeError}}.

1. If |window|'s [=associated document=] is not [=fully active=], return a [=promise rejected=] with a {{TypeError}}.

1. 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 [=list/size=] is 1.

1. [=Assert=]: |worklet|'s [=module map=] is not [=map/empty=].

1. Let |globalScope| be [=this=]'s [=global scopes=][0].

1. Let |operationMap| be |globalScope|'s [=SharedStorageWorkletGlobalScope/operation map=].

1. If |operationMap| does not [=map/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 {{SharedStorageWorkletGlobalScope/register()}} was never called with |operationName|.

1. Let |operation| be |operationMap|[|operationName|].

1. [=Assert=]: |operation|'s [=associated realm=] is [=this=]'s [=relevant realm=].

1. Let |argumentsList| be the [=/list=] « |urlList| ».

1. If |options| [=map/contains=] |data|, [=list/append=] |data| to |argumentsList|.

1. Let |index| be the result of [=invoking=] |operation| with |argumentsList|.

1. 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 {{SharedStorageWorkletGlobalScope/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.

1. If |index| is greater than |urlList|'s [=list/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.

1. [=Queue a global task=] on the [=DOM manipulation task source=], given |window|, to [=resolve=] |promise| with |index|.

</div>

<div algorithm>

The <dfn method for="SharedStorageWorklet">selectURL(|name|, |urls|, |options|)</dfn> method steps are:

1. Let |resultPromise| be a new [=promise=].

1. If [=this=]'s [=addModule initiated=] is false, then return a [=promise rejected=] with a {{TypeError}}.

1. Let |window| be [=this=]'s [=relevant settings object=].

1. [=Assert=]: |window| is a {{Window}}.

1. Let |context| be |window|'s [=Window/browsing context=].

1. If |context| is null, then return a [=promise rejected=] with a {{TypeError}}.

1. Let |document| be |context|'s [=active document=].

1. [=Assert=]: [=this=]'s [=global scopes=]'s [=list/size=] is 1.

1. Let |globalScope| be [=this=]'s [=global scopes=][0].

1. Let |workletOrigin| be |globalScope|'s [=global object/realm=]'s [=realm/settings object=]'s [=environment settings object/origin=].

1. If the result of running [=Is feature enabled in document for origin?=] on "[=PermissionsPolicy/shared-storage-select-url=]", |document|, and |workletOrigin| returns false, return a [=promise rejected=] with a {{TypeError}}.

1. If [=this=]'s [=global scopes=] is [=list/empty=], then return a [=promise rejected=] with a {{TypeError}}.

Note: This can happen if either {{WindowSharedStorage/selectURL()}} or {{SharedStorageWorklet/selectURL()}} is called before {{addModule()}}.

1. If the result of running [=SharedStorageWorkletGlobalScope/check whether addModule is finished=] for |globalScope| is false, return a [=promise rejected=] with a {{TypeError}}.

1. If |urls| is empty or if |urls|'s [=list/size=] is greater than 8, return a [=promise rejected=] with a {{TypeError}}.

Note: 8 is chosen here so that each call of {{SharedStorageWorklet/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.

1. Let |urlList| be an empty [=list=].

1. [=map/iterate|For each=] |urlWithMetadata| in |urls|:

1. If |urlWithMetadata| has no field "`url`", return a [=promise rejected=] with a {{TypeError}}.

1. Otherwise, let |urlString| be |urlWithMetadata|["`url`"].

1. Let |serializedUrl| be the result of running [=get the canonical URL string if valid=] with |urlString|.

1. If |serializedUrl| is undefined, return a [=promise rejected=] with a {{TypeError}}.

1. Otherwise, [=list/append=] |serializedUrl| to |urlList|.

1. If |urlWithMetadata| has field "`reportingMetadata`":

1. Let |reportingMetadata| be |urlWithMetadata|["`reportingMetadata`"].

1. If the result of running [=validate reporting metadata=] with |reportingMetadata| is false, [=reject=] |resultPromise| with a {{TypeError}} and abort these steps.

1. Let |fencedFrameConfigMapping| be |window|'s [=associated document=]'s [=node navigable=]'s [=navigable/traversable navigable=]'s [=traversable navigable/fenced frame config mapping=].

1. Let |pendingConfig| be a new [=fenced frame config=].

1. Let |urn| be the result of running [=fenced frame config mapping/store a pending config=] on |fencedFrameConfigMapping| with |pendingConfig|.

1. If |urn| is failure, then return a [=promise rejected=] with a {{TypeError}}.

1. Let |environment| be |window|'s [=relevant settings object=].

1. Let |allowedInOpaqueOriginContext| be [=this=]'s [=SharedStorageWorklet/is cross-origin worklet=].

1. If the result of running [=determine whether shared storage is allowed by context=] given |environment|, |workletOrigin|, and |allowedInOpaqueOriginContext| is false, return a [=promise rejected=] with a {{TypeError}}.

1. If the result of running [=determine whether shared storage is allowed by enrollment and user preference=] given |environment| and |workletOrigin| is false:

1. If [=this=]'s [=SharedStorageWorklet/is cross-origin worklet=] is false, return a [=promise rejected=] with a {{TypeError}}.

1. If |options|["`resolveToConfig`"] is true, [=resolve=] |resultPromise| with |pendingConfig|.

1. Otherwise, [=resolve=] |resultPromise| with |urn|.

1. Let |indexPromise| be the result of running [=get the select-url result index=], given [=this=], |name|, |urlList|, and |options|.

1. [=Upon fulfillment=] of |indexPromise| with |resultIndex|, perform the following steps:

1. Let |site| be the result of running [=obtain a site=] with |document|'s [=Document/origin=].

1. Let |remainingBudget| be the result of running [=determine remaining navigation budget=] with |environment| and |site|.

1. Let |pendingBits| be the logarithm base 2 of |urlList|'s [=list/size=].

1. If |pendingBits| is greather than |remainingBudget|, set |resultIndex| to [=default index=].

1. Let |finalConfig| be a new [=fenced frame config=].

1. Set |finalConfig|'s [=fenced frame config/mapped url=] to |urlList|[|resultIndex|].

1. Set |finalConfig|'s <span class=todo>a "pending shared storage budget debit" field</span> to |pendingBits|.

1. [=Finalize a pending config=] on |fencedFrameConfigMapping| with |urn| and |finalConfig|.

1. Let |resultURLWithMetadata| be |urls|[|resultIndex|].

1. If |resultURLWithMetadata| has field "`reportingMetadata`", run [=register reporting metadata=] with |resultURLWithMetadata|["`reportingMetadata`"].

1. If |options|["`keepAlive`"] is false, run [=terminate a worklet global scope=] with [=this=].

1. [=Upon rejection=] of |indexPromise|, perform the following steps:

1. Let |finalConfig| be a new [=fenced frame config=].

1. Set |finalConfig|'s [=fenced frame config/mapped url=] to |urlList|[[=default index=]].

1. [=Finalize a pending config=] on |fencedFrameConfigMapping| with |urn| and |finalConfig|.

1. If |options|["`keepAlive`"] is false, run [=terminate a worklet global scope=] with [=this=].

1. Return |resultPromise|.

</div>

<div algorithm>

The <dfn method for="SharedStorageWorklet">run(|name|, |options|)</dfn> method steps are:

1. Let |promise| be a new [=promise=].

1. If [=this=]'s [=addModule initiated=] is false, then return a [=promise rejected=] with a {{TypeError}}.

1. Let |window| be [=this=]'s [=relevant settings object=].

1. [=Assert=]: |window| is a {{Window}}.

1. If [=this=]'s [=global scopes=] is [=list/empty=], then return a [=promise rejected=] with a {{TypeError}}.

1. [=Assert=]: [=this=]'s [=global scopes=]'s [=list/size=] is 1.

1. Let |globalScope| be [=this=]'s [=global scopes=][0].

1. If the result of running [=SharedStorageWorkletGlobalScope/check whether addModule is finished=] for |globalScope| is false, return a [=promise rejected=] with a {{TypeError}}.

1. Let |workletOrigin| be |globalScope|'s [=global object/realm=]'s [=realm/settings object=]'s [=environment settings object/origin=].

1. Let |allowedInOpaqueOriginContext| be [=this=]'s [=SharedStorageWorklet/is cross-origin worklet=].

1. If the result of running [=determine whether shared storage is allowed by context=] given |window|, |workletOrigin|, and |allowedInOpaqueOriginContext| is false, [=reject=] |promise| with a {{TypeError}}.

1. If the result of running [=determine whether shared storage is allowed by enrollment and user preference=] given |window| and |workletOrigin| is false:

1. If [=this=]'s [=SharedStorageWorklet/is cross-origin worklet=] is false, [=reject=] |promise| with a {{TypeError}}.

1. Else, [=resolve=] |promise| with undefined.

1. Return |promise|.

1. 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 {{SharedStorageWorklet/run()}} (via its success/error result).

1. [=Queue a global task=] on the [=DOM manipulation task source=], given |window|, to [=resolve=] |promise| with undefined.

1. If [=this=]'s [=module map=] is not [=map/empty=]:

1. Let |operationMap| be [=this=]'s {{SharedStorageWorkletGlobalScope}}'s [=SharedStorageWorkletGlobalScope/operation map=].

1. If |operationMap| [=map/contains=] |name|:

1. Let |operation| be |operationMap|[|name|].

1. [=Assert=]: |operation|'s [=associated realm=] is [=this=]'s [=relevant realm=].

1. If |options| [=map/contains=] |data|:

1. Let |argumentsList| be a new [=/list=].

1. [=list/Append=] |data| to |argumentsList|.

1. [=Invoke=] |operation| with |argumentsList|.

1. Otherwise, [=invoke=] |operation| without any arguments list.

1. If |options|["`keepAlive`"] is false:

1. Wait for |operation| to finish running, if applicable.

1. Run [=terminate a worklet global scope=] with [=this=].

</div>

## Monkey Patch for [=Worklets=] ## {#worklet-monkey-patch}

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

### Monkey Patch for [=set up a worklet environment settings object=] ### {#set-up-a-worklet-environment-settings-object-monkey-patch}

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 [=environment settings object/origin=] should be modified as follows:

6. Let |settingsObject| be a new [=environment settings object=] whose algorithms are defined as follows:

......

<b>The [=environment settings object/origin=]</b>

1. Let |workletGlobalScope| be the [=global object=] of <var ignore=''>realmExecutionContext</var>'s Realm component.

1. If |workletGlobalScope| is not {{SharedStorageWorkletGlobalScope}}, return |origin|.

1. Let |pendingAddedModules| be a [=list/clone=] of |worklet|'s [=added modules list=].

1. [=Assert=]: |pendingAddedModules|'s [=list/size=] is 1.

1. Let |moduleURL| be |pendingAddedModules|[0].

1. Return |moduleURL|'s [=url/origin=].

......

### Monkey Patch for [=create a worklet global scope=] ### {#create-a-worklet-global-scope-monkey-patch}

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

5. Let <var ignore=''>insideSettings</var> be the result of [=setting up a worklet environment settings object=] given <var ignore=''>realmExecutionContext</var>, <var ignore=''>outsideSettings</var>, and |worklet|.

### Monkey Patch for [=fetch a worklet script graph=] ### {#fetch-a-worklet-script-graph-monkey-patch}

The algorithm [=fetch a worklet script graph=] calls into the <a href="https://html.spec.whatwg.org/multipage/webappapis.html#fetch-a-worklet/module-worker-script-graph">fetch a worklet/module worker script graph</a> 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|, ...":

5. If <var ignore=''>fetchClient</var>'s [=environment settings object/global object=] is {{SharedStorageWorkletGlobalScope}}:

1. Set |request|'s [=request/redirect mode=] to "<code>error</code>".

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 [=realm/settings object=]'s [=environment settings object/origin=] (as described in [[#set-up-a-worklet-environment-settings-object-monkey-patch]]) 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 [=realm/settings object=]'s [=environment settings object/origin=] should be updated to return the final request's [=request/URL=]'s [=url/origin=] after receiving the final request's response, and the user preference checkings shall only be done after that point.

<h4 id="shared-storage-cross-origin-worklet-allowed">The \`<dfn export http-header><code>Shared-Storage-Cross-Origin-Worklet-Allowed</code></dfn>\` HTTP response header</h4>

The \`<a http-header><code>Shared-Storage-Cross-Origin-Worklet-Allowed</code></a>\` HTTP response header, along with the traditional CORS headers, can be used to grant a cross-origin site the permission to create a worklet under the module script's [=/URL=]'s [=url/origin=], and to run subsequent operations on the worklet.

Cross-origin worklets rely on CORS as a baseline permission mechanism to indicate trusted external origins. However, CORS alone is insufficient for worklet creation. Unlike simple resource sharing, worklets allow the creator site to execute JavaScript within the context of the target origin. To ensure security, an additional header, \`<a http-header><code>Shared-Storage-Cross-Origin-Worklet-Allowed</code></a>\`, is required.

### Monkey Patch for [=HTTP fetch=] ### {#http-fetch-monkey-patch}

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, ..."):

1. If |request|'s [=request/destination=] is "sharedstorageworklet":

1. [=Assert=]: |request|'s [=request/origin=] is not "<code>client</code>".

1. If |request|'s [=request/origin=] and |request|'s [=request/URL=]'s [=url/origin=] are not [=same origin=]:

1. Let |headers| be |internalResponse|'s [=response/header list=].

1. Let |allowed| be the result of running [=get a structured field value=] algorithm given \`<a http-header><code>Shared-Storage-Cross-Origin-Worklet-Allowed</code></a>\`, "item", and |headers| as input.

1. 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 [=url/origin=] and the worklet's creator {{Window}} origin are not [=same origin=], by sending permissive CORS headers and the \`<a http-header><code>Shared-Storage-Cross-Origin-Worklet-Allowed</code></a>\` header on the module script response, the server will be granting the worklet's creation and subsequent operations on the worklet. For example, the worklet's creator {{Window}} could poison and use up the worklet origin's [=remaining navigation budget=] by calling {{SharedStorageWorklet/selectURL()}} or {{SharedStorageWorklet/run()}}, where the worklet origin is the global scope's [=global object/realm=]'s [=realm/settings object=]'s [=environment settings object/origin=].

### Monkey Patch for {{Worklet/addModule()}} ### {#add-module-monkey-patch}

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

4. 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 <var ignore=''>moduleURLRecord</var>.

1. If |addModuleAllowedResult| is "DisallowedDueToNonPreferenceError":

1. Return [=a promise rejected with=] a {{TypeError}}.

1. Else if |addModuleAllowedResult| is "DisallowedDueToPreferenceError":

1. If |this|'s [=SharedStorageWorklet/is cross-origin worklet=] is false, then return [=a promise rejected with=] a {{TypeError}}.

1. Else:

1. [=Assert=]: |addModuleAllowedResult| is "Allowed".

<div class="note">

On user preferences error, {{Worklet/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 {{SharedStorageWorklet/selectURL()}} and {{SharedStorageWorklet/run()}}.

</div>

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

2. 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|.

<span class=todo>Add additional monkey patch pieces for out-of-process worklets.</span>

## The {{SharedStorageWorkletGlobalScope}} ## {#global-scope}

The {{SharedStorageWorklet}}'s [=worklet global scope type=] is {{SharedStorageWorkletGlobalScope}}.

The {{SharedStorageWorklet}}'s [=worklet destination type=] is "sharedstorageworklet".

### Monkey Patch for request [=request/destination=] ### {#request-destination-monkey-patch}

The fetch request's [=request/destination=] field should additionally include "sharedstorageworklet" as a valid value.

<xmp class='idl'>

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

</xmp>

<xmp class='idl'>

[Exposed=SharedStorageWorklet, Global=SharedStorageWorklet]

interface SharedStorageWorkletGlobalScope : WorkletGlobalScope {

undefined register(DOMString name,

Function operationCtor);

readonly attribute WorkletSharedStorage sharedStorage;

};

</xmp>

Each {{SharedStorageWorkletGlobalScope}} has an associated [=environment settings object=] <dfn for=SharedStorageWorkletGlobalScope>outside settings</dfn>, which is the associated {{SharedStorageWorklet}}'s [=relevant settings object=].

Each {{SharedStorageWorkletGlobalScope}} has an associated [=/boolean=] <dfn for=SharedStorageWorkletGlobalScope>addModule success</dfn>, which is initialized to false.

Each {{SharedStorageWorkletGlobalScope}} also has an associated <dfn for=SharedStorageWorkletGlobalScope>operation map</dfn>, which is a [=map=], initially empty, of [=strings=] (denoting operation names) to [=functions=].

Each {{SharedStorageWorkletGlobalScope}} also has an associated {{WorkletSharedStorage}} instance, with the [=SharedStorageWorkletGlobalScope/sharedStorage getter=] algorithm as described below.

## {{SharedStorageWorkletGlobalScope}} algorithms ## {#scope-algo}

<div algorithm>

The <dfn method for="SharedStorageWorkletGlobalScope">register(|name|, |operationCtor|)</dfn> method steps are:

1. If |name| is missing or empty, throw a {{TypeError}}.

1. Let |operationMap| be this {{SharedStorageWorkletGlobalScope}}'s [=SharedStorageWorkletGlobalScope/operation map=].

1. If |operationMap| [=map/contains=] an [=map/entry=] with [=map/key=] |name|, throw a {{TypeError}}.

1. If |operationCtor| is missing, throw a {{TypeError}}.

1. Let |operationClassInstance| be the result of [=constructing=] |operationCtor|, with no arguments.

1. Let |runFunction| be [=Get=](|operationClassInstance|, "`run`"). Rethrow any exceptions.

1. Let |runIDLFunction| be the result of [=converting=] |runFunction| to a Web IDL {{RunFunctionForSharedStorageSelectURLOperation}} instance.

1. [=map/Set=] the value of |operationMap|[|name|] to |runIDLFunction|.

</div>

Issue(151): The "name" and "operationCtor" cannot be missing here given WebIDL. Should just check for default/empty values.

<div algorithm>

The <dfn for="SharedStorageWorkletGlobalScope">{{SharedStorageWorkletGlobalScope/sharedStorage}} getter</dfn> steps are:

1. If [=this=]'s [=addModule success=] is true, return [=this=]'s {{SharedStorageWorkletGlobalScope/sharedStorage}}.

1. Otherwise, throw a {{TypeError}}.

</div>

<div algorithm>

To <dfn for="SharedStorageWorkletGlobalScope">check whether addModule is finished</dfn>, the step is:

1. Return the value of [=addModule success=].

</div>

## {{SharedStorageUrlWithMetadata}} and Reporting ## {#reporting}

<xmp class='idl'>

dictionary SharedStorageUrlWithMetadata {

required USVString url;

object reportingMetadata;

};

</xmp>

If a {{SharedStorageUrlWithMetadata}} [=dictionary=] contains a non-[=map/empty=] {{SharedStorageUrlWithMetadata/reportingMetadata}} {{/object}} in the form of a [=dictionary=] whose [=map/keys=] are {{FenceEvent}}'s {{FenceEvent/eventType}}s and whose [=map/values=] are [=strings=] that parse to valid [=/URLs=], then these {{FenceEvent/eventType}}-[=/URL=] pairs will be [=register reporting metadata|registered=] for later access within any [=fenced frame=] that loads the {{SharedStorageResponse}} resulting from this {{SharedStorageWorklet/selectURL()}} call.

Issue(141): {{SharedStorageUrlWithMetadata/reportingMetadata}} should be a [=dictionary=].

Inside a [=fenced frame=] with {{FenceEvent/eventType}}-[=/URL=] pairs that have been [=register reporting metadata|registered=] through {{SharedStorageWorklet/selectURL()}} with {{SharedStorageUrlWithMetadata/reportingMetadata}} {{/object}}s, if {{reportEvent()}} is called on a {{FenceEvent}} with a {{FenceEvent/destination}} [=list/containing=] "`shared-storage-select-url`" and that {{FenceEvent}}'s corresponding {{FenceEvent/eventType}} is triggered, then the {{FenceEvent}}'s {{FenceEvent/eventData}} will be sent as a [=beacon=] to the registered [=/URL=] for that {{FenceEvent/eventType}}.

<div algorithm>

To <dfn>validate reporting metadata</dfn>, given an {{/object}} |reportingMetadata|, run the following steps:

1. If |reportingMetadata| is not a [=dictionary=], return false.

1. If |reportingMetadata| is [=map/empty=], return true.

1. [=map/iterate|For each=] <var ignore="">eventType</var> → |urlString| of |reportingMetadata|, if the result of running [=get the canonical URL string if valid=] with |urlString| is undefined, return false.

1. Return true.

</div>

<div algorithm>

To <dfn>get the canonical URL string if valid</dfn>, given a [=string=] |urlString|, run the following steps:

1. Let |url| be the result of running a [=URL parser=] on |urlString|.

1. If |url| is not a valid [=/URL=], return undefined.

1. Otherwise, return the result of running a [=URL serializer=] on |url|.

</div>

<div algorithm>

To <dfn>register reporting metadata</dfn>, given an {{/object}} |reportingMetadata| and a [=fenced frame config=] |fencedFrameConfigStruct|, run the following steps:

1. If |reportingMetadata| is [=map/empty=], return.

1. [=Assert=]: |reportingMetadata| is a [=dictionary=].

1. Let |reportingUrlMap| be an [=map/empty=] [=map=].

1. [=map/iterate|For each=] |eventType| → |urlString| of |reportingMetadata|:

1. Let |url| be the result of running a [=URL parser=] on |urlString|.

1. [=Assert=]: |url| is a valid [=/URL=].

1. [=map/Set=] |reportingUrlMap|[|eventType|] to |url|.

Issue(144): Store |reportingUrlMap| inside a [=fenced frame reporter=] class associated with |fencedFrameConfigStruct|. Both of these still need to be added to the draft [[Fenced-Frame]].

</div>

## Entropy Budgets ## {#budgets}

Because [=bits of entropy=] can leak via {{SharedStorageWorklet/selectURL()}}, the [=user agent=] will need to maintain budgets to limit these leaks.

### Navigation Entropy Budget ### {#nav-budget}

If a user [=user activation|activates=] a [=fenced frame=] whose [=Node/node document=]'s [=Document/browsing context=]'s [=browsing context/fenced frame config instance=] was generated by {{SharedStorageWorklet/selectURL()}} and thereby initiates a [=top-level traversable=] [=navigate|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 {{SharedStorageWorklet/selectURL()}}. To mitigate this, a [=user agent=] will set a per-[=calling site=] [=navigation entropy allowance=].

A <dfn>calling site</dfn> for {{SharedStorageWorklet/selectURL()}} is a [=site=].

A <dfn>navigation entropy allowance</dfn> is a maximum allowance of [=entropy bits=] that are permitted to leak via [=fenced frames=] initiating [=top-level traversable=] [=navigate|navigations=] during a given [=navigation budget epoch=] for a given calling [=calling site=]. This [=navigation entropy allowance|allowance=] is defined by the [=user agent=] and is [=calling site=]-agnostic.

A [=user agent=] will define a fixed predetermined [=duration=] <dfn>navigation budget lifetime</dfn>.

An <dfn>navigation budget epoch</dfn> 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 <dfn>shared storage navigation budget table</dfn>, which is a [=map=] of [=calling sites=] to [=navigation entropy ledgers=].

An <dfn>navigation entropy ledger</dfn> is a [=/list=] of [=bit debits=].

A <dfn>bit debit</dfn> is a [=struct=] with the following [=struct/items=]:

<dl dfn-for="bit debit">

: <dfn>bits</dfn>

:: a double

: <dfn>timestamp</dfn>

:: a {{DOMHighResTimeStamp}} (from the [=Unix Epoch=])

</dl>

[=Bit debits=] whose [=bit debit/timestamps=] precede the start of the current [=navigation budget epoch=] are said to be <dfn for="bit debit">expired</dfn>.

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

A [=calling site=]'s <dfn for="calling site">remaining navigation budget</dfn> is the [=navigation entropy allowance=] minus any [=bit debits=] whose [=bit debit/timestamps=] are within the current [=navigation budget epoch=].

{{SharedStorageWorklet/selectURL()}}'s argument "`urls`" is its <dfn for=selectURL>input URL list</dfn>.

When a [=calling site=] has insufficient [=calling site/remaining navigation budget=], {{SharedStorageWorklet/selectURL()}} will return a {{SharedStorageResponse}} (i.e. either a {{FencedFrameConfig}} or a [=urn uuid=]) for the {{SharedStorageUrlWithMetadata/url}} in the {{SharedStorageUrlWithMetadata}} at the [=default index=] in its [=selectURL/input URL list=].

The <dfn>default index</dfn> for a call to {{SharedStorageWorklet/selectURL()}} is [=implementation-defined=] in such a way that it is independent from the result of the registered operation class's "`run`" method.

Issue(147): Methods can't have state attached to them. Many definitions in this section needs improving.

<div class="example">

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 [=calling site/remaining navigation budget=], the "`run`" method would return 0, and hence {{SharedStorageWorklet/selectURL()}} would return a {{SharedStorageResponse}} for the first {{SharedStorageUrlWithMetadata/url}} in its [=selectURL/input URL list=].

</div>

<div class="example">

The [=default index=] could be defined to be [=selectURL/input URL list=]'s [=list/size=] &minus; 1.

In this case, whenever the registered operation class's "`run`" method encounters an error, or whenever there is insufficient [=calling site/remaining navigation budget=], {{SharedStorageWorklet/selectURL()}} would return a {{SharedStorageResponse}} for the last {{SharedStorageUrlWithMetadata/url}} in its [=selectURL/input URL list=].

</div>

<div algorithm>

To <dfn>determine remaining navigation budget</dfn>, given an [=environment settings object=] |environment| and a [=calling site=] |site|, run the following steps:

1. [=Assert=]: |site| is not an [=opaque origin=].

1. Let |maxBits| be the [=user agent=]'s [=navigation entropy allowance=].

1. If the [=user agent=]'s [=shared storage navigation budget table=] does not [=map/contain=] |site|, then return |maxBits|.

1. Otherwise, let |ledger| be [=user agent=]'s [=shared storage navigation budget table=][|site|].

1. Let |debitSum| be 0.

1. [=map/iterate|For each=] [=list/item=] |bitDebit| in |ledger|, do the following steps:

1. Let |debit| be |bitDebit|'s [=bit debit/bits=].

1. If the result of running [=check whether a bit debit is expired=] with |environment| and |bitDebit| is false, then increment |debitSum| by |debit|.

1. Return |maxBits| &minus; |debitSum|.

</div>

<div algorithm>

To <dfn>check whether a bit debit is expired</dfn>, given an [=environment settings object=] |environment| and a [=bit debit=] |bitDebit|, run the following steps:

1. Let |epochLength| be the [=user agent=]'s [=navigation budget lifetime=].

1. Let |currentTime| be |environment|'s [=environment settings object/current wall time=].

1. Let |threshold| be |currentTime| &minus; |epochLength|.

1. If |bitDebit|'s [=bit debit/timestamp=] is less than |threshold|, return true.

1. Otherwise, return false.

</div>

A [=bit debit=] will need to be [=charge shared storage navigation budget|charged=] to the [=shared storage navigation budget table=] for each [=top-level traversable=] [=navigate|navigation=] initiated by a [=fenced frame=] whose [=Node/node document=]'s [=Document/browsing context=]'s [=browsing context/fenced frame config instance=] was generated via {{SharedStorageWorklet/selectURL()}}, as this can leak cross-site data. Since the [=bit debit/bits=] to charge is calculated during the call to {{SharedStorageWorklet/selectURL()}} but only actually recorded in the [=shared storage navigation budget table=] if and when the resulting fenced frame initiates a [=top-level traversable=] [=beginning navigation|navigation=], the [=bit debit/bits=] must be stored as a <dfn>pending shared storage budget debit</dfn> in the corresponding fenced frame's [=Node/node document=]'s [=Document/browsing context=]'s [=browsing context/fenced frame config instance=] until this time.

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

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

Issue(138): Need to find a better way to specify timing of the navigation budget charging.

Issue(149): The boolean <dfn>shared storage navigation budget charged</dfn> 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.

<div algorithm>

To <dfn>charge shared storage navigation budget</dfn> during a [=beginning navigation|navigation=] with [=/navigable=] |navigable| and {{Document}} |sourceDocument|, run the following steps:

1. If |navigable| is not a [=top-level traversable=], return.

1. Let |currentNavigable| be |sourceDocument|'s [=node navigable=].

1. While |currentNavigable| is not null:

1. Let |site| be the result of running [=obtain a site=] with |currentNavigable|'s [=active document=]'s [=Document/origin=].

1. Let |instance| be |currentNavigable|'s [=Node/node document=]'s [=Document/browsing context=]'s [=browsing context/fenced frame config instance=].

1. Set |currentNavigable| to |currentNavigable|'s [=navigable/parent=].

1. If |instance| is null or |site| is an [=opaque origin=], then [=iteration/continue=].

1. Let |pendingBits| be |instance|'s [=pending shared storage budget debit=].

1. If |pendingBits| is not greater than 0, or if |instance|'s [=shared storage navigation budget charged=] is true, then [=iteration/continue=].

1. Let |ledger| be [=user agent=]'s [=shared storage navigation budget table=][|site|].

1. Let |bitDebit| be a new [=bit debit=].

1. Set |bitDebit|'s [=bit debit/bits=] to |pendingBits|.

1. Let |currentTime| be the [=/current wall time=].

1. Set |bitDebit|'s [=bit debit/timestamp=] to |currentTime|.

1. [=list/Append=] |bitDebit| to |ledger|.

1. Set |instance|'s [=shared storage navigation budget charged=] to true.

</div>

### Reporting Entropy Budget ### {#report-budget}

Likewise, each time a call to {{reportEvent()}} from a [=fenced frame=] originating via {{SharedStorageWorklet/selectURL()}} whose {{FenceEvent/destination}} [=list/contains=] "`shared-storage-select-url`" and whose {{FenceEvent/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 <dfn>page load</dfn> referring to a [=top-level traversable=]'s (i.e. primary main frame's) lifecycle.

A <dfn>reporting entropy allowance</dfn> is a maximum allowance of [=entropy bits=] that are permitted to leak via {{reportEvent()}} during a given page load. This [=reporting entropy allowance|allowance=] is defined by the [=user agent=].

Each [=top-level traversable=] will have a new {{double}} <dfn>shared storage reporting budget</dfn> 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 {{FenceEvent/destination}} [=list/containing=] "`shared-storage-select-url`", it will be necessary to [=charge shared storage reporting budget=] as below.

Issue(150): Move this to {{reportEvent()}} in [[Fenced-Frame]].

<div algorithm>

To <dfn>determine reporting budget to charge</dfn>, given a {{Document}} |sourceDocument|, run the following steps:

1. Let |debitSum| be 0.

1. Let |currentNavigable| be |sourceDocument|'s [=node navigable=].

1. While |currentNavigable| is not null:

1. Let |instance| be |currentNavigable|'s [=source snapshot params/initiator fenced frame config instance=].

1. Set |currentNavigable| to |currentNavigable|'s [=navigable/parent=].

1. If |instance| is null, then [=iteration/continue=].

1. Let |pendingBits| be |instance|'s [=pending shared storage budget debit=].

1. If |pendingBits| is greater than 0 and if |instance|'s [=shared storage reporting budget charged=] is false, increment |debitSum| by |pendingBits|.

1. Return |debitSum|.

</div>

Issue(149): The boolean <dfn>shared storage reporting budget charged</dfn> 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.

<div algorithm>

To <dfn>charge shared storage reporting budget</dfn> given a {{Document}} |sourceDocument|, run the following steps:

1. Let |toCharge| be the result of running [=determine reporting budget to charge=] with |sourceDocument|.

1. Let |currentNavigable| be |sourceDocument|'s [=node navigable=].

1. Let |topNode| be the result of running [=get the top-level traversable=] for |currentNavigable|.

1. If |topNode|'s [=shared storage reporting budget=] is less than |toCharge|, return false.

1. While |currentNavigable| is not null:

1. Let |instance| be |currentNavigable|'s [=Node/node document=]'s [=Document/browsing context=]'s [=browsing context/fenced frame config instance=].

1. 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.

1. Set |currentNavigable| to |currentNavigable|'s [=navigable/parent=].

1. Decrement |topNode|'s [=shared storage reporting budget=] by |toCharge|.

1. Return true.

</div>

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

<div algorithm>

To <dfn>purge expired bit debits from all navigation entropy ledgers</dfn>, run the following steps:

1. [=map/iterate|For each=] <var ignore="">origin</var> → |ledger| of [=user agent=]'s [=shared storage navigation budget table=]:

1. [=map/iterate|For each=] |bitDebit| in |ledger|, if the result of running [=check whether a bit debit is expired=] with |bitDebit| is true, [=list/remove=] |bitDebit| from |ledger|.

</div>

Shared Storage's Backend {#backend}

===================================

The Shared Storage API will integrate into the [=Storage Model|Storage API=] as below, via [=storage endpoint/registering=] a new [=storage endpoint=].

## Monkey Patch for the [=Storage Model=] ## {#storage-monkey-patch}

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 [=storage type|type=] "`shared`".

This standard will also [=storage endpoint/register=] a [=storage endpoint=] of [=storage type|type=] "`shared`" with [=storage identifier=] "`sharedStorage`" and [=storage endpoint/quota=] `5`^`4` `*` `2`^`16` bytes (i.e. 39.0625 mebibytes).

<span class=todo>This [=storage endpoint/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`^`20` bytes. For example, decreasing the per-origin entry limit from 10,000 to 1,280 would achieve this.</span>

A <dfn>shared storage shed</dfn> is a [=map=] of [=/origins=] to [=storage shelf|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 <dfn>shared storage</dfn> data.

<div algorithm>

To <dfn>obtain a shared storage shelf</dfn>, given a [=shared storage shed=] |shed|, an [=environment settings object=] |environment|, and an [=/origin=] |origin|, run these steps:

1. Let |allowedInOpaqueOriginContext| be false.

1. If the result of running [=determine whether shared storage is allowed by context=] given |environment|, |origin|, and |allowedInOpaqueOriginContext| is false, then return failure.

1. If the result of running [=determine whether shared storage is allowed by enrollment and user preference=] given |environment| and |origin| is false, then return failure.

1. If |shed|[origin] does not exist, then set |shed|[origin] to the result of running [=create a shared storage shelf=] with [=storage type|type=] "`shared`".

1. Return |shed|[|origin|].

</div>

<div algorithm>

To <dfn>create a shared storage shelf</dfn>, run these steps:

1. Let |shelf| be a new [=storage shelf=].

1. Set |shelf|'s [=bucket map=]["`default`"] to the result of running [=create a shared storage bucket=].

1. Return |shelf|.

</div>

A <dfn>shared storage bucket</dfn> is a [=storage bucket=] in one of a [=shared storage shed=]'s [=storage shelf|shelves=].

<div algorithm>

To <dfn>create a shared storage bucket</dfn>, run these steps:

1. Let |endpoint| be the [=storage endpoint=] with [=storage identifier=] "`sharedStorage`".

1. Let |bucket| be a new [=shared storage bucket=].

1. Set |bucket|'s [=bottle map=]["`sharedStorage`"] to a new [=storage bottle=] whose [=storage bottle/quota=] is |endpoint|'s [=storage endpoint/quota=].

1. Return |bucket|.

</div>

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

<div algorithm>

To <dfn>obtain a shared storage bottle map</dfn>, given an [=environment settings object=] |environment| and an [=/origin=] |origin|, run these steps:

1. Let |shed| be the [=user agent=]'s [=shared storage shed=].

1. Let |shelf| be the result of running [=obtain a shared storage shelf=] with |shed|, |environment|, and |origin|.

1. If |shelf| is failure, then return failure.

1. Let |bucket| be |shelf|'s [=bucket map=]["`default`"].

1. Let |bottle| be |bucket|'s [=bottle map=]["`sharedStorage`"].

1. Let |proxyMap| be a new [=storage proxy map=] whose [=backing map=] is |bottle|'s [=map=].

1. [=set/Append=] |proxyMap| to |bottle|'s [=proxy map reference set=].

1. Return |proxyMap|.

</div>

## The [=Shared Storage Database=] ## {#database}

A [=/browsing context=] has an associated <dfn>shared storage database</dfn>, which provides methods to [=shared storage database/store an entry in the database|store=], [=shared storage database/retrieve an entry from the database|retrieve=], [=shared storage database/delete an entry from the database|delete=], [=shared storage database/clear all entries in the database|clear=], and [=shared storage database/purge expired entries from the database|purge expired=] data, and additional methods as below. The data in the [=shared storage database|database=] take the form of [=shared storage database/entry|entries=].

Each [=shared storage database=] has a <dfn for="shared storage database">shared storage database queue</dfn>, which is the result of [=start a new parallel queue|starting a new parallel queue=]. This [=shared storage database queue|queue=] is used to run each of the [=shared storage database=]'s methods when calls to them are initiated from that [=/browsing context=].

Each <dfn for="shared storage database">entry</dfn> consists of a [=entry/key=] and a [=entry/value struct=].

An [=shared storage database/entry=]'s <dfn for=entry>key</dfn> is a [=string=].

[=User agents=] may specify the <dfn for=key>maximum length</dfn> of a [=entry/key=].

Since [=entry/keys=] are used to organize and efficiently retrieve [=shared storage database/entry|entries=], [=entry/keys=] must appear at most once in any given [=shared storage database=].

An [=shared storage database/entry=]'s <dfn for=entry>value struct</dfn> is a [=struct=] composed of [=string=] <dfn for="value struct">value</dfn> and {{DOMHighResTimeStamp}} <dfn for="value struct">last updated</dfn> (from the [=Unix Epoch=]).

[=User agents=] may specify the <dfn for=value>maximum length</dfn> of a [=value struct/value=].

[=User agents=] may specify a <dfn>default entry lifetime</dfn>, the default [=duration=] between when an [=shared storage database/entry=] is [=shared storage database/store an entry in the database|stored=] and when it expires. If the [=user agent=] specifies a [=default entry lifetime=], then it should have a timer periodically [=shared storage database/purge expired entries from the database=].

## The [=Shared Storage Database|Database=] Algorithms ## {#database-algorithms}

<div algorithm>

To <dfn for="shared storage database">store an entry in the database</dfn>, given a [=shared storage database/shared storage database queue=] |queue|, a [=storage proxy map=] |databaseMap|, an [=environment settings object=] |environment|, a [=entry/key=] |key|, and a [=value struct/value=] |value|, run the following steps on |queue|:

1. Let |valueStruct| be a new [=entry/value struct=].

1. Set |valueStruct|'s [=value struct/value=] to |value|.

1. Let |currentTime| be the |environment|'s [=environment settings object/current wall time=].

1. Set |valueStruct|'s [=value struct/last updated=] to |currentTime|.

1. [=map/Set=] |databaseMap|[|key|] to |valueStruct|.

1. If [=an exception was thrown=], then return false.

Note: Errors with [=storage proxy map=] |databaseMap|'s methods are possible depending on its implementation.

1. Otherwise, return true.

</div>

<div algorithm>

To <dfn for="shared storage database">retrieve an entry from the database</dfn>, given a [=shared storage database/shared storage database queue=] |queue|, a [=storage proxy map=] |databaseMap|, an [=environment settings object=] |environment|, and a [=entry/key=] |key|, run the following steps on |queue|:

1. If |databaseMap| does not [=map/contain=] |key|, return undefined.

1. Let |valueStruct| be the result of running [=map/Get=] on |databaseMap| with |key|.

1. If [=an exception was thrown=], then return failure.

Note: Errors with [=storage proxy map=] |databaseMap|'s methods are possible depending on its implementation.

1. If the result of running [=shared storage database/determine whether an entry is expired=] with |environment| and |valueStruct| is true, return undefined.

1. Return |valueStruct|'s [=value struct/value=].

</div>

<div algorithm>

To <dfn for="shared storage database">delete an entry from the database</dfn>, given a [=shared storage database/shared storage database queue=] |queue|, a [=storage proxy map=] |databaseMap|, and a [=entry/key=] |key|, run the following steps on |queue|:

1. [=map/Remove=] |databaseMap|[|key|].

1. If [=an exception was thrown=], then return false.

Note: Errors with [=storage proxy map=] |databaseMap|'s methods are possible depending on its implementation.

1. Return true.

</div>

<div algorithm>

To <dfn for="shared storage database">clear all entries in the database</dfn>, given a [=shared storage database/shared storage database queue=] |queue| and a [=storage proxy map=] |databaseMap|, run the following steps on |queue|:

1. Run [=map/Clear=] on |databaseMap|.

1. If [=an exception was thrown=], then return false.

Note: Errors with [=storage proxy map=] |databaseMap|'s methods are possible depending on its implementation.

1. Return true.

</div>

<div algorithm>

To <dfn for="shared storage database">retrieve all entries from the database</dfn>, given a [=shared storage database/shared storage database queue=] |queue| and a [=storage proxy map=] |databaseMap|, run the following steps on |queue|:

1. Let |values| be the result of running [=map/getting the values=] on |databaseMap|.

1. If [=an exception was thrown=], then return failure.

Note: Errors with [=storage proxy map=] |databaseMap|'s methods are possible depending on its implementation.

1. Return |values|.

</div>

<div algorithm>

To <dfn for="shared storage database">count entries in the database</dfn>, given a [=shared storage database/shared storage database queue=] |queue| and a [=storage proxy map=] |databaseMap|, run the following steps on |queue|:

1. Let |size| be |databaseMap|'s [=map/size=].

1. If [=an exception was thrown=], then return failure.

Note: Errors with [=storage proxy map=] |databaseMap|'s members are possible depending on its implementation.

1. Return |size|.

</div>

<div algorithm>

To <dfn for="shared storage database">purge expired entries from the database</dfn>, given a [=shared storage database/shared storage database queue=] |queue|, a [=storage proxy map=] |databaseMap|, and an [=environment settings object=] |environment|, run the following steps on |queue|:

1. [=map/iterate|For each=] [=entry/key=] |key| in |databaseMap|:

1. Let |valueStruct| be the result of running [=map/Get=] on |databaseMap| with |key|.

1. If [=an exception was thrown=], then return false.

1. If the result of running [=shared storage database/determine whether an entry is expired=] with |environment| and |valueStruct| is true, [=map/Remove=] |databaseMap|[|key|].

1. If [=an exception was thrown=], then return false.

1. Return true.

</div>

<div algorithm>

To <dfn for="shared storage database">determine whether an entry is expired</dfn>, given an [=environment settings object=] |environment| and a [=entry/value struct=] |valueStruct|, run the following steps:

1. Let |lastUpdated| be |valueStruct|'s [=value struct/last updated=].

1. Let |lifetime| be [=user agent=]'s [=default entry lifetime=].

1. Let |expiration| be the sum of |lastUpdated| and |lifetime|.

1. Let |currentTime| be the |environment|'s [=environment settings object/current wall time=].

1. If |expiration| is less than or equal to |currentTime|, return true.

1. Otherwise, return false.

</div>

The {{SharedStorage}} Interface {#shared-storage-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. {{SharedStorageWorklet/selectURL()}} and {{SharedStorageWorklet/run()}}), along with the {{WindowSharedStorage/worklet}} attribute which is used to call {{Worklet/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 [=shared storage database|database=].

<xmp class='idl'>

[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;

};

</xmp>

## The {{WindowSharedStorage}} interface ## {#window}

The {{WindowSharedStorage}} interface is as follows.

<xmp class='idl'>