cdt-cookie-debugging

Core Concepts

HttpOnly vs Client-Side Storage

Cookies marked HttpOnly cannot be accessed or modified by client-side JavaScript (cookieStore or document.cookie). However, the browser automatically attaches active HttpOnly cookies to outgoing HTTP request headers (Cookie).

• To inspect current HttpOnly values: Look at the Cookie request header of any outgoing HTTP request via get_network_request.
• To inspect how cookies were created or configured: Look at the Set-Cookie response header of login/auth responses.
• To inspect non-HttpOnly cookies: Use evaluate_script with the modern cookieStore API (async () => await cookieStore.getAll()).

Session Strategy: Live Tab vs Isolated Context

Choose the right session environment to avoid state contamination (e.g., residual analytics or auth tokens):

Client-Side Capabilities & Limitations

[!WARNING] Attempting to clear an HttpOnly cookie via JavaScript (cookieStore.delete or document.cookie = "...; max-age=0") will silently fail. To test in an unauthenticated or fresh state, always spawn a new isolated context using new_page with isolatedContext.

Workflow Patterns

1. Diagnosing Authentication Failures & Redirects (401 / 403)

When an authenticated page request fails, returns 401/403, or redirects to login:

1. List Recent Requests: Call list_network_requests with includePreservedRequests: true.
2. Find the Target Request: Locate the failing request (401/403) or redirect (302/307).
3. Inspect Outgoing Cookie Header: Call get_network_request with the reqid.
   • Verify if the Cookie header was attached and whether required tokens (e.g. SESSION_ID, auth_token) were sent.
4. Trigger Active Inspection (If no recent request exists):
   • If the cookie was set in a previous session and no network call is listed, trigger a request:
     • Use navigate_page with reload: true, OR
     • Call evaluate_script with () => fetch(window.location.href)
   • Then call get_network_request on the new request to inspect the active Cookie header.
5. Trace the Setting Request: If the cookie is missing or rejected:
   • Check earlier login/handshake responses for Set-Cookie directives:
     • Path mismatch: e.g., Path=/api when the request is to /.
     • Domain mismatch: e.g., Domain=api.example.com preventing cookies on sub.example.com.
     • Secure flag on HTTP: Secure cookies are never sent over unencrypted http://.
     • SameSite blocking: SameSite=Strict cookies are omitted on cross-site navigations.
     • Expiration: Check if Expires or Max-Age elapsed.

2. Cookie Banner & Consent Conformance Testing

To verify that no non-essential or tracking cookies are set before consent or when declining:

1. Start Clean: Open a fresh isolated context with a dedicated name:

   {"url": "<PAGE_URL>", "isolatedContext": "consent-test-1"}

2. Record Baseline Cookies: Before interacting with the banner, run evaluate_script with async () => await cookieStore.getAll().
3. Inspect Premature Network Requests & Issues:
   • Call list_network_requests to ensure no third-party tracking beacons fired before consent.
   • Call list_console_messages with types: ["issue"] to check for tracking warnings.
4. Interact with Consent Banner:
   • Capture snapshot with take_snapshot to locate the "Decline" or "Reject All" button uid.
   • Click the button with click.
5. Verify Cookie Difference:
   • Run evaluate_script with async () => await cookieStore.getAll() after clicking to assert that only strictly necessary or consent-state cookies exist.
6. Test Consent Revocation (Lifecycle Audit):
   • When auditing consent withdrawal or preference changes:
     • Locate and click the "Cookie Settings", "Manage Preferences", or footer privacy trigger (take_snapshot $\rightarrow$ click).
     • Deselect non-essential categories or click "Revoke All" / "Save Preferences".
     • Re-query cookieStore.getAll() to verify previously accepted non-essential cookies were cleared or expired.
     • Call list_network_requests on subsequent actions to ensure tracking beacons are no longer fired.
7. Teardown Context: Call close_page when the audit is complete to prevent leftover cookies from affecting subsequent tasks.

3. Auditing Cookie Security, SameSite & CHIPS (Partitioned Cookies)

1. Fast-Track: Native DevTools Issues (Recommended):
   • Call list_console_messages with:

     {
       "types": ["issue"],
       "includePreservedMessages": true
     }

   • Check for CookieIssue entries, such as:
     • SameSiteNoneInsecure: SameSite=None without Secure.
     • ThirdPartyCookiePhaseout: Third-party cookie blocked or restricted.
     • SchemefulSameSite: Cross-scheme cookie issues.
     • PartitionedCookies: Invalid CHIPS partitioning attributes.
2. Deep Audit: Lighthouse Third-Party Cookies:
   • Run lighthouse_audit with mode: "navigation" and outputDirPath: "/tmp/lh-report".
   • Extract the specific cookie audit without loading the full report into context:

     node -e "const r=require('/tmp/lh-report/report.json'); const a=r.audits['third-party-cookies']; console.log(JSON.stringify({score: a?.score, displayValue: a?.displayValue, items: a?.details?.items}))"

4. Client-Side Cookie Inspection & Manipulation

For client-accessible, non-HttpOnly cookies (e.g., UI preferences, non-sensitive feature flags):

1. Read Cookies & Attributes:
   • Use the modern asynchronous Cookie Store API:

     async () => await cookieStore.getAll();

   • Fallback for insecure HTTP origins: () => document.cookie.
2. Set / Modify Cookie:
   • Set client cookie via cookieStore:

     async () =>
       await cookieStore.set({
         name: 'theme',
         value: 'dark',
         expires: Date.now() + 86400000,
         sameSite: 'lax',
       });

3. Delete Cookie:
   • Clear client cookie:

     async () => await cookieStore.delete('theme');

Troubleshooting

• cookieStore is undefined: cookieStore requires a Secure Context (https://, localhost, or 127.0.0.1). On non-secure HTTP origins, use () => document.cookie or test over HTTPS.
• evaluate_script returns empty / unresolved Promise: cookieStore methods are asynchronous. Always wrap calls with async () => await cookieStore.getAll().
• Cookie not visible in JavaScript: The cookie is marked HttpOnly. Trigger a network request and call get_network_request to view it in the Cookie request header.
• JavaScript deletion did not remove cookie: The cookie is HttpOnly or requires matching Path and Domain parameters. Use a fresh isolatedContext with new_page for a clean slate.
• Cookie set in response but not sent in requests:
  • Verify if page is http:// while cookie specifies Secure.
  • Check if Domain restricts subdomains.
  • Check list_console_messages(types: ["issue"]) for browser rejection reasons.
• Residual cookies contaminating audits: Always use new_page with a unique isolatedContext when running compliance tests, and call close_page when done.