@ssheleg/sheleg-dev 0.11.8 → 0.12.0

package/plugins/sheleg-dev/skills/frontend-performance/SKILL.md

@@ -28,24 +28,39 @@ Optimize frontend applications for maximum Lighthouse scores and real-user perfo
 
 ## Core Web Vitals, and the diagnostics beside them
 
-**Three metrics are Core Web Vitals. The other three are not**, and the difference
-is not pedantry: only the first three are what Google reports and ranks on, and
-only they are field-measurable. TBT is a *lab* metric — web.dev says it "is not
-part of the Core Web Vitals set because they are not field-measurable" — and it
-stands in for INP when you have no field data. Telling a client their Speed Index
-is a failing Core Web Vital is telling them about a thing Google does not measure.
-
-| Core Web Vital | Good | Needs Work | Poor |
-|--------|------|------------|------|
-| LCP (Largest Contentful Paint) | < 2.5s | 2.5-4.0s | > 4.0s |
-| INP (Interaction to Next Paint) | < 200ms | 200-500ms | > 500ms |
-| CLS (Cumulative Layout Shift) | < 0.1 | 0.1-0.25 | > 0.25 |
-
-| Lab diagnostic | Good | Needs Work | Poor | Stands in for |
-|--------|------|------------|------|---|
-| FCP (First Contentful Paint) | < 1.8s | 1.8-3.0s | > 3.0s | early LCP signal |
-| TBT (Total Blocking Time) | < 200ms | 200-600ms | > 600ms | INP, in the lab |
-| SI (Speed Index) | < 3.4s | 3.4-5.8s | > 5.8s | perceived load |
+**Two INDEPENDENT axes, and conflating them is the common error.** Axis one:
+**is it a Core Web Vital** — what Google reports and ranks on (LCP, INP, CLS)
+— or not. Axis two: **where can you measure it** — in the FIELD (real users,
+CrUX) or only in the LAB (a synthetic run). These do not line up: a metric can
+be not-CWV and still field-measurable. **FCP is the case that breaks the
+one-axis story — it is NOT a Core Web Vital, yet it IS field-measurable**
+(CrUX reports FCP; web.dev lists both lab and field tools for it). The earlier
+claim that "only the three CWV are field-measurable" was wrong.
+
+| Metric | Core Web Vital? | Field-measurable? | Good | Needs Work | Poor |
+|---|---|---|---|---|---|
+| LCP | yes | yes (CrUX) | < 2.5s | 2.5-4.0s | > 4.0s |
+| INP | yes | yes (CrUX) | < 200ms | 200-500ms | > 500ms |
+| CLS | yes | yes (CrUX) | < 0.1 | 0.1-0.25 | > 0.25 |
+| FCP | no | **yes (CrUX)** | < 1.8s | 1.8-3.0s | > 3.0s |
+| TBT | no | no (lab only) | < 200ms | 200-600ms | > 600ms |
+| SI | no | no (lab only) | < 3.4s | 3.4-5.8s | > 5.8s |
+
+**A field claim carries its provenance, always: p75** (the 75th-percentile
+value Google classifies on, never a mean), the **device/cohort** (phone vs
+desktop, and which population), the **period** (CrUX is a 28-day trailing
+window), and the **sample size** (a thin origin has no field data — that is
+`unknown`, not `good`). A number without these four is a lab number wearing a
+field label.
+
+**TBT is a diagnostic CORRELATE of INP, never a substitute for its evidence.**
+A good lab TBT is a hint that INP may be fine; it does NOT PROVE INP, because
+INP is measured on real interactions the lab did not perform. So a page with
+CrUX FCP data and a Lighthouse TBT but **no field INP** reports **FCP =
+field-supported, INP = unknown** — never "INP passed by TBT". Telling a client
+their Speed Index is a failing Core Web Vital is telling them about a thing
+Google does not rank; telling them INP passed because TBT did is telling them
+about a measurement nobody took.
 
 Thresholds and the classification verified against `web.dev/articles/vitals`,
 2026-08-16.
