@ssheleg/sheleg-dev 0.11.8 → 0.13.0

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

package/plugins/sheleg-dev/skills/google-auth/references/sign-in-with-google.md

@@ -228,8 +228,7 @@ from pydantic import BaseModel
 
 class GoogleLoginRequest(BaseModel):
     credential: str
-    g_csrf_token: str | None = None
-    nonce: str | None = None
+    g_csrf_token: str | None = None   # no nonce field — the server holds the expectation
 
 @router.post("/google")
 async def google_login(request: Request, body: GoogleLoginRequest):
@@ -265,38 +264,54 @@ def google_login():
 
 ## Nonce Verification
 
-Pass a nonce to `google.accounts.id.initialize()` on the client, then verify it server-side against the token's `nonce` claim.
+**The server issues the nonce; the client never invents one.** A
+client-generated nonce sent back beside the credential proves nothing: the
+"expected" value would be read out of the very JWT it is meant to check, so a
+stolen token replays with its own nonce. The contract (shared with
+`google-signin` — one contract, both skills):
+
+1. `GET /api/auth/google/nonce` — the server mints a random value, stores it
+   with a TTL bound to a **pre-auth HttpOnly session cookie**, returns it.
+2. The client passes that value to `google.accounts.id.initialize({nonce})`.
+3. On the callback the server **pops the expectation (one-time consume) and
+   requires the token's `nonce` claim to equal it exactly.** Missing claim,
+   missing expectation, expiry and re-use all reject; the POST body carries
+   no nonce and plays no part in the check.
 
 **Client-side:**
 
 ```js
-const nonce = crypto.randomUUID();  // or any random string
+const nonce = (await (await fetch('/api/auth/google/nonce')).json()).nonce;
 google.accounts.id.initialize({
   client_id: CLIENT_ID,
-  callback: handleResponse,
-  nonce: nonce
+  callback: handleResponse,   // POSTs { credential } only
+  nonce
 });
-// Send nonce alongside credential to your backend
 ```
 
 **Server-side (Node.js):**
 
 ```js
+const sid = req.cookies.preauth || '';
+const expected = await nonceStore.pop(sid);        // one-time consume, with TTL
 const payload = ticket.getPayload();
-if (payload.nonce !== expectedNonce) {
-  throw new Error('Nonce mismatch');
+if (!expected || payload.nonce !== expected) {
+  throw new Error('Nonce missing, expired, replayed or not server-issued');
 }
 ```
 
 **Server-side (Python):**
 
 ```python
-if body.nonce:
-    token_nonce = payload.get('nonce')
-    if not token_nonce or token_nonce != body.nonce:
-        raise ValueError('Nonce mismatch')
+sid = request.cookies.get('preauth') or ''
+expected = nonce_store.pop(sid)                    # one-time consume, with TTL
+if not expected or payload.get('nonce') != expected:
+    raise ValueError('Nonce missing, expired, replayed or not server-issued')
 ```
 
+First sign-in passes; a replay from a new session meets a different
+expectation; a replay after consume meets none.
+
 ## ID Token Payload Fields
 
 | Field | Description |
@@ -474,8 +489,7 @@ CLIENT_ID = settings.google_client_id
 
 class GoogleLoginRequest(BaseModel):
     credential: str
-    g_csrf_token: str | None = None
-    nonce: str | None = None
+    g_csrf_token: str | None = None   # no nonce field — the server holds the expectation
 
 @router.post("/auth/google")
 async def google_login(request: Request, body: GoogleLoginRequest):
@@ -494,10 +508,13 @@ async def google_login(request: Request, body: GoogleLoginRequest):
     if not payload.get("email_verified", False):
         raise HTTPException(status_code=401, detail="Email not verified")
 
-    # 3. Verify nonce
-    if body.nonce:
-        if payload.get("nonce") != body.nonce:
-            raise HTTPException(status_code=401, detail="Nonce mismatch")
+    # 3. Verify nonce — MANDATORY, against the server's own expectation.
+    # pop() consumes it in the same step (one-time); the body carries no nonce.
+    sid = request.cookies.get("preauth") or ""
+    expected = nonce_store.pop(sid)          # server-issued, TTL'd (see §Nonce Verification)
+    if not expected or payload.get("nonce") != expected:
+        raise HTTPException(status_code=401,
+                            detail="Nonce missing, expired, replayed or not server-issued")
 
     # 4. Find or create user, issue app JWT...
     user, is_new = await find_or_create_google_user(db, payload)

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

@@ -33,19 +33,27 @@ implementation this skill ships.
 
 ## Core flow (ID-token)
 
-1. Frontend: `google.accounts.id.initialize({ client_id, callback, nonce })`
-   + `renderButton()`. Generate a **fresh random nonce per render**
-   (`crypto.randomUUID()`). The GSI script loads async — retry rendering
-   (e.g. 20 × 150 ms) instead of silently dropping the button.
+1. Frontend: fetch a **server-issued nonce** first (`GET /api/auth/google/nonce`
+   — the server stores it with a TTL, bound to a pre-auth HttpOnly cookie),
+   then `google.accounts.id.initialize({ client_id, callback, nonce })`
+   + `renderButton()`. A client-generated nonce POSTed back proves nothing:
+   the value would be read out of the very JWT it is meant to check. The GSI
+   script loads async — retry rendering (e.g. 20 × 150 ms) instead of
+   silently dropping the button.
 2. Callback receives `{ credential }` — a Google-signed ID token (JWT).
