1# Authentication Architecture
2 
3## Overview
4 
5This skill uses a **hybrid authentication approach** that combines the best of both worlds:
6 
71. **Persistent Browser Profile** (`user_data_dir`) for consistent browser fingerprinting
82. **Manual Cookie Injection** from `state.json` for reliable session cookie persistence
9 
10## Why This Approach?
11 
12### The Problem
13 
14Playwright/Patchright has a known bug ([#36139](https://github.com/microsoft/playwright/issues/36139)) where **session cookies** (cookies without an `Expires` attribute) do not persist correctly when using `launch_persistent_context()` with `user_data_dir`.
15 
16**What happens:**
17- ✅ Persistent cookies (with `Expires` date) → Saved correctly to browser profile
18- ❌ Session cookies (without `Expires`) → **Lost after browser restarts**
19 
20**Impact:**
21- Some Google auth cookies are session cookies
22- Users experience random authentication failures
23- "Works on my machine" syndrome (depends on which cookies Google uses)
24 
25### TypeScript vs Python
26 
27The **MCP Server** (TypeScript) can work around this by passing `storage_state` as a parameter:
28 
29```typescript
30// TypeScript - works!
31const context = await chromium.launchPersistentContext(userDataDir, {
32  storageState: "state.json",  // ← Loads cookies including session cookies
33  channel: "chrome"
34});
35```
36 
37But **Python's Playwright API doesn't support this** ([#14949](https://github.com/microsoft/playwright/issues/14949)):
38 
39```python
40# Python - NOT SUPPORTED!
41context = playwright.chromium.launch_persistent_context(
42    user_data_dir=profile_dir,
43    storage_state="state.json",  # ← Parameter not available in Python!
44    channel="chrome"
45)
46```
47 
48## Our Solution: Hybrid Approach
49 
50We use a **two-phase authentication system**:
51 
52### Phase 1: Setup (`auth_manager.py setup`)
53 
541. Launch persistent context with `user_data_dir`
552. User logs in manually
563. **Save state to TWO places:**
57   - Browser profile directory (automatic, for fingerprint + persistent cookies)
58   - `state.json` file (explicit save, for session cookies)
59 
60```python
61context = playwright.chromium.launch_persistent_context(
62    user_data_dir="browser_profile/",
63    channel="chrome"
64)
65# User logs in...
66context.storage_state(path="state.json")  # Save all cookies
67```
68 
69### Phase 2: Runtime (`ask_question.py`)
70 
711. Launch persistent context with `user_data_dir` (loads fingerprint + persistent cookies)
722. **Manually inject cookies** from `state.json` (adds session cookies)
73 
74```python
75# Step 1: Launch with browser profile
76context = playwright.chromium.launch_persistent_context(
77    user_data_dir="browser_profile/",
78    channel="chrome"
79)
80 
81# Step 2: Manually inject cookies from state.json
82with open("state.json", 'r') as f:
83    state = json.load(f)
84    context.add_cookies(state['cookies'])  # ← Workaround for session cookies!
85```
86 
87## Benefits
88 
89| Feature | Our Approach | Pure `user_data_dir` | Pure `storage_state` |
90|---------|--------------|----------------------|----------------------|
91| **Browser Fingerprint Consistency** | ✅ Same across restarts | ✅ Same | ❌ Changes each time |
92| **Session Cookie Persistence** | ✅ Manual injection | ❌ Lost (bug) | ✅ Native support |
93| **Persistent Cookie Persistence** | ✅ Automatic | ✅ Automatic | ✅ Native support |
94| **Google Trust** | ✅ High (same browser) | ✅ High | ❌ Low (new browser) |
95| **Cross-platform Reliability** | ✅ Chrome required | ⚠️ Chromium issues | ✅ Portable |
96| **Cache Performance** | ✅ Keeps cache | ✅ Keeps cache | ❌ No cache |
97 
98## File Structure
99 
100```
101~/.claude/skills/notebooklm/data/
102├── auth_info.json              # Metadata about authentication
103├── browser_state/
104│   ├── state.json             # Cookies + localStorage (for manual injection)
105│   └── browser_profile/       # Chrome user profile (for fingerprint + cache)
106│       ├── Default/
107│       │   ├── Cookies        # Persistent cookies only (session cookies missing!)
108│       │   ├── Local Storage/
109│       │   └── Cache/
110│       └── ...
111```
112 
113## Why `state.json` is Critical
114 
115Even though we use `user_data_dir`, we **still need `state.json`** because:
116 
1171. **Session cookies** are not saved to the browser profile (Playwright bug)
1182. **Manual injection** is the only reliable way to load session cookies
1193. **Validation** - we can check if cookies are expired before launching
120 
121## Code References
122 
123**Setup:** `scripts/auth_manager.py:94-120`
124- Lines 100-113: Launch persistent context with `channel="chrome"`
125- Line 167: Save to `state.json` via `context.storage_state()`
126 
127**Runtime:** `scripts/ask_question.py:77-118`
128- Lines 86-99: Launch persistent context
129- Lines 101-118: Manual cookie injection workaround
130 
131**Validation:** `scripts/auth_manager.py:236-298`
132- Lines 262-275: Launch persistent context
133- Lines 277-287: Manual cookie injection for validation
134 
135## Related Issues
136 
137- [microsoft/playwright#36139](https://github.com/microsoft/playwright/issues/36139) - Session cookies not persisting
138- [microsoft/playwright#14949](https://github.com/microsoft/playwright/issues/14949) - Storage state with persistent context
139- [StackOverflow Question](https://stackoverflow.com/questions/79641481/) - Session cookie persistence issue
140 
141## Future Improvements
142 
143If Playwright adds support for `storage_state` parameter in Python's `launch_persistent_context()`, we can simplify to:
144 
145```python
146# Future (when Python API supports it):
147context = playwright.chromium.launch_persistent_context(
148    user_data_dir="browser_profile/",
149    storage_state="state.json",  # ← Would handle everything automatically!
150    channel="chrome"
151)
152```
153 
154Until then, our hybrid approach is the most reliable solution.
155