@@ -61,15 +76,28 @@ Thresholds and the classification verified against `web.dev/articles/vitals`,
 - **Use `font-display: swap`** -- Prevents invisible text during load (FOIT).
 - **Remove unused preconnects** -- If fonts are self-hosted, `preconnect` to font CDNs is dead weight.
 
+**Before any of these changes: MEASURE, don't prescribe.** The items below are
+optimization HEURISTICS, not blanket rules — each is conditional on evidence,
+and applied blind it can lose function for a score. Before changing anything,
+check three things: the **performance trace + the scenarios** (what a low-end
+device on a slow network actually waits for), the **browser-support contract**
+(who must the page still work for), and the **accessibility owner** (structure
+is theirs, not the score's). A change ships only with acceptance covering:
+low-end/slow-network scenarios, keyboard + heading structure intact, the
+supported-browser matrix still served, NO new unapproved CSP origin, and
+several comparable before/after measurements showing the win **with no
+functional loss**.
+
 ### JavaScript (TBT, FCP, LCP)
 
-- **Code split aggressively** -- Lazy-load below-the-fold sections. Only hero + nav in initial bundle.
+- **Code split by the MEASURED waterfall** -- lazy-load what the trace shows the first paint does not need; "only hero + nav in the initial bundle" is a starting hypothesis, not a rule — a section the scenario needs above the fold stays, whatever the score says.
 - **Defer third-party scripts** -- GA, analytics, chat widgets load after interactive (`afterInteractive` or `defer`).
-- **Target modern browsers** -- Set `browserslist` to avoid shipping polyfills for `Array.prototype.at`, `Object.fromEntries`, etc.:
+- **Target the browsers your USERS run** -- `browserslist` follows a stated user-support policy (your analytics, your contract), not a default "last 2". The `last 2` line below is an EXAMPLE; shipping it without checking who it drops is how a working browser stops being served for a polyfill saving:
   ```
+  # example only — replace with your measured support matrix
   last 2 Chrome versions, last 2 Firefox versions, last 2 Safari versions, last 2 Edge versions
   ```
-- **Tree-shake imports** -- Named imports only. No `import * as`.
+- **Tree-shake imports** -- prefer named imports where the bundle analyzer shows `import * as` pulling dead weight; it is a tree-shaking aid, not a ban — a namespace import that costs nothing measured is not a defect.
 - **Analyze bundles** -- Use `@next/bundle-analyzer`, `source-map-explorer`, or `vite-plugin-visualizer`.
 
 ### CSS & Animations (CLS)
@@ -98,7 +126,7 @@ Thresholds and the classification verified against `web.dev/articles/vitals`,
 
 ### Content Security Policy (Best Practices)
 
-- **Whitelist all loaded origins** -- CSP blocks = console errors = lower Best Practices score.
+- **Approve origins by FUNCTIONAL NECESSITY, not for the score** -- an origin enters the CSP because the page genuinely needs it, and each is reviewed; whitelisting everything the page happens to load to silence console errors trades the whole point of a CSP for a Best-Practices number. No new origin ships unapproved.
 - **Audit after every third-party change** -- Adding analytics, fonts, or CDN scripts requires CSP updates.
 - **Tighten after migration** -- If you move from external fonts to self-hosted, remove the old CSP entries.
 - **Common CSP origins**:
@@ -111,7 +139,7 @@ Thresholds and the classification verified against `web.dev/articles/vitals`,
 These directly affect the Lighthouse Accessibility score:
 
 - **Contrast ratio** -- WCAG AA requires 4.5:1 for normal text, 3:1 for large text. Avoid opacity modifiers on text colors (e.g., `text-primary/80` in Tailwind reduces contrast). Use full-opacity color tokens.
-- **Heading hierarchy** -- Sequential: `h1` -> `h2` -> `h3`. Never skip levels. Use non-heading elements (`<p>`) for visual-only "headings" (e.g., footer column titles).
+- **Heading hierarchy follows STRUCTURE, decided with the accessibility owner** -- sequential `h1`->`h2`->`h3`, no skipped levels. Demote a heading to `<p>` only when it is genuinely NOT a section title; downgrading a real footer-section heading to `<p>` to quiet a Lighthouse audit removes structure a screen-reader user navigates by. Accessibility is the owner here, not the score.
 - **Alt text** -- Decorative images next to identical text get `alt=""`. Informative images get descriptive alt. Never duplicate adjacent text.
 - **Tap targets** -- Minimum 48x48px on mobile. Applies to buttons, links, form inputs.
 

package/plugins/sheleg-dev/skills/google-auth/SKILL.md

@@ -86,7 +86,7 @@ request = google.auth.transport.requests.Request()
 credentials.refresh(request)
 ```
 
-ADC search order: attached service account → `gcloud auth application-default login` file → `GOOGLE_APPLICATION_CREDENTIALS` env var.
+ADC search order (env var FIRST — this line was reversed): `GOOGLE_APPLICATION_CREDENTIALS` env var → `gcloud auth application-default login` file → attached service account (metadata). Print the RESOLVED principal and source (no secret) before configuring — with more than one present, only the resolved source names which you are actually using.
 
 For detailed ADC setup and service account usage, see [references/adc-and-service-accounts.md](references/adc-and-service-accounts.md).
 
@@ -259,6 +259,18 @@ if credentials.expired and credentials.refresh_token:
 - Validate external credential configurations before use (check `token_url`, `service_account_impersonation_url` point to googleapis.com)
 - Prefer Workload Identity Federation over service account keys for non-GCP environments
 - For end-user web sign-in, apply the google-signin skill's full checklist — a partial restatement here is how the two skills drifted apart once already
+- **Fail closed on a missing production secret.** The session signing secret,
+  and any credential-store key, is REQUIRED in production with NO dev fallback —
+  a hardcoded default signs every deployment's cookies with a key that lives in
+  the repo. Missing → refuse to boot, never a warning-and-continue (DV-07).
+- **Logs are sanitized; a credential never reaches one.** No token, no
+  `client_secret`, no `refresh_token`, no session value in a log line, a stack
+  trace, or an error message — a token in a log is a token anyone with log
+  access holds. Redact by allow-list, not by trying to strip the secret out.
+- **HTTPS is mandatory and the credential store can fail.** The auth cookie is
+  `Secure` and the callback refuses plain HTTP (an OAuth code over `http://` is a
+  code on the wire); and a credential-store read/write that FAILS is an auth
+  failure — re-prompt or 503, never proceed as if the credentials loaded.
 - **Python-specific**: reuse a single `google.auth.transport.requests.Request()` instance across verifications for connection pooling; do not create a new one per call in hot paths
 
 ## Reference Files

