Cross-Origin Storage

1. Introduction

This section is non-normative.

Storage is normally partitioned by origin to protect user security and privacy. That is the right default, but it is a poor fit for a narrow class of very large, highly popular, publicly-distributed resources — AI models, WebAssembly modules, JavaScript libraries, game engines, and large web fonts — that are, byte-for-byte, the same file no matter which site requested them. When two unrelated origins each depend on the same 8 GB model, origin-partitioned storage forces the user to download and retain that model twice, which is wasteful for the user’s bandwidth, storage, and battery, and for the network as a whole.

Cross-Origin Storage (COS) is a content-addressable cache, keyed by cryptographic hash rather than by URL, that lets a user agent share a single stored copy of such a resource across the origins that opt into using it. Storing a resource in COS is always an explicit, opt-in act by the storing origin, and a user agent may withhold confirming a resource’s presence even from origins that would otherwise be permitted to read it; see § 7 Privacy and security considerations.

The entry point for this specification is the requestFileHandle() method, exposed via crossOriginStorage:

const hash = {
  algorithm: 'SHA-256',
  value: '8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4',
};
try {
  const handle = await navigator.crossOriginStorage.requestFileHandle(hash);
  const file = await handle.getFile();
  // Do something with the file.
} catch (err) {
  if (err.name === 'NotFoundError') {
    // Not (disclosably) in Cross-Origin Storage; fetch from the network instead.
  }
}

This specification reuses FileSystemFileHandle, FileSystemWritableFileStream, and related infrastructure from the File System Standard [FS], scoped to a dedicated, cross-origin-shared file system rather than to a single origin’s private or user-visible file system.

This specification defines the imperative JavaScript API only. Related proposals integrate the same underlying cache into other host specifications — an HTML crossoriginstorage attribute on link and script, a crossOriginStorage JavaScript import attribute, a CSS cross-origin-storage() <request-url-modifier>, and a crossOriginStorage RequestInit option for fetch() — each defined in its own host specification; see § 8 Integration with other specifications.

2. Concepts

2.1. Hashes

A COS hash is a struct with the following items:

algorithm

A string naming a hash algorithm recognized by [WEBCRYPTO], for example "SHA-256".

value

A string that is a lowercase hexadecimal encoding of a digest produced by algorithm. For "SHA-256", this is 64 characters long.

The algorithm dictionary member is typed as a plain DOMString, not as a HashAlgorithmIdentifier, even though its value space is exactly the set of names accepted by [WEBCRYPTO]’s hash algorithms. A HashAlgorithmIdentifier is (object or DOMString) — it additionally admits an object, normalized by [WEBCRYPTO] into an Algorithm-shaped dictionary, so that callers can pass extra parameters to algorithms that need them (for example, {name: "HMAC", hash: "SHA-256"}). Hash algorithms take no such parameters, algorithm is stored, compared, and round-tripped as part of a content-addressable key rather than consumed once by a single operation, and every use in this specification’s examples is a bare string; admitting arbitrary objects here would add no capability while making equality and serialization needlessly complicated. DOMString is therefore the narrower and more correct type for this field.

Two COS hash values are equal if their algorithm values are an ASCII case-insensitive match and their value values are exactly equal.

Note: Unlike algorithm, whose case is not normatively constrained, value is already normatively lowercase (see above), so comparing it is a plain string comparison rather than an ASCII case-insensitive one.

A content-addressable store is one whose entries are keyed by the equality of a COS hash, rather than by URL or by name: two files with identical bytes and the same hash algorithm are the same entry, regardless of how many origins stored them or how many URLs they were fetched from.

2.2. COS entries

Each user agent has a single COS registry, a map from COS hash values to COS entry structs, shared by all origins that use Cross-Origin Storage. A COS entry has the following items:

hash

A COS hash.

bytes

Null, or a byte sequence whose digest under hash’s algorithm equals hash’s value. Null until a writer completes verification and storage.

state

Either "pending" or "written". An entry starts out "pending" and becomes "written" exactly once, when bytes is first set.

pending writer count

