connect.cookies

Read and write cookies for sites you're granted access to. Cookies are profile-scoped, and every call is host-gated: it needs the cookies capability and a { host } grant matching the target url. A call for a URL your host grants don't cover is denied — you never see cookies for sites you weren't granted.

• Capability: cookies + a { host } grant covering the target URL
• Namespace: connect.cookies

{ "capabilities": ["cookies", { "host": "https://*.example.com/*" }] }

📷

Screenshot

caption: Granting `cookies` plus a host pattern in the permission prompt. Capture the prompt showing both the cookies capability and the host grant.

drop the image at public/docs-img/extensions/cookies-grant.png

Walkthrough

Read a site's session cookie.

1. Declare cookies and a host pattern for the site:

   { "capabilities": ["cookies", { "host": "https://app.example.com/*" }] }

2. Read for a URL your grant covers:

   const [c] = await connect.cookies.getAll({ url: 'https://app.example.com/', name: 'session' });

3. Write / delete with set / remove for the same permitted URLs.
4. React to changes with onChanged (you only hear about granted origins).

Methods

cookies.getAll(filter)

List cookies matching a filter, for a permitted site.

How to use it

1. Scope with url or domain (must be covered by a host grant).
2. Narrow further with name / path / secure / session.

Signature — connect.cookies.getAll({ url?, domain?, name?, path?, secure?, session? })

Parameters

Returns — Promise<Cookie[]>.

Errors — denied unless cookies and a host grant covering the scope are held.

const cookies = await connect.cookies.getAll({ url: 'https://app.example.com/' });

cookies.get(details)

Read a specific cookie (or cookies) for a permitted site.

How to use it

1. Pass the url (host-gated) and optionally a name.

Signature — connect.cookies.get({ url, name? })

Parameters

Returns — Promise<Cookie | Cookie[] | null>.

cookies.set(details)

Write a cookie.

How to use it

1. Pass the url (host-gated) plus the cookie fields you want.
2. Omit expirationDate for a session cookie.

Signature — connect.cookies.set({ url, name?, value?, domain?, path?, secure?, httpOnly?, expirationDate?, sameSite? })

Parameters

Returns — Promise<Cookie>.

cookies.remove(details)

Delete a cookie.

How to use it

1. Pass the url (host-gated) and the cookie name.

Signature — connect.cookies.remove({ url, name }) · Returns Promise<void>.

Events

cookies.onChanged(cb)

Fires on any cookie change for origins you hold a host grant for — never other sites.

How to use it

1. Subscribe; you only hear about origins your host grants cover.
2. Read removed to tell a set from a delete, and inspect cookie / cause.

Payload

const off = connect.cookies.onChanged(({ cookie, removed }) => {
  if (!removed && cookie.name === 'session') refreshAuth();
});

Notes

• Host-scoping is enforced on every call and on the change event — the capability alone is never enough; the { host } grant defines which sites you can touch.