package/plugins/sheleg-dev/skills/google-auth/references/adc-and-service-accounts.md

@@ -20,9 +20,19 @@ Application Default Credentials (ADC) automatically finds credentials based on t
 
 ## ADC Search Order
 
-1. **Attached service account** — via GCP metadata server (Compute Engine, Cloud Run, GKE, etc.)
-2. **`gcloud auth application-default login`** — local credential file
-3. **`GOOGLE_APPLICATION_CREDENTIALS`** — env var pointing to a credential JSON file
+Google resolves these **in this order — env var FIRST**, and the earlier match
+wins. The old text here had it reversed (attached account first), which points
+you at the wrong lever when the resolved identity is not what you expect:
+
+1. **`GOOGLE_APPLICATION_CREDENTIALS`** — env var pointing to a credential JSON file
+2. **`gcloud auth application-default login`** — local credential file (well-known path)
+3. **Attached service account** — via GCP metadata server (Compute Engine, Cloud Run, GKE, etc.)
+
+**Before configuring, print the ACTUALLY-resolved principal and source** — which
+of the three won, and the account email — **without the secret**. On a VM with a
+metadata identity AND an env var set, only the resolved source tells you which
+one your code is actually using; a config change made against the wrong source
+is a change that does nothing.
 
 Credential file locations from `gcloud auth application-default login`:
 - **macOS/Linux**: `$HOME/.config/gcloud/application_default_credentials.json`

package/plugins/sheleg-dev/skills/google-auth/references/oauth2-web-server.md

@@ -42,20 +42,30 @@ pip install google-auth google-auth-oauthlib google-api-python-client flask
 
 ### Node.js
 