A non-negative integer, initially 0, counting outstanding writers — FileSystemFileHandle handles returned by complete a create request whose closing write has not yet settled. Used only to decide, in verify and store, whether a failed write is safe to clean up; see § 3.3 Creating and writing files.

origins

The declared sharing scope: either "*" (any origin), a list of origin strings (only those origins), or null (same-site origins only). Set by the first writer and upgradeable but never downgradeable.

storing origins

A set of origins that have each successfully completed writing this entry’s bytes at least once. Persisted across page loads and grows over time; never shrinks except as described in § 5.2 Eviction. An origin in storing origins may always obtain a handle for the entry via requestFileHandle(), independent of origins or whether the entry’s hash is on the Public Hash List (PHL). See § 3.4.1 Original storer access.

A user agent has an associated Cross-Origin Storage queue, which is the result of starting a new parallel queue. All operations on the COS registry are to be enqueued on this queue, so that they execute in the order they were enqueued and do not interleave.

2.3. The Public Hash List

Confirming that a hash is present in Cross-Origin Storage can itself leak information about a user’s browsing history (see § 7.2 Cross-site probing). This is a risk specifically for globally scoped entries — an entry whose origins is a list or null has already had its disclosure bounded by an explicit choice of the storing origin, but "*" potentially exposes an entry to any origin on the web. To bound that specific risk, a "*"-scoped resource is only disclosable to origins outside its storing origins if its hash clears an additional, independent gate: membership on the Public Hash List (PHL), a vendor-neutral, implementation-defined allowlist of COS hash values. A hash is admitted to the Public Hash List only once it clears a k-anonymity-style popularity bar — for example, appearing, byte-identical, across some minimum number of independent origins — so that confirming its presence in a shared cache is not informative about any individual user.

A COS hash hash is on the Public Hash List if hash equals an entry of the user agent’s current snapshot of the Public Hash List.

The retrieval protocol, update cadence, data format, popularity thresholds, and governance of the Public Hash List are designed in detail as a companion artifact to this specification, in the spirit of how the [URL] Standard’s public suffix list is a companion data file rather than normative prose — see the Public Hash List explainer in this repository. That design proposes governance by the WHATWG, modeled on the Public Suffix List’s cross-vendor, rolling-release precedent, and admission criteria keyed on independently corroborated ubiquity —​a concrete instance of the k-anonymity-style bar described above, applied once, offline, as part of how a hash is admitted, not as a check the user agent repeats per query. None of this is yet established outside this proposal. An early, non-normative code prototype of the list itself is maintained in this repository, at public-hash-list/implementation/ — a pragmatic interim home; a dedicated, cross-vendor repository remains the governance target described in the PHL explainer. This specification only depends on whether a hash is on the PHL, not on any particular retrieval mechanism or governance model, so it remains correct regardless of how that design evolves.

3. The CrossOriginStorageManager interface

[Exposed=(Window,Worker), SecureContext]
interface CrossOriginStorageManager {
  Promise<FileSystemFileHandle> requestFileHandle(
      CrossOriginStorageRequestFileHandleHash hash,
      optional CrossOriginStorageRequestFileHandleOptions options = {});
};

dictionary CrossOriginStorageRequestFileHandleHash {
  required DOMString value;
  required DOMString algorithm;
};

dictionary CrossOriginStorageRequestFileHandleOptions {
  boolean create = false;
  (DOMString or sequence<DOMString>) origins;
};

interface mixin NavigatorCrossOriginStorage {
  [SameObject, SecureContext] readonly attribute CrossOriginStorageManager crossOriginStorage;
};
Navigator includes NavigatorCrossOriginStorage;
WorkerNavigator includes NavigatorCrossOriginStorage;

Each Navigator and WorkerNavigator object has an associated CrossOriginStorageManager object. The crossOriginStorage getter steps are to return this’s associated CrossOriginStorageManager.

Each CrossOriginStorageManager object has an associated origin, set to this’s relevant settings object’s origin when the object is created.

