chromium/third_party/blink/public/common/storage_key/storage_key.h

// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef THIRD_PARTY_BLINK_PUBLIC_COMMON_STORAGE_KEY_STORAGE_KEY_H_
#define THIRD_PARTY_BLINK_PUBLIC_COMMON_STORAGE_KEY_STORAGE_KEY_H_

#include <iosfwd>
#include <optional>
#include <string>
#include <string_view>

#include "base/unguessable_token.h"
#include "net/base/isolation_info.h"
#include "net/base/schemeful_site.h"
#include "net/cookies/cookie_partition_key.h"
#include "net/cookies/site_for_cookies.h"
#include "third_party/blink/public/common/common_export.h"
#include "third_party/blink/public/mojom/storage_key/ancestor_chain_bit.mojom.h"
#include "url/origin.h"

namespace blink {

// A class used by Storage APIs as a key for storage. An entity with a given
// storage key may not access data keyed with any other storage key.
//
// When third party storage partitioning is disabled, a StorageKey is equivalent
// to an origin, which is how storage has historically been partitioned.
//
// When third party storage partitioning is enabled, a storage key additionally
// contains a top-level site and an ancestor chain bit (see below). This
// achieves partitioning of an origin by the top-level site that the frame is
// embedded in. For example, https://chat.example.net embedded in
// https://social-example.org is a distinct key from https://chat.example.net
// embedded in https://news-example.org.
//
// A key is a third-party key if its origin is not in its top-level site (or if
// its ancestor chain bit is `kCrossSite`; see below); otherwise the key is a
// first-party key and the ancestor chain bit is `kSameSite`.
//
// A corner-case is a first-party origin embedded in a third-party origin, such
// as https://a.com embedded in https://b.com in https://a.com. The inner
// `a.com` frame can be controlled by `b.com`, and is thus considered
// third-party. The ancestor chain bit tracks this status.
//
// Storage keys can also optionally have a nonce. Keys with different nonces are
// considered distinct, and distinct from a key with no nonce. This is used to
// implement iframe credentialless and other forms of storage partitioning.
// Keys with a nonce disregard the top level site and ancestor chain bit. For
// consistency we set them to the origin's site and `kCrossSite` respectively.
//
// Storage keys might have an opaque top level site (for example, if an
// iframe is embedded in a data url). These storage keys always have a
// `kCrossSite` ancestor chain bit as there is no need to distinguish their
// partitions based on frame ancestry.
//
// Storage keys might have a top level site and origin that don't match. These
// storage keys always have a `kCrossSite` ancestor chain bit.
//
// Storage keys might have an opaque origin (for example, data urls). These
// storage keys always have a `kCrossSite` ancestor chain bit as there is no
// need to distinguish their partitions based on frame ancestry. These storage
// keys cannot be serialized.
//
// For more details on the overall design, see
// https://docs.google.com/document/d/1xd6MXcUhfnZqIe5dt2CTyCn6gEZ7nOezAEWS0W9hwbQ/edit.
//
// This class is typemapped to blink.mojom.StorageKey, and should stay in sync
// with BlinkStorageKey
// (third_party/blink/renderer/platform/storage/blink_storage_key.h)
class BLINK_COMMON_EXPORT StorageKey { … };

}  // namespace blink

#endif  // THIRD_PARTY_BLINK_PUBLIC_COMMON_STORAGE_KEY_STORAGE_KEY_H_