+**One OAuth2 client PER request, never a shared singleton.** A module-level
+`oauth2Client` whose `setCredentials(tokens)` runs on every callback is mutated
+by every concurrent login — two users signing in at once end up with each
+other's tokens. Build the client inside the handler; the client id/secret are
+shared config, the CREDENTIALS are per principal and never assigned to a
+process-wide object.
+
 ```js
 const {google} = require('googleapis');
 const crypto = require('crypto');
 
-const oauth2Client = new google.auth.OAuth2(
-  YOUR_CLIENT_ID,
-  YOUR_CLIENT_SECRET,
-  YOUR_REDIRECT_URL
-);
+// A fresh client per request — the credentials it will hold are this user's.
+function newOAuthClient() {
+  return new google.auth.OAuth2(YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL);
+}
+
+const oauthClient = newOAuthClient();
 
+// State is REQUIRED, crypto-random, single-use with a TTL, and bound to the
+// server session — not a value the client can echo back to itself.
 const state = crypto.randomBytes(32).toString('hex');
-req.session.state = state;
+req.session.oauthState = { value: state, expires: Date.now() + 10 * 60 * 1000 };
 
-const authorizationUrl = oauth2Client.generateAuthUrl({
+const authorizationUrl = oauthClient.generateAuthUrl({
   access_type: 'offline',          // 'online' (default) or 'offline' (gets refresh_token)
   scope: [
     'https://www.googleapis.com/auth/drive.metadata.readonly',
@@ -73,6 +83,7 @@ const authorizationUrl = oauth2Client.generateAuthUrl({
 ```python
 from google_auth_oauthlib.flow import Flow
 import secrets