Note: Taking the origin from the relevant settings object rather than from anything about the script itself has a consequence worth spelling out for workers. A worker created from a blob: URL has the origin of the context that created it, so it shares that origin’s Cross-Origin Storage view exactly: what such a worker writes, its creating page can read back, and what the page stored, the worker can read. The blob: URL is not an origin of its own, and revoking it does not detach the worker from that view. A worker created from a data: URL, by contrast, has an opaque origin. This specification does not currently define what requestFileHandle() does when the calling origin is opaque; the opaque origin rule in validate a COS request governs the origins a caller names, not the origin it speaks from. An opaque origin has no stable identity to key storing origins or same site comparisons on, so there is nothing meaningful for it to be granted.

3.1. The requestFileHandle() method

3.2. Reading files

3.3. Creating and writing files

A FileSystemFileHandle created by complete a create request has an associated requested origins, the value that verify and store will attempt to upgrade the entry’s origins to once the handle is successfully written through.

Every FileSystemFileHandle addressing a COS entry also has an associated COS origin, the origin that obtained it, and an associated may read boolean, which governs whether getFile() may disclose the entry’s bytes through that particular handle. It is true for a handle returned by complete a read request, which has already passed availability gating, and false for a handle returned by complete a create request until verify and store succeeds for that same handle.

Note: This is deliberately a property of the handle rather than of the entry. A create request returns a handle whether or not the entry already exists and is already "written" (see complete a create request), so a per-entry rule would let any origin call requestFileHandle() with create: true and immediately read an entry it never wrote, learning its contents without satisfying origins, PHL membership, or GREASE’ing. Every disclosure control in this specification is applied on the read path, so gating per entry would let a create request walk around all of them. Requiring the caller to supply the correct bytes first means a successful read through a create-obtained handle discloses nothing the caller did not already have.

When the FileSystemWritableFileStream obtained by calling createWritable() on a handle whose locator addresses a COS entry is closed [FS], the user agent must run the verify and store steps below before that closing operation’s promise is fulfilled.

Note: This applies regardless of how closing was triggered — an explicit close() call, or a pipeTo() call that reaches the end of its source, which by default also closes its destination. [STREAMS] does not distinguish the two at the point a stream becomes closed, and neither does this algorithm.

createWritable() called on a FileSystemFileHandle addressing a COS entry must produce a FileSystemWritableFileStream whose contents start empty, regardless of the value of keepExistingData and regardless of the addressed entry’s state.

Note: [FS] otherwise defines keepExistingData as seeding the stream with the existing file’s contents. Honoring that here would let a caller become a storing origin for bytes it never possessed. A create request returns a handle whether or not the entry already exists, so a caller could open a writable for a hash another origin stored, close it having written nothing, and have the carried-over bytes hash to the requested value. That would grant it read access with origins, the Public Hash List and GREASE’ing never consulted — an availability gating bypass assembled out of two individually permitted operations. It is the same reasoning that makes verify and store require the complete contents on every create request.

Note: A writable closed without any write therefore holds the empty byte sequence, which will not hash to the requested value for any entry a caller would want, so verify and store rejects with a "DataError" DOMException as it does for any other mismatch. An implementation that instead reports a storage or I/O failure for that case hides a verification result behind an unrelated error.

The File System Standard [FS] does not yet define an extension point for a dependent specification to hook additional per-write validation into FileSystemWritableFileStream’s closing steps. Until such a hook exists, this section describes the required behavior directly; a future revision is expected to formally integrate with [FS].

3.4. Resource visibility upgrades

The visibility of a COS entry can be upgraded but never downgraded.

Note: A new site — not only the original storer — can widen an entry’s origins, as long as it also supplies bytes that hash to the entry’s hash. This is intentional: any site that already possesses the correct bytes for a hash is, by construction, as authoritative as the original storer about what that hash denotes.

3.4.1. Original storer access

An origin that has successfully completed writing a COS entry — that is, any origin in the entry’s storing origins — can always subsequently obtain a handle for it via requestFileHandle(), independent of the entry’s origins value and independent of whether its hash is on the PHL. This mirrors the Cache API’s model, in which an origin always has access to what it stored.

4. The Cross-Origin Storage file system

The Cross-Origin Storage file system is a file system root, distinct from any origin’s bucket file system or local file system access roots, whose entries correspond one-to-one with the COS registry’s COS entry items.

