chrome.cookies
使用 chrome.cookies API 查询和修改 Cookie，并在 Cookie 发生更改时收到通知。
更多参考官网定义：chrome.cookies | API | Chrome for Developers (google.cn)
本文以加载一个清理cookies功能扩展为例 https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/cookies/cookie-clearer
摘自官网扩展例子：
manifest.json
{
"name": "Cookie Clearer",
"manifest_version": 3,
"version": "1.0",
"description": "Uses the chrome.cookies API by letting a user delete their cookies via a popup.",
"permissions": ["cookies"],
"host_permissions": ["<all_urls>"],
"action": {
"default_popup": "popup.html"
}
}
popup.js
const form = document.getElementById('control-row');
const input = document.getElementById('input');
const message = document.getElementById('message');
// The async IIFE is necessary because Chrome <89 does not support top level await.
(async function initPopupWindow() {
let [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
if (tab?.url) {
try {
let url = new URL(tab.url);
input.value = url.hostname;
} catch {
// ignore
}
}
input.focus();
})();
form.addEventListener('submit', handleFormSubmit);
async function handleFormSubmit(event) {
event.preventDefault();
clearMessage();
let url = stringToUrl(input.value);
if (!url) {
setMessage('Invalid URL');
return;
}
let message = await deleteDomainCookies(url.hostname);
setMessage(message);
}
function stringToUrl(input) {
// Start with treating the provided value as a URL
try {
return new URL(input);
} catch {
// ignore
}
// If that fails, try assuming the provided input is an HTTP host
try {
return new URL('http://' + input);
} catch {
// ignore
}
// If that fails ¯\_(ツ)_/¯
return null;
}
async function deleteDomainCookies(domain) {
let cookiesDeleted = 0;
try {
const cookies = await chrome.cookies.getAll({ domain });
if (cookies.length === 0) {
return 'No cookies found';
}
let pending = cookies.map(deleteCookie);
await Promise.all(pending);
cookiesDeleted = pending.length;
} catch (error) {
return `Unexpected error: ${error.message}`;
}
return `Deleted ${cookiesDeleted} cookie(s).`;
}
function deleteCookie(cookie) {
// Cookie deletion is largely modeled off of how deleting cookies works when using HTTP headers.
// Specific flags on the cookie object like `secure` or `hostOnly` are not exposed for deletion
// purposes. Instead, cookies are deleted by URL, name, and storeId. Unlike HTTP headers, though,
// we don't have to delete cookies by setting Max-Age=0; we have a method for that ;)
//
// To remove cookies set with a Secure attribute, we must provide the correct protocol in the
// details object's `url` property.
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure
const protocol = cookie.secure ? 'https:' : 'http:';
// Note that the final URL may not be valid. The domain value for a standard cookie is prefixed
// with a period (invalid) while cookies that are set to `cookie.hostOnly == true` do not have
// this prefix (valid).
// https://developer.chrome.com/docs/extensions/reference/cookies/#type-Cookie
const cookieUrl = `${protocol}//${cookie.domain}${cookie.path}`;
return chrome.cookies.remove({
url: cookieUrl,
name: cookie.name,
storeId: cookie.storeId
});
}
function setMessage(str) {
message.textContent = str;
message.hidden = false;
}
function clearMessage() {
message.hidden = true;
message.textContent = '';
}
popup.html
<!doctype html>
<html>
<head>
<script src="popup.js" type="module"></script>
</head>
<body>
<form id="control-row">
<label for="input">Domain:</label>
<input type="text" id="input" />
<br />
<button id="go">Clear Cookies</button>
</form>
<span id="message" hidden></span>
</body>
</html>
一、看下c++提供 的cookies接口定义 chrome\common\extensions\api\cookies.json
// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
[
{
"namespace": "cookies",
"description": "Use the <code>chrome.cookies</code> API to query and modify cookies, and to be notified when they change.",
"types": [
{
"id": "SameSiteStatus",
"type": "string",
"enum": ["no_restriction", "lax", "strict", "unspecified"],
"description": "A cookie's 'SameSite' state (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' corresponds to a cookie set with 'SameSite=None', 'lax' to 'SameSite=Lax', and 'strict' to 'SameSite=Strict'. 'unspecified' corresponds to a cookie set without the SameSite attribute."
},
{
"id": "CookiePartitionKey",
"type": "object",
"description": "Represents a partitioned cookie's partition key.",
"properties": {
"topLevelSite": {"type": "string", "optional": true, "description": "The top-level site the partitioned cookie is available in."}
}
},
{
"id": "Cookie",
"type": "object",
"description": "Represents information about an HTTP cookie.",
"properties": {
"name": {"type": "string", "description": "The name of the cookie."},
"value": {"type": "string", "description": "The value of the cookie."},
"domain": {"type": "string", "description": "The domain of the cookie (e.g. \"www.google.com\", \"example.com\")."},
"hostOnly": {"type": "boolean", "description": "True if the cookie is a host-only cookie (i.e. a request's host must exactly match the domain of the cookie)."},
"path": {"type": "string", "description": "The path of the cookie."},
"secure": {"type": "boolean", "description": "True if the cookie is marked as Secure (i.e. its scope is limited to secure channels, typically HTTPS)."},
"httpOnly": {"type": "boolean", "description": "True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts)."},
"sameSite": {"$ref": "SameSiteStatus", "description": "The cookie's same-site status (i.e. whether the cookie is sent with cross-site requests)."},
"session": {"type": "boolean", "description": "True if the cookie is a session cookie, as opposed to a persistent cookie with an expiration date."},
"expirationDate": {"type": "number", "optional": true, "description": "The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies."},
"storeId": {"type": "string", "description": "The ID of the cookie store containing this cookie, as provided in getAllCookieStores()."},
"partitionKey": {"$ref": "CookiePartitionKey", "optional": true, "description": "The partition key for reading or modifying cookies with the Partitioned attribute."}
}
},
{
"id": "CookieStore",
"type": "object",
"description": "Represents a cookie store in the browser. An incognito mode window, for instance, uses a separate cookie store from a non-incognito window.",
"properties": {
"id": {"type": "string", "description": "The unique identifier for the cookie store."},
"tabIds": {"type": "array", "items": {"type": "integer"}, "description": "Identifiers of all the browser tabs that share this cookie store."}
}
},
{
"id": "OnChangedCause",
"type": "string",
"enum": ["evicted", "expired", "explicit", "expired_overwrite", "overwrite"],
"description": "The underlying reason behind the cookie's change. If a cookie was inserted, or removed via an explicit call to \"chrome.cookies.remove\", \"cause\" will be \"explicit\". If a cookie was automatically removed due to expiry, \"cause\" will be \"expired\". If a cookie was removed due to being overwritten with an already-expired expiration date, \"cause\" will be set to \"expired_overwrite\". If a cookie was automatically removed due to garbage collection, \"cause\" will be \"evicted\". If a cookie was automatically removed due to a \"set\" call that overwrote it, \"cause\" will be \"overwrite\". Plan your response accordingly."
},
{
"id": "CookieDetails",
"type": "object",
"description": "Details to identify the cookie.",
"properties": {
"url": {"type": "string", "description": "The URL with which the cookie to access is associated. This argument may be a full URL, in which case any data following the URL path (e.g. the query string) is simply ignored. If host permissions for this URL are not specified in the manifest file, the API call will fail."},
"name": {"type": "string", "description": "The name of the cookie to access."},
"storeId": {"type": "string", "optional": true, "description": "The ID of the cookie store in which to look for the cookie. By default, the current execution context's cookie store will be used."},
"partitionKey": {"$ref": "CookiePartitionKey", "optional": true, "description": "The partition key for reading or modifying cookies with the Partitioned attribute."}
}
}
],
"functions": [
{
"name": "get",
"type": "function",
"description": "Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned.",
"parameters": [
{
"name": "details",
"$ref": "CookieDetails"
}
],
"returns_async": {
"name": "callback",
"parameters": [
{
"name": "cookie", "$ref": "Cookie", "optional": true, "description": "Contains details about the cookie. This parameter is null if no such cookie was found."
}
]
}
},
{
"name": "getAll",
"type": "function",
"description": "Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first. Only retrieves cookies for domains which the extension has host permissions to.",
"parameters": [
{
"type": "object",
"name": "details",
"description": "Information to filter the cookies being retrieved.",
"properties": {
"url": {"type": "string", "optional": true, "description": "Restricts the retrieved cookies to those that would match the given URL."},
"name": {"type": "string", "optional": true, "description": "Filters the cookies by name."},
"domain": {"type": "string", "optional": true, "description": "Restricts the retrieved cookies to those whose domains match or are subdomains of this one."},
"path": {"type": "string", "optional": true, "description": "Restricts the retrieved cookies to those whose path exactly matches this string."},
"secure": {"type": "boolean", "optional": true, "description": "Filters the cookies by their Secure property."},
"session": {"type": "boolean", "optional": true, "description": "Filters out session vs. persistent cookies."},
"storeId": {"type": "string", "optional": true, "description": "The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used."},
"partitionKey": {"$ref": "CookiePartitionKey", "optional": true, "description": "The partition key for reading or modifying cookies with the Partitioned attribute."}
}
}
],
"returns_async": {
"name": "callback",
"parameters": [
{
"name": "cookies", "type": "array", "items": {"$ref": "Cookie"}, "description": "All the existing, unexpired cookies that match the given cookie info."
}
]
}
},
{
"name": "set",
"type": "function",
"description": "Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.",
"parameters": [
{
"type": "object",
"name": "details",
"description": "Details about the cookie being set.",
"properties": {
"url": {"type": "string", "description": "The request-URI to associate with the setting of the cookie. This value can affect the default domain and path values of the created cookie. If host permissions for this URL are not specified in the manifest file, the API call will fail."},
"name": {"type": "string", "optional": true, "description": "The name of the cookie. Empty by default if omitted."},
"value": {"type": "string", "optional": true, "description": "The value of the cookie. Empty by default if omitted."},
"domain": {"type": "string", "optional": true, "description": "The domain of the cookie. If omitted, the cookie becomes a host-only cookie."},
"path": {"type": "string", "optional": true, "description": "The path of the cookie. Defaults to the path portion of the url parameter."},
"secure": {"type": "boolean", "optional": true, "description": "Whether the cookie should be marked as Secure. Defaults to false."},
"httpOnly": {"type": "boolean", "optional": true, "description": "Whether the cookie should be marked as HttpOnly. Defaults to false."},
"sameSite": {"$ref": "SameSiteStatus", "optional": true, "description": "The cookie's same-site status. Defaults to \"unspecified\", i.e., if omitted, the cookie is set without specifying a SameSite attribute."},
"expirationDate": {"type": "number", "optional": true, "description": "The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie."},
"storeId": {"type": "string", "optional": true, "description": "The ID of the cookie store in which to set the cookie. By default, the cookie is set in the current execution context's cookie store."},
"partitionKey": {"$ref": "CookiePartitionKey", "optional": true, "description": "The partition key for reading or modifying cookies with the Partitioned attribute."}
}
}
],
"returns_async": {
"name": "callback",
"optional": true,
"min_version": "11.0.674.0",
"parameters": [
{
"name": "cookie", "$ref": "Cookie", "optional": true, "description": "Contains details about the cookie that's been set. If setting failed for any reason, this will be \"null\", and $(ref:runtime.lastError) will be set."
}
]
}
},
{
"name": "remove",
"type": "function",
"description": "Deletes a cookie by name.",
"parameters": [
{
"name": "details",
"$ref": "CookieDetails"
}
],
"returns_async": {
"name": "callback",
"optional": true,
"min_version": "11.0.674.0",
"parameters": [
{
"name": "details",
"type": "object",
"description": "Contains details about the cookie that's been removed. If removal failed for any reason, this will be \"null\", and $(ref:runtime.lastError) will be set.",
"optional": true,
"properties": {
"url": {"type": "string", "description": "The URL associated with the cookie that's been removed."},
"name": {"type": "string", "description": "The name of the cookie that's been removed."},
"storeId": {"type": "string", "description": "The ID of the cookie store from which the cookie was removed."},
"partitionKey": {"$ref": "CookiePartitionKey", "optional": true, "description": "The partition key for reading or modifying cookies with the Partitioned attribute."}
}
}
]
}
},
{
"name": "getAllCookieStores",
"type": "function",
"description": "Lists all existing cookie stores.",
"parameters": [],
"returns_async": {
"name": "callback",
"parameters": [
{
"name": "cookieStores", "type": "array", "items": {"$ref": "CookieStore"}, "description": "All the existing cookie stores."
}
]
}
}
],
"events": [
{
"name": "onChanged",
"type": "function",
"description": "Fired when a cookie is set or removed. As a special case, note that updating a cookie's properties is implemented as a two step process: the cookie to be updated is first removed entirely, generating a notification with \"cause\" of \"overwrite\" . Afterwards, a new cookie is written with the updated values, generating a second notification with \"cause\" \"explicit\".",
"parameters": [
{
"type": "object",
"name": "changeInfo",
"properties": {
"removed": {"type": "boolean", "description": "True if a cookie was removed."},
"cookie": {"$ref": "Cookie", "description": "Information about the cookie that was set or removed."},
"cause": {"min_version": "12.0.707.0", "$ref": "OnChangedCause", "description": "The underlying reason behind the cookie's change."}
}
}
]
}
]
}
]
同时会生成
out\Debug\gen\chrome\common\extensions\api\cookies.h
out\Debug\gen\chrome\common\extensions\api\cookies.cc
此文件是cookies.json 定义的一个c++实现，自动生成请勿手动更改【tools\json_schema_compiler\compiler.py】。
二、cookies api接口定义：
chrome\browser\extensions\api\cookies\cookies_api.h
chrome\browser\extensions\api\cookies\cookies_api.cc
// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Defines the Chrome Extensions Cookies API functions for accessing internet
// cookies, as specified in the extension API JSON.
#ifndef CHROME_BROWSER_EXTENSIONS_API_COOKIES_COOKIES_API_H_
#define CHROME_BROWSER_EXTENSIONS_API_COOKIES_COOKIES_API_H_
#include <memory>
#include <string>
#include "base/memory/raw_ptr.h"
#include "base/values.h"
#include "chrome/browser/ui/browser_list_observer.h"
#include "chrome/common/extensions/api/cookies.h"
#include "extensions/browser/browser_context_keyed_api_factory.h"
#include "extensions/browser/event_router.h"
#include "extensions/browser/extension_function.h"
#include "mojo/public/cpp/bindings/receiver.h"
#include "mojo/public/cpp/bindings/remote.h"
#include "net/cookies/canonical_cookie.h"
#include "net/cookies/cookie_access_result.h"
#include "net/cookies/cookie_change_dispatcher.h"
#include "services/network/public/mojom/cookie_manager.mojom.h"
#include "third_party/abseil-cpp/absl/types/optional.h"
#include "url/gurl.h"
class Profile;
namespace extensions {
// Observes CookieManager Mojo messages and routes them as events to the
// extension system.
class CookiesEventRouter : public BrowserListObserver {
public:
explicit CookiesEventRouter(content::BrowserContext* context);
CookiesEventRouter(const CookiesEventRouter&) = delete;
CookiesEventRouter& operator=(const CookiesEventRouter&) = delete;
~CookiesEventRouter() override;
// BrowserListObserver:
void OnBrowserAdded(Browser* browser) override;
private:
// This helper class connects to the CookieMonster over Mojo, and relays Mojo
// messages to the owning CookiesEventRouter. This rather clumsy arrangement
// is necessary to differentiate which CookieMonster the Mojo message comes
// from (that associated with the incognito profile vs the original profile),
// since it's not possible to tell the source from inside OnCookieChange().
class CookieChangeListener : public network::mojom::CookieChangeListener {
public:
CookieChangeListener(CookiesEventRouter* router, bool otr);
CookieChangeListener(const CookieChangeListener&) = delete;
CookieChangeListener& operator=(const CookieChangeListener&) = delete;
~CookieChangeListener() override;
// network::mojom::CookieChangeListener:
void OnCookieChange(const net::CookieChangeInfo& change) override;
private:
raw_ptr<CookiesEventRouter> router_;
bool otr_;
};
void MaybeStartListening();
void BindToCookieManager(
mojo::Receiver<network::mojom::CookieChangeListener>* receiver,
Profile* profile);
void OnConnectionError(
mojo::Receiver<network::mojom::CookieChangeListener>* receiver);
void OnCookieChange(bool otr, const net::CookieChangeInfo& change);
// This method dispatches events to the extension message service.
void DispatchEvent(content::BrowserContext* context,
events::HistogramValue histogram_value,
const std::string& event_name,
base::Value::List event_args,
const GURL& cookie_domain);
raw_ptr<Profile> profile_;
// To listen to cookie changes in both the original and the off the record
// profiles, we need a pair of bindings, as well as a pair of
// CookieChangeListener instances.
CookieChangeListener listener_{this, false};
mojo::Receiver<network::mojom::CookieChangeListener> receiver_{&listener_};
CookieChangeListener otr_listener_{this, true};
mojo::Receiver<network::mojom::CookieChangeListener> otr_receiver_{
&otr_listener_};
};
// Implements the cookies.get() extension function.
class CookiesGetFunction : public ExtensionFunction {
public:
DECLARE_EXTENSION_FUNCTION("cookies.get", COOKIES_GET)
CookiesGetFunction();
protected:
~CookiesGetFunction() override;
// ExtensionFunction:
ResponseAction Run() override;
private:
void GetCookieListCallback(
const net::CookieAccessResultList& cookie_list,
const net::CookieAccessResultList& excluded_cookies);
// Notify the extension telemetry service when API is called.
void NotifyExtensionTelemetry();
GURL url_;
mojo::Remote<network::mojom::CookieManager> store_browser_cookie_manager_;
absl::optional<api::cookies::Get::Params> parsed_args_;
};
// Implements the cookies.getAll() extension function.
class CookiesGetAllFunction : public ExtensionFunction {
public:
DECLARE_EXTENSION_FUNCTION("cookies.getAll", COOKIES_GETALL)
CookiesGetAllFunction();
protected:
~CookiesGetAllFunction() override;
// ExtensionFunction:
ResponseAction Run() override;
private:
// For the two different callback signatures for getting cookies for a URL vs
// getting all cookies. They do the same thing.
void GetAllCookiesCallback(const net::CookieList& cookie_list);
void GetCookieListCallback(
const net::CookieAccessResultList& cookie_list,
const net::CookieAccessResultList& excluded_cookies);
// Notify the extension telemetry service when API is called.
void NotifyExtensionTelemetry();
GURL url_;
mojo::Remote<network::mojom::CookieManager> store_browser_cookie_manager_;
absl::optional<api::cookies::GetAll::Params> parsed_args_;
};
// Implements the cookies.set() extension function.
class CookiesSetFunction : public ExtensionFunction {
public:
DECLARE_EXTENSION_FUNCTION("cookies.set", COOKIES_SET)
CookiesSetFunction();
protected:
~CookiesSetFunction() override;
ResponseAction Run() override;
private:
void SetCanonicalCookieCallback(net::CookieAccessResult set_cookie_result);
void GetCookieListCallback(
const net::CookieAccessResultList& cookie_list,
const net::CookieAccessResultList& excluded_cookies);
enum { NO_RESPONSE, SET_COMPLETED, GET_COMPLETED } state_;
GURL url_;
bool success_;
mojo::Remote<network::mojom::CookieManager> store_browser_cookie_manager_;
absl::optional<api::cookies::Set::Params> parsed_args_;
};
// Implements the cookies.remove() extension function.
class CookiesRemoveFunction : public ExtensionFunction {
public:
DECLARE_EXTENSION_FUNCTION("cookies.remove", COOKIES_REMOVE)
CookiesRemoveFunction();
protected:
~CookiesRemoveFunction() override;
// ExtensionFunction:
ResponseAction Run() override;
private:
void RemoveCookieCallback(uint32_t /* num_deleted */);
GURL url_;
mojo::Remote<network::mojom::CookieManager> store_browser_cookie_manager_;
absl::optional<api::cookies::Remove::Params> parsed_args_;
};
// Implements the cookies.getAllCookieStores() extension function.
class CookiesGetAllCookieStoresFunction : public ExtensionFunction {
public:
DECLARE_EXTENSION_FUNCTION("cookies.getAllCookieStores",
COOKIES_GETALLCOOKIESTORES)
protected:
~CookiesGetAllCookieStoresFunction() override {}
// ExtensionFunction:
ResponseAction Run() override;
};
class CookiesAPI : public BrowserContextKeyedAPI, public EventRouter::Observer {
public:
explicit CookiesAPI(content::BrowserContext* context);
CookiesAPI(const CookiesAPI&) = delete;
CookiesAPI& operator=(const CookiesAPI&) = delete;
~CookiesAPI() override;
// KeyedService implementation.
void Shutdown() override;
// BrowserContextKeyedAPI implementation.
static BrowserContextKeyedAPIFactory<CookiesAPI>* GetFactoryInstance();
// EventRouter::Observer implementation.
void OnListenerAdded(const EventListenerInfo& details) override;
private:
friend class BrowserContextKeyedAPIFactory<CookiesAPI>;
raw_ptr<content::BrowserContext> browser_context_;
// BrowserContextKeyedAPI implementation.
static const char* service_name() {
return "CookiesAPI";
}
static const bool kServiceIsNULLWhileTesting = true;
// Created lazily upon OnListenerAdded.
std::unique_ptr<CookiesEventRouter> cookies_event_router_;
};
} // namespace extensions
#endif // CHROME_BROWSER_EXTENSIONS_API_COOKIES_COOKIES_API_H_
三、开发者模式打开加载下扩展看下堆栈效果：
至此分析完毕，如果想拦截 chrome.cookies.getAll等方法在 chrome\browser\extensions\api\cookies\cookies_api.cc中更改即可。