+import time
 
 flow = Flow.from_client_secrets_file(
     'client_secret.json',
@@ -84,7 +95,8 @@ flow = Flow.from_client_secrets_file(
 )
 
 state = secrets.token_hex(32)
-session['state'] = state
+# Server-bound, random, with a TTL: the callback consumes it atomically.
+session['oauth_state'] = {'value': state, 'expires': time.time() + 600}
 
 authorization_url, state = flow.authorization_url(
     access_type='offline',             # gets refresh_token
@@ -125,6 +137,41 @@ return redirect(authorization_url)
 
 ## Step 3: Handle Callback
 
+### The session cookie is opaque — credentials live server-side, encrypted
+
+**A signed cookie is not an encrypted one.** Flask's default session and
+Starlette's `SessionMiddleware` SIGN the cookie (tamper-evident) but do NOT
+encrypt it — anyone holding the cookie can base64-decode and read every value
+in it, which the official docs confirm. So the cookie carries **only a random
+opaque session id**; the Google credentials (`token`, `refresh_token`,
+`client_secret`) go into a **server-side encrypted store**, fetched by
+`(session_id, principal)` — never into the cookie, the redirect URL, or the
+response body.
+
+```python
+# The cookie holds ONLY an opaque id. Credentials are server-side, encrypted.
+session['sid'] = session.get('sid') or secrets.token_urlsafe(32)
+credential_store.put(                      # encrypted at rest, keyed by (sid, principal)
+    sid=session['sid'], principal=userinfo['sub'],
+    credentials={'token': credentials.token,
+                 'refresh_token': credentials.refresh_token,
+                 'client_secret': credentials.client_secret, ...})
+# Never: session['credentials'] = {...}     ← readable in the cookie
+# Never: log or return the tokens            ← no console.log(tokens.access_token)
+```
+
+Four more, because a leaked secret does not announce itself: **never log a
+token or a credential** (no `console.log(tokens.access_token)`; sanitize logs
+by allow-list, so no token, `client_secret` or `refresh_token` reaches a line,
+a stack trace or an error message); the session signing secret is a **required
+production secret with NO dev fallback** (a hardcoded default signs every
+deployment's cookies with a key in the repo — missing in production is
+**fail-closed**, refuse to boot); the auth cookie is **`Secure`, and the
+callback refuses plain HTTP** — an OAuth code or token over `http://` is a code
+or token on the wire; and **a credential-store read or write that FAILS is an
+auth failure** — re-prompt the user or return 503, never proceed as if the
+credentials loaded (a silent empty read logs the user in as nobody).
+
 ### Node.js
 
 ```js
@@ -134,16 +181,21 @@ app.get('/oauth2callback', async (req, res) => {
   const q = url.parse(req.url, true).query;
 
   if (q.error) {
-    console.log('Error: ' + q.error);
-    return res.status(400).send('Authorization failed');
+    return res.status(400).send('Authorization failed');   // never log the raw error/token
   }
 
-  if (q.state !== req.session.state) {
-    return res.status(403).send('State mismatch. Possible CSRF attack');
+  // Validate state BEFORE the token exchange: it must be PRESENT on both sides
+  // (undefined === undefined must NOT pass), unexpired, and consumed atomically
+  // so a replay of the same callback cannot reuse it.
+  const saved = req.session.oauthState;
+  delete req.session.oauthState;                            // single-use: consume it now
+  if (!q.state || !saved || saved.value !== q.state || Date.now() > saved.expires) {
+    return res.status(403).send('State invalid, missing, expired or already used');
   }
 
-  const {tokens} = await oauth2Client.getToken(q.code);
-  oauth2Client.setCredentials(tokens);
+  const oauthClient = newOAuthClient();                     // a client for THIS request
+  const {tokens} = await oauthClient.getToken(q.code);
+  oauthClient.setCredentials(tokens);                       // credentials stay on the local client
 
   // tokens.access_token — short-lived access token
   // tokens.refresh_token — long-lived (only on first auth!)
@@ -162,14 +214,20 @@ def oauth2callback():
     if request.args.get('error'):
         return 'Authorization failed', 400
 
-    if request.args.get('state') != session.get('state'):
-        abort(403, 'State mismatch. Possible CSRF attack')
+    # Validate state BEFORE the token exchange, and consume it atomically:
+    # pop() removes it in the same step, so a replayed callback finds nothing.
+    # Presence is required on BOTH sides — None == None must NOT pass.
+    saved = session.pop('oauth_state', None)
+    got = request.args.get('state')
+    if (not got or not saved or saved['value'] != got
+            or time.time() > saved['expires']):
+        abort(403, 'State invalid, missing, expired or already used')
 
     flow = Flow.from_client_secrets_file(
         'client_secret.json',
         scopes=SCOPES,
         redirect_uri=YOUR_REDIRECT_URL,
-        state=session['state']
+        state=saved['value']
     )
     flow.fetch_token(authorization_response=request.url)
 
@@ -179,20 +237,26 @@ def oauth2callback():
     # credentials.expiry — expiration datetime
     # credentials.scopes — granted scopes
 
-    session['credentials'] = {
+    # Cookie: opaque id only. Credentials: server-side, encrypted, keyed by
+    # (session id, principal) — never serialized into the signed cookie.
+    session['sid'] = session.get('sid') or secrets.token_urlsafe(32)
+    credential_store.put(session['sid'], principal=userinfo['sub'], credentials={
         'token': credentials.token,
         'refresh_token': credentials.refresh_token,
         'token_uri': credentials.token_uri,
         'client_id': credentials.client_id,
         'client_secret': credentials.client_secret,
-        'scopes': list(credentials.scopes)
-    }
+        'scopes': list(credentials.scopes),
+    })
     return redirect('/profile')
 ```
 
 ### Python (FastAPI)
 
 ```python
+import secrets
+import time
+
 from fastapi import APIRouter, Request
 from fastapi.responses import RedirectResponse
 from google_auth_oauthlib.flow import Flow
@@ -202,15 +266,19 @@ async def oauth2callback(request: Request):
     if request.query_params.get('error'):
         raise HTTPException(400, 'Authorization failed')
 
-    state = request.session.get('state')
-    if request.query_params.get('state') != state:
-        raise HTTPException(403, 'State mismatch')
+    # Consume atomically (pop) and validate BEFORE the exchange; a wrong,
+    # expired or replayed state must never start a token exchange.
+    saved = request.session.pop('oauth_state', None)
+    got = request.query_params.get('state')
+    if (not got or not saved or saved['value'] != got
+            or time.time() > saved['expires']):
+        raise HTTPException(403, 'State invalid, missing, expired or already used')
 
     flow = Flow.from_client_secrets_file(
         'client_secret.json',
         scopes=SCOPES,
         redirect_uri=YOUR_REDIRECT_URL,
-        state=state
+        state=saved['value']
     )
     flow.fetch_token(code=request.query_params.get('code'))
     credentials = flow.credentials
@@ -262,7 +330,8 @@ oauth2Client.on('tokens', (tokens) => {
   if (tokens.refresh_token) {
     // Store in database — only sent once!
   }
-  console.log('New access_token:', tokens.access_token);
+  // Never log a token or a credential (FIX-DV-07) — a token in a log is a
+  // token anyone with log access holds.
 });
 ```
 
@@ -377,19 +446,20 @@ const {google} = require('googleapis');
 const app = express();
 app.use(session({secret: 'your-secret', resave: false, saveUninitialized: false}));
 
-const oauth2Client = new google.auth.OAuth2(
-  process.env.GOOGLE_CLIENT_ID,
-  process.env.GOOGLE_CLIENT_SECRET,
-  'http://localhost:3000/oauth2callback'
-);
+// A client per request — client id/secret are config, credentials are per user.
+function newOAuthClient() {
+  return new google.auth.OAuth2(
+    process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET,
+    'http://localhost:3000/oauth2callback');
+}
 
 const SCOPES = ['https://www.googleapis.com/auth/userinfo.profile'];
 
 app.get('/auth', (req, res) => {
   const state = crypto.randomBytes(32).toString('hex');
-  req.session.state = state;
+  req.session.oauthState = { value: state, expires: Date.now() + 10 * 60 * 1000 };
 
-  const url = oauth2Client.generateAuthUrl({
+  const url = newOAuthClient().generateAuthUrl({
     access_type: 'offline',
     scope: SCOPES,
     state,
@@ -400,18 +470,22 @@ app.get('/auth', (req, res) => {
 
 app.get('/oauth2callback', async (req, res) => {
   if (req.query.error) return res.redirect('/error');
-  if (req.query.state !== req.session.state) return res.status(403).send('CSRF');
+  const saved = req.session.oauthState;
+  delete req.session.oauthState;                    // single-use
+  if (!req.query.state || !saved || saved.value !== req.query.state
+      || Date.now() > saved.expires) return res.status(403).send('CSRF');
 
-  const {tokens} = await oauth2Client.getToken(req.query.code);
+  const {tokens} = await newOAuthClient().getToken(req.query.code);
   req.session.tokens = tokens;
   res.redirect('/profile');
 });
 
 app.get('/profile', async (req, res) => {
   if (!req.session.tokens) return res.redirect('/auth');
-  oauth2Client.setCredentials(req.session.tokens);
+  const oauthClient = newOAuthClient();             // local to this request
+  oauthClient.setCredentials(req.session.tokens);
 
-  const oauth2 = google.oauth2({version: 'v2', auth: oauth2Client});
+  const oauth2 = google.oauth2({version: 'v2', auth: oauthClient});
   const {data} = await oauth2.userinfo.get();
   res.json(data);
 });
@@ -452,7 +526,7 @@ def auth():
         redirect_uri=REDIRECT_URI
     )
     state = secrets.token_hex(32)
-    session['state'] = state
+    session['oauth_state'] = {'value': state, 'expires': time.time() + 600}
     authorization_url, _ = flow.authorization_url(
         access_type='offline',
         include_granted_scopes='true',
@@ -465,8 +539,11 @@ def auth():
 def oauth2callback():
     if request.args.get('error'):
         return 'Authorization failed', 400
-    if request.args.get('state') != session.get('state'):
-        abort(403, 'State mismatch')
+    saved = session.pop('oauth_state', None)   # single-use: consume BEFORE exchange
+    got = request.args.get('state')
+    if (not got or not saved or saved['value'] != got
+            or time.time() > saved['expires']):
+        abort(403, 'State invalid, missing, expired or already used')
 
     flow = Flow.from_client_config(
         {
@@ -479,26 +556,28 @@ def oauth2callback():
         },
         scopes=SCOPES,
         redirect_uri=REDIRECT_URI,
-        state=session['state']
+        state=saved['value']
     )
     flow.fetch_token(authorization_response=request.url)
     creds = flow.credentials
-    session['credentials'] = {
-        'token': creds.token,
-        'refresh_token': creds.refresh_token,
-        'token_uri': creds.token_uri,
-        'client_id': creds.client_id,
-        'client_secret': creds.client_secret,
-        'scopes': list(creds.scopes or [])
-    }
+    userinfo = build('oauth2', 'v2', credentials=creds).userinfo().get().execute()
+    # Opaque id in the cookie; credentials in the server-side encrypted store.
+    session['sid'] = session.get('sid') or secrets.token_urlsafe(32)
+    credential_store.put(session['sid'], principal=userinfo['id'], credentials={
+        'token': creds.token, 'refresh_token': creds.refresh_token,
+        'token_uri': creds.token_uri, 'client_id': creds.client_id,
+        'client_secret': creds.client_secret, 'scopes': list(creds.scopes or []),
+    })
+    session['principal'] = userinfo['id']
     return redirect('/profile')
 
 
 @app.route('/profile')
 def profile():
-    if 'credentials' not in session:
+    stored = credential_store.get(session.get('sid'), session.get('principal'))
+    if not stored:
         return redirect('/auth')
-    creds = Credentials(**session['credentials'])
+    creds = Credentials(**stored)
     service = build('oauth2', 'v2', credentials=creds)
     user_info = service.userinfo().get().execute()
     return jsonify(user_info)
@@ -544,7 +623,7 @@ CLIENT_CONFIG = {
 async def auth(request: Request):
     flow = Flow.from_client_config(CLIENT_CONFIG, scopes=SCOPES, redirect_uri=REDIRECT_URI)
     state = secrets.token_hex(32)
-    request.session['state'] = state
+    request.session['oauth_state'] = {'value': state, 'expires': time.time() + 600}
     authorization_url, _ = flow.authorization_url(
         access_type='offline',
         include_granted_scopes='true',
@@ -557,31 +636,38 @@ async def auth(request: Request):
 async def oauth2callback(request: Request):
     if request.query_params.get('error'):
         raise HTTPException(400, 'Authorization failed')
-    if request.query_params.get('state') != request.session.get('state'):
-        raise HTTPException(403, 'State mismatch')
+    saved = request.session.pop('oauth_state', None)   # single-use: consume BEFORE exchange
+    got = request.query_params.get('state')
+    if (not got or not saved or saved['value'] != got
+            or time.time() > saved['expires']):
+        raise HTTPException(403, 'State invalid, missing, expired or already used')
 
     flow = Flow.from_client_config(
         CLIENT_CONFIG, scopes=SCOPES, redirect_uri=REDIRECT_URI,
-        state=request.session['state']
+        state=saved['value']
     )
     flow.fetch_token(code=request.query_params.get('code'))
     creds = flow.credentials
-    request.session['credentials'] = {
-        'token': creds.token,
-        'refresh_token': creds.refresh_token,
-        'token_uri': creds.token_uri,
-        'client_id': creds.client_id,
-        'client_secret': creds.client_secret,
-        'scopes': list(creds.scopes or [])
-    }
+    userinfo = build('oauth2', 'v2', credentials=creds).userinfo().get().execute()
+    # Opaque id in the cookie; credentials in the server-side encrypted store.
+    sid = request.session.get('sid') or secrets.token_urlsafe(32)
+    request.session['sid'] = sid
+    request.session['principal'] = userinfo['id']
+    credential_store.put(sid, principal=userinfo['id'], credentials={
+        'token': creds.token, 'refresh_token': creds.refresh_token,
+        'token_uri': creds.token_uri, 'client_id': creds.client_id,
+        'client_secret': creds.client_secret, 'scopes': list(creds.scopes or []),
+    })
     return RedirectResponse('/profile')
 
 
 @app.get('/profile')
 async def profile(request: Request):
-    if 'credentials' not in request.session:
+    stored = credential_store.get(request.session.get('sid'),
+                                  request.session.get('principal'))
+    if not stored:
         return RedirectResponse('/auth')
-    creds = Credentials(**request.session['credentials'])
+    creds = Credentials(**stored)
     service = build('oauth2', 'v2', credentials=creds)
     user_info = service.userinfo().get().execute()
     return user_info