The Cross-Origin Storage file system does not use [FS]’s ordinary per-call permission-check model: every FileSystemFileHandle obtained from it has already been fully authorized by § 3.2 Reading files or § 3.3 Creating and writing files before it is returned to script, so calling getFile() or createWritable() on such a handle never triggers an additional permission prompt.

queryPermission() and requestPermission() on such a handle must therefore never report "prompt", since no prompt can appear. They must report "denied" for a write mode on a handle that was not obtained by a create request, and "granted" otherwise.

Note: Writing is the one capability a handle can genuinely lack. Only a create request yields a handle that can be written through, so reporting "granted" for a write mode on any other handle would claim a capability createWritable() will refuse. Reading stays "granted", since a caller holding a readable handle can read through it. Requesting cannot change either answer, as there is no prompt to show and no state a grant could be recorded in.

Calling getFile() on a FileSystemFileHandle addressing a COS entry whose may read is false must reject with a "NotAllowedError" DOMException. This covers two distinct cases:

• A handle from a create request whose entry is still "pending", for the same reason a concurrent requestFileHandle() call for the same hash rejects (see § 3.2 Reading files): the caller must not be able to observe a not-yet-verified placeholder as if it were the file’s real contents.

• A handle from a create request for an entry that some other origin has already written. The entry’s state is "written", but this caller has not supplied the bytes and has not passed availability gating, so it must learn nothing about the entry — including whether it exists.

Once a handle’s may read is true, getFile() called on it returns a File whose contents are the addressed entry’s bytes; this is exactly the behavior [FS] already defines for a file entry whose binary data is those bytes.

A FileSystemFileHandle addressing a COS entry has a file system locator whose path is a list containing a single string, the entry’s COS hash’s value, and whose root is the Cross-Origin Storage file system.

Note: [FS] defines name as the last path component of the handle’s locator’s path, so this settles name rather than leaving it to be chosen: it is the hash. An entry has no name of its own, and the hash is the only identity it has, so reporting it carries information the empty string would discard.

An entry has no name and no containing directory, so most of [FS]’s structural surface has nothing to act on. Identity is the exception, and it is the one question a content-addressed entry can always answer: the COS registry holds at most one COS entry per COS hash, so two handles address the same entry exactly when their hashes are equal.

isSameEntry() called on a FileSystemFileHandle addressing a COS entry, with an argument that also addresses a COS entry and was obtained by the same origin, must return true if the two handles' COS hash items are equal, and false otherwise.

Note: Refusing this would discard information the user agent already holds.

isSameEntry() called with an argument the calling origin did not obtain, or one addressing a file system other than the Cross-Origin Storage file system, must reject.

Note: Returning false in that case would assert that the two handles address different entries, which is a claim about a handle the calling origin is not entitled to inspect. Rejecting says only that the comparison could not be made.

move() and remove() called on a FileSystemFileHandle addressing a COS entry must reject with a "NotAllowedError" DOMException, and must leave the entry unchanged.

Note: An entry is shared by every origin in its storing origins, so honoring a removal would let one site destroy data other sites depend on; deletion belongs to eviction and to the user’s own storage controls. A rename or a reparent has nothing to act on, since an entry is named by its COS hash and has no containing directory.