-   POST it with the nonce to your backend. Never treat it as a session.
+   POST it alone to your backend (no nonce in the body). Never treat it as a
+   session.
 3. Backend: verify with the official lib — Python
    `google.oauth2.id_token.verify_oauth2_token(credential, transport, CLIENT_ID)`,
    Node `google-auth-library` `verifyIdToken({ idToken, audience })`. That
    checks signature (Google JWKS), `aud`, `iss`, `exp`. Never hand-decode
    and trust the payload.
-4. Additionally require `email_verified == true` and token `nonce` claim ==
-   submitted nonce.
+4. Additionally require `email_verified == true` and **pop the expected nonce
+   from the pre-auth session (one-time consume) and require the token `nonce`
+   claim to equal it exactly** — a missing claim, a missing expectation, an
+   expired or an already-consumed nonce all reject. This is what makes a
+   stolen token non-replayable: a replay from a new session meets a different
+   expectation, a replay in the same session meets a consumed one.
 5. Find-or-create the user, then issue YOUR OWN session (app JWT) as an
    **HttpOnly + Secure + SameSite=Strict cookie**. Google's token is
    verified once, never stored, never logged.
@@ -56,25 +64,49 @@ Key the user on `sub` (stable Google user ID; store as `google_id`) — never
 on email (emails change, `sub` doesn't). On each Google login:
 
 1. Record with this `google_id` exists → login (refresh name/picture).
-2. Email matches an existing account without `google_id` → link, BUT apply
-   the **pre-hijacking guard**: if that account is password-based and its
-   email was never verified, REFUSE the auto-link ("sign in with your
-   password instead"). Otherwise an attacker who pre-registered the
-   victim's email with a known password captures the victim's first Google
-   login into the attacker's record.
-3. No match → create the user with `email_verified=True`, empty password
-   hash.
+2. Email matches an existing account without `google_id` → **do NOT auto-link
+   on `email_verified` alone.** `email_verified` is Google saying it verified
+   the inbox ONCE, not that this person owns the LOCAL account, and for a
+   third-party address Google is not even authoritative that they still own the
+   inbox. Default: link only after a **fresh re-auth of the existing local
+   account** (its password / existing factor), so the person proves they hold
+   the account Google is being attached to.
+   - Auto-link WITHOUT that re-auth is allowed only when Google is
+     **authoritative for the address** — `email_verified` AND (the address is
+     `@gmail.com` OR the token carries an `hd` Workspace-domain claim) — AND
+     the existing account's own email ownership was proven. For any other
+     (third-party) address, run an **independent challenge** (a link to that
+     inbox) before linking; Google's one-time verification is not current proof.
+   - If the existing account is a password account whose email was **never
+     verified** (a possible pre-registration hijack), send the person into a
+     **safe account-recovery flow** — never "sign in with the existing
+     password", which may be the attacker's.
+3. No match → create the user. Mark `email_verified=True` only when Google is
+   authoritative for the address (Gmail or `hd`); for a third-party address
+   record it unverified and challenge the inbox before granting anything that
+   trusts the email.
 
 ## Login-CSRF (cover BOTH delivery flows)
 
-- Form-POST flow (`login_uri` auto-POST): GIS double-submits `g_csrf_token`
-  in body AND cookie — compare constant-time (`hmac.compare_digest`);
-  reject if either side is missing.
-- JS-fetch flow: no `g_csrf_token` — enforce same-origin via Fetch-Metadata
-  (`Sec-Fetch-Site: same-origin`) with an Origin-allowlist fallback.
-
-Without this, an attacker's page can force-POST the *attacker's* credential
-and silently log the victim into the attacker's account.
+The two delivery flows are **separate, explicitly typed paths**, chosen by
+Content-Type — not one handler that claims both. A skeleton that declares form
+support but only binds a JSON body does not actually run the form contract.
+
+- **Form-POST flow** (`login_uri` auto-POST, `application/x-www-form-urlencoded`):
+  GIS double-submits `g_csrf_token` in the FORM BODY and the cookie — require
+  BOTH present and equal, constant-time (`hmac.compare_digest`). Missing either
+  side → reject. This token is the whole authorization for the form path.
+- **JS-fetch flow** (`application/json`): no `g_csrf_token`, so require a
+  trusted same-origin signal — `Sec-Fetch-Site: same-origin` (browser-set,
+  unforgeable), OR, only when that header is ABSENT, an exact `Origin` in an
+  allowlist. A **missing `Sec-Fetch-Site` is NOT assumed same-origin**;
+  `cross-site` and `none` are rejected; and with neither a trusted metadata
+  value nor an allowed Origin the request **fails closed**.
+
+The CSRF decision runs BEFORE the token is verified — no external call on a
+request that has not proven its origin. Without this, an attacker's page can
+force-POST the *attacker's* credential and silently log the victim into the
+attacker's account.
 
 ## Setup (GCP)
 
@@ -119,3 +151,12 @@ and silently log the victim into the attacker's account.
 | `access_denied` on consent | Consent screen still in Testing → publish the app |
 | Works locally, breaks in prod | Prod origin missing in GCP, or `Secure` cookie served over plain HTTP |
 | One Tap missing / FedCM console warnings | FedCM is mandatory since Aug 2025 and the opt-out is gone (checked 2026-08-06). Load `gsi/client` from Google and keep it current — a vendored or pinned copy is the real break. The rendered button flow is unaffected; code branching on the old `isNotDisplayed()` moment callbacks is not |
+
+## Degradation
+
+- **Not Claude Code** (Cursor, Codex, the skills CLI, the API container): the pack's
+  `PreToolUse` gate does not run — the rules here hold, the refusal does not.
+- **No browser channel**: the sign-in button and its redirect are verified by reading
+  the code, not by watching it work. Record that as the weaker claim it is.
+- **No console access**: creating the OAuth client is a human step; state it once, do
+  the rest, and say what is waiting on it.