Note: Neither method is defined by [FS] or by the File System Access API at the time of writing (WICG/file-system-access#214), so the error name follows removeEntry(), the operation [FS] does define for deleting an entry: it rejects with the access result’s error name when readwrite access is not granted. Refused rather than absent is the accurate reading here — the operations are meaningful and denied.

createSyncAccessHandle() needs no rule here: its steps reject with an "InvalidStateError" DOMException whenever the handle is not in a bucket file system, and the Cross-Origin Storage file system is a file system root distinct from any origin’s, so [FS] already determines both the refusal and its name.

Note: That is also the outcome this specification would want independently. A FileSystemSyncAccessHandle hands the caller a writable file descriptor, which would let it change an entry’s bytes out from under the COS hash they are stored against, and every other origin the entry is disclosable to reads those same bytes.

4.1. Transferring handles

A FileSystemFileHandle is a serializable object [FS], so one addressing a COS entry can be passed to another environment settings object, for example with postMessage(message, options). That is a second way to come by such a handle, alongside requestFileHandle(), so it is constrained here as well.

The serialization steps for a FileSystemFileHandle addressing a COS entry, given value and serialized, additionally:

1. Set serialized.[[COSOrigin]] to value’s COS origin.

2. Set serialized.[[COSMayRead]] to value’s may read.

The deserialization steps, given serialized, value and realm, additionally:

1. If serialized.[[COSOrigin]] is not same origin with realm’s environment settings object’s origin, then throw a "DataCloneError" DOMException.

2. Set value’s COS origin to serialized.[[COSOrigin]].

3. Set value’s may read to serialized.[[COSMayRead]].

Note: Without the same origin check, transferring would defeat every disclosure control in this specification at once. A handle whose may read is true has already cleared apply availability gating for the origin that requested it; posting it to another origin would hand that origin the entry’s bytes without origins, PHL membership or GREASE’ing ever being evaluated for it. This matches the File System Standard’s existing treatment of handles, which are likewise only useful to a same origin recipient.

Note: may read travels with the handle rather than being recomputed, so a create-request handle that has not been written through stays unreadable after a transfer, and a read-request handle stays readable without being re-gated. Re-gating on arrival would be worse, not better: it would let a caller probe availability repeatedly by transferring the same handle.

5. Storage management

5.1. Storage limits

A user agent must impose a limit on the total number of bytes an origin may contribute to the COS registry through successful writes, to prevent a single origin from flooding the cache in an attempt to evict other origins' entries. The specific limit is implementation-defined. If an origin’s write would exceed its limit, the user agent must reject the write with a "QuotaExceededError" DOMException and should log a warning to the console.

Note: Because entries are content-addressable, an origin that repeatedly writes the same bytes under the same hash does not consume additional quota beyond the first successful write; see § 2.2 COS entries.

A user agent also has an implementation-defined maximum origins list length, a positive integer bounding how many origins a single origins list may contain. This is enforced both when a list is first supplied (see validate a COS request) and when one is later merged into an existing entry (see upgrade resource visibility), so that neither a single call nor the cumulative effect of many calls over time can grow an entry’s origins without bound. Beyond bounding memory use, this also keeps a list of origins from being usable as an undeclared substitute for "*"; see § 7.2 Cross-site probing.

Exceeding this limit is handled differently in each of those two places, because the two calls happen at very different points in an operation:

• In validate a COS request, the limit is checked before any file is fetched, hashed, or written. A caller that exceeds it gets an immediate "TypeError" and nothing else happens —​the same treatment as any other malformed origins value.

• In upgrade resource visibility, the limit can only be reached by the cumulative effect of origins requested across separate, independent write calls, possibly by unrelated origins over a long period of time, and it is only checked after this call’s bytes have already been hashed, verified, and durably stored. Rejecting the write at that point would discard a successful, already-verified — and potentially very large — write over an unrelated bookkeeping limit, and would not even be attributable to a single caller’s mistake. The write is therefore left to succeed, and only the origins beyond capacity are dropped from origins, with a console warning. This mirrors the existing handling of a permissive-to-more-restricted request: an origin request that cannot be fully honored is silently capped rather than turned into a failure of the write that carried it. Consistent with § 7.3 Availability gating elsewhere in this specification, a caller has no reliable way to confirm after the fact whether its requested origin was actually added: a subsequent requestFileHandle() call as that origin can still fail even if the origin was added — for example because of GREASE’ing — so its result must not be read as confirmation either way.

5.2. Eviction

This section is non-normative.

Under storage pressure, a user agent may evict entries from the COS registry, for example using a least-recently-used policy across the storing origins that have most recently accessed each entry. A user agent is expected to provide settings UI through which a user can inspect which files are stored, which origins have accessed each file, and manually delete entries or clear all Cross-Origin Storage data.

When a user clears an origin’s site data, the user agent should remove that origin from every storing origins set it appears in. If, after that removal, a COS entry’s storing origins is empty, the user agent may consider that entry for deletion.

5.3. Manually added entries

This section is non-normative.

The settings UI described above may let a user directly add a file they already have on disk to Cross-Origin Storage — for example, an AI model they downloaded independently of any website —​without any script ever calling requestFileHandle(). Such an entry has no requesting origin to attribute the write to, which raises two questions the imperative API does not answer by itself:

• Who is the original storer, for the purposes of § 3.4.1 Original storer access? Nobody: the entry’s storing origins starts out empty, rather than containing an origin that performed the write. No origin is therefore exempt from the ordinary availability gating and origins checks that every requesting origin is otherwise subject to — which is the correct outcome, since no origin actually wrote the bytes.

• Should origins default to same-site-only, as it does for an ordinary write that omits origins? No: "same-site" is only meaningful relative to a requesting origin, and a manual add has none, so there is no site for "same-site" to mean. A user agent is expected to default such an entry’s origins to "*" instead, since manually seeding a file only serves its purpose — letting sites the user has not visited yet reuse a file the user already has on disk — if other origins can actually discover it. A user agent’s settings UI may additionally let the user choose a narrower scope.

Once added this way, an entry with state "written" is otherwise indistinguishable from one a website wrote via requestFileHandle(): the same availability gating and visibility upgrade rules apply to it, exactly as they would for any other entry with the same origins value — including the on the PHL check, if the entry ends up "*"-scoped, which is the default for a manual add but not the only possible outcome.

5.4. Provenance metadata

This section is non-normative.

A COS entry deliberately records nothing about where its bytes came from. Identity is the hash alone: the same bytes are the same entry regardless of how many origins stored them or how many URLs they were fetched from (see § 2.2 COS entries). A URL is a property of one writer’s fetch rather than of the entry, so there is no non-arbitrary way to pick one for an entry several origins wrote; it is not verifiable the way the bytes are (see § 7.1 Resource integrity); and it carries considerably more about a user’s browsing than the coarse origin values in storing origins do, since a path or query string can name a specific document, account, or session. Recording it on the entry would therefore route a high-entropy signal around the disclosure limits that origins and § 7.3 Availability gating exist to impose.

The motivation for wanting it is nonetheless real: a user looking at a multi-gigabyte file in the settings UI described in § 5.2 Eviction, and a developer debugging why a requestFileHandle() call missed, would both like to know where a file came from. A user agent may serve that by keeping an implementation-private provenance record alongside an entry — for example, the URL each of its storing origins fetched the bytes from, and when — provided the record is treated as user agent state rather than as part of the entry:

• It is never exposed to script. Nothing in this specification discloses it, and nothing added later should: neither requestFileHandle() nor the FileSystemFileHandle it returns should reveal whether such a record exists, let alone its contents. In particular, a requesting origin must not be able to observe a record it did not itself produce.

• It is surfaced only through trusted, non-web surfaces: the user agent’s own settings and storage inspection UI, its developer tools, and — where the user agent has an extension platform —​extension APIs gated behind an explicit, user-granted permission, on the same footing as other APIs that expose browsing history. See the browser extension integration points explainer in this repository for the extension surfaces being considered.

• It is unverified, and is presented as such. A URL in it is a claim by the origin that wrote the bytes, not an attestation about them — only the hash guarantees the content (see § 7.1 Resource integrity). Two origins may record different URLs for the same entry, and either may be inaccurate or deliberately misleading.

• It shares the lifetime of the entry, and of the origin it is attributed to. It is discarded when the entry is evicted or deleted, and the portion attributable to an origin is discarded when that origin is removed from storing origins, including when the user clears that origin’s site data (see § 5.2 Eviction).

Because such a record is invisible to content, whether a user agent keeps one, and how much it keeps, is left entirely to implementations. Nothing in this specification depends on it, and its presence or absence is not detectable by a site.

6. Permissions Policy integration

This specification defines a policy-controlled feature [permissions-policy] identified by the string "cross-origin-storage". Its default allowlist is self.

A Document that is not allowed to use this feature causes every requestFileHandle() call made from that Document (or from a worker whose owner is that Document) to reject with a "NotAllowedError" DOMException, before any hash validation, registry lookup, or write occurs.

7. Privacy and security considerations

This section is non-normative except where it uses RFC 2119 keywords; see also the security and privacy questionnaire in the repository.

7.1. Resource integrity

Every COS entry is keyed by, and its bytes are verified against, a cryptographic hash (see § 3.3 Creating and writing files). A site can therefore be sure that a file obtained through requestFileHandle() has exactly the same bytes it would have gotten by fetching hash itself. Developers cannot enumerate the contents of Cross-Origin Storage or access a file without already knowing its hash.

A COS hash is not a secret. It is a content identifier, trivially computable by anyone who already has the file, and is routinely public knowledge for the kind of widely distributed resources this specification targets — published, for example, alongside a model’s or a library’s release. Knowing a hash is therefore sufficient to look an entry up, but unlike a capability URL or a bearer token, it grants no access by itself: whether a lookup succeeds is governed entirely by origins and § 7.3 Availability gating, never by whether the hash happened to stay unpublished. Developers must not treat an unpublished hash as an access-control mechanism; an attacker interested in a specific file does not need to guess its hash, only to obtain the file itself (see § 7.2 Cross-site probing).

7.2. Cross-site probing

If a resource is only used by a narrow set of sites, an attacker able to learn that the resource is present in Cross-Origin Storage can infer that the user likely visited one of those sites. Because requestFileHandle() is the mechanism for learning presence, each call is, in effect, a probe. Two independent mechanisms in this specification bound what a probe can learn:

• origins (see § 3.4 Resource visibility upgrades) lets a storing origin restrict disclosure to a chosen set of origins, so a proprietary or low-popularity resource need not be globally probeable at all.

• § 7.3 Availability gating additionally withholds disclosure of a "*"-scoped resource from requesting origins outside its storing origins unless the hash is on the PHL, so that a resource stored with origins: "*" is not automatically probeable by every origin on the web. This gate applies only to "*"-scoped entries; for list- and same-site-scoped entries, the first bullet’s restriction is the sole gate, since the storing origin has already bounded disclosure explicitly for those.

The first bullet only holds if a "chosen set of origins" stays meaningfully smaller than the web. Nothing about the shape of origins stops a caller from enumerating a very large number of origins — for example, a list assembled from a public top-sites ranking — which would functionally approximate global disclosure while bypassing the deliberate, explicit opt-in that "*" alone requires. The maximum origins list length (see § 5.1 Storage limits) bounds this: a limit small enough to fit genuine multi-property use cases (a handful of related origins under common control) but far short of any meaningful approximation of "every origin" keeps the restricted-origins form of origins from being usable as an undeclared substitute for "*".

A user agent should additionally rate-limit or otherwise throttle repeated requestFileHandle() calls from a single origin, and may apply on-device heuristics (for example, detecting a pattern of requests for hashes that appear to be generated per-user) to identify and block probing attempts, independent of whether the probed hashes are on the PHL.

7.3. Availability gating

Whether a requestFileHandle() read from an origin outside storing origins succeeds always depends on whether the requesting origin is allowed to read the entry, governed by origins. For a "*"-scoped entry, a second, independent question also applies: whether the user agent is willing to disclose that the entry exists at all, governed by PHL membership and GREASE’ing. Both must hold for such an entry; for a list- or same-site-scoped entry, only the first question applies, though GREASE’ing may still suppress a disclosure that origins would otherwise permit. See § 3.2 Reading files for the normative algorithm. A "NotFoundError" is therefore not proof that a resource is absent: it may mean the resource does not exist, that the requesting origin is out of scope, that a "*"-scoped resource’s hash is not (yet, or ever) on the PHL, or that GREASE’ing suppressed a true positive. Developers must not treat "NotFoundError" as anything more specific than "fall back to the network."

Note: A "*"-scoped entry’s disclosure is additionally limited to requesting origins that can set or read third-party cookies in the current context; such an entry is not disclosed to an origin third-party cookies are unavailable to, regardless of PHL membership. This closes a gap PHL membership alone cannot: an attacker can build a cross-site identifier out of otherwise-ordinary, individually PHL-eligible resources by choosing which subset to write, and third-party cookie availability is the deciding factor in whether the resulting probe is any more informative than an ordinary tracking cookie would be.

7.4. GREASE’ing

A user agent may apply GREASE’ing (Generate Random Extensions And Sustain Extensibility): occasionally responding as if a disclosable entry were absent, even though § 7.3 Availability gating would otherwise permit disclosure. This adds noise that makes it harder for a site to distinguish a true absence from a privacy-motivated false negative, similar to the technique applied by UA Client Hints.

A user agent applying GREASE’ing must do so with judgement proportionate to the size of the entry in question. For small entries, where falling back to a network fetch is inexpensive, an occasional false negative is a reasonable privacy trade-off. A user agent must not apply GREASE’ing to entries whose size makes a spurious re-download clearly disproportionate to the resulting privacy benefit —​for example, gigabyte-scale AI model weights — because a false negative there forces a full, observable, and costly re-download rather than a cheap one.

7.5. Fingerprinting

The information an attacker can extract from probing Cross-Origin Storage is bounded by how popular the probed resource is. Learning that a user has a very popular resource, such as a common AI model or a widely used JavaScript library, reveals only that the user visited one of the (possibly very many) sites that use it. Learning that a user has a rare or unique resource is far more informative. A user agent is expected to apply on-device heuristics to detect resources whose hashes look deliberately unique per user (for example, a hash that has only ever been written by a single site, or that is requested with unusual frequency) and to treat such patterns as probing attempts, independent of nominal PHL status.

8. Integration with other specifications

This section is non-normative.

The COS registry defined here is also reachable from four host integrations without going through requestFileHandle() directly. Each integration is defined in its own host specification, not in this document; this specification defines only the shared underlying concepts (COS hash, COS entry, availability gating, and the Public Hash List) that those integrations are expected to build on.

• HTML: a crossoriginstorage attribute on link and script elements that already carry integrity [SRI], proposed to the WHATWG in whatwg/html#12770.

• JavaScript: a host-defined crossOriginStorage import attribute, usable alongside integrity, building on the Import Attributes proposal, proposed to the WHATWG in whatwg/html#12771.

• CSS: a cross-origin-storage() <request-url-modifier>, usable alongside integrity(), proposed to the CSS Working Group in w3c/csswg-drafts#14056.

• Fetch: a crossOriginStorage RequestInit option, usable alongside integrity [FETCH], proposed to the WHATWG in whatwg/fetch#1954. Unlike the three declarative forms, this one has no host-defined destination, so how a Response served from the COS registry reports its MIME type, status, and other metadata is an open question for that specification; a COS entry stores bytes only.

For illustration only, here is the same globally-shared resource opted into Cross-Origin Storage through each of the four forms:

<script src="popular-library.js" integrity="sha256-abc123..." crossoriginstorage="*"></script>

import data from "popular-resource.ext" with {
  integrity: "sha256-abc123...",
  crossOriginStorage: "*",
};

@font-face {
  font-family: "Popular Font";
  src: url("popular-font.woff2" integrity("sha256-abc123...") cross-origin-storage(*));
}

const response = await fetch("popular-resource.ext", {
  integrity: "sha256-abc123...",
  crossOriginStorage: "*",
});

These snippets are illustrative only. None of this syntax is defined by this specification, and the authoritative grammar for each form — including how a restricted, non-"*" origins value is spelled — belongs to its own host specification, not to this document. The spellings deliberately differ: a RequestInit member can take a sequence<DOMString>, matching origins exactly, while an attribute value, an import attribute value, and a CSS modifier argument can only carry text.

All four forms are expected to share the processing model of first consulting the COS registry for a matching, disclosable entry before falling back to a network fetch, and of storing a successfully fetched and integrity-verified resource into the COS registry for reuse by other origins, exactly as requestFileHandle() does. Discussion of these integrations belongs in the tracker of the host specification that would carry them, not in this repository’s issue tracker.

Acknowledgments

Many thanks for valuable feedback from Tab Atkins-Bittner, Yash Raj Bharti, and Joshua Lochner, and for valuable inspiration or ideas from Kenji Baheux and Kevin Moore.

This specification includes material modeled on File System, which is available under the W3C Software and Document License.