@ssheleg/sheleg-dev 0.11.8 → 0.12.0

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)
 

package/plugins/sheleg-dev/skills/google-signin/references/full-guide.md

@@ -41,21 +41,25 @@ secrets, no redirect URIs, no token storage for Google APIs.
  Browser                       Google                        Your backend
  ───────                       ──────                        ────────────
  1. load gsi/client script
- 2. google.accounts.id.initialize({client_id, callback, nonce})
+ 0. GET /api/auth/google/nonce ────────────────────────────► server issues nonce,
+    (pre-auth HttpOnly cookie set)                              stores it w/ TTL
+ 2. google.accounts.id.initialize({client_id, callback, nonce: serverIssued})
  3. renderButton(#container)
  4. user clicks button ──────► account-chooser popup
                                (user picks account,
                                 consents on first use)
  5. callback receives  ◄────── ID token (JWT, RS256-signed
     {credential: "<jwt>"}       by Google's private key)
- 6. POST /api/auth/google {credential, nonce} ─────────────► 7. verify ID token:
+ 6. POST /api/auth/google {credential} ────────────────────► 7. verify ID token:
                                                                 - signature vs Google JWKS
                                                                   (https://www.googleapis.com/oauth2/v3/certs)
                                                                 - aud == YOUR client_id
                                                                 - iss == accounts.google.com
                                                                 - exp not passed
                                                                 - email_verified == true
-                                                                - nonce matches
+                                                                - nonce claim == server
+                                                                  expectation (popped:
+                                                                  one-time consume)
                                                              8. find-or-create user,
                                                                 link accounts
                                                              9. issue YOUR OWN session
@@ -81,7 +85,7 @@ Payload claims you care about:
   "email_verified": true,
   "name": "Ada Lovelace",
   "picture": "https://lh3.googleusercontent.com/…",
-  "nonce": "d9b2d63d-…",       // echoed from initialize() — replay defense
+  "nonce": "d9b2d63d-…",       // the SERVER-issued value passed to initialize()
   "iat": 1719410000,
   "exp": 1719413600            // ~1 hour lifetime
 }
@@ -107,7 +111,7 @@ Payload claims you care about:
 // app.js (essentials)
 var _googleNonce = '';
 
-function _renderGoogleButton() {
+async function _renderGoogleButton() {
   var clientId = _getGoogleClientId();          // read from the <meta> tag
   if (!clientId) return;                        // Google auth not configured → hide, degrade honestly
   if (typeof google === 'undefined' || !google.accounts) {
@@ -115,7 +119,10 @@ function _renderGoogleButton() {
     if (_googleRenderRetries++ < 20) setTimeout(_renderGoogleButton, 150);
     return;
   }
-  _googleNonce = crypto.randomUUID();           // fresh nonce per render — replay defense
+  // SERVER-issued nonce: the backend stores it (TTL, pre-auth HttpOnly cookie)
+  // and will pop it on the callback — the client never invents the value.
+  var nr = await fetch('/api/auth/google/nonce');
+  _googleNonce = (await nr.json()).nonce;
 
   google.accounts.id.initialize({
     client_id: clientId,
@@ -135,7 +142,7 @@ async function handleGoogleCredential(response) {
   var resp = await fetch('/api/auth/google', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ credential: response.credential, nonce: _googleNonce }),
+    body: JSON.stringify({ credential: response.credential }),
   });
   var data = await resp.json();
   if (!resp.ok) { showError(data.detail); return; }
@@ -185,14 +192,21 @@ Every Google login resolves to exactly one of three cases:
 
 1. **Returning Google user** — a record with this `google_id` (`sub`) exists
    → issue session. Refresh `name`/`picture` if they changed.
-2. **Existing email/password account, no `google_id`** — link Google to it
-   (set `google_id`, mark `email_verified=True`) → issue session.
-   ⚠️ **Pre-hijacking guard** (see §4.3): only auto-link if the existing
-   account's email ownership was verified. Otherwise refuse with "sign in
-   with your password".
-3. **Brand-new user** — create the account with `email_verified=True` (the
-   Google token already proved inbox ownership), empty password hash → issue
-   session.
+2. **Existing account, no `google_id`** — `email_verified` is NOT authority to
+   attach Google to it. It means Google verified the inbox once; it does not
+   mean this person owns the LOCAL account, and for a third-party address it
+   does not even mean they still own the inbox. Default: link only after a
+   **fresh re-auth of the existing local account** (§4.3). Auto-link without
+   re-auth is permitted only when `google_authoritative(payload)` — the address
+   is `@gmail.com` or the token carries an `hd` Workspace claim — AND the
+   existing record's own email ownership was proven; for any other address run
+   an **independent inbox challenge** first. If the existing account is a
+   password account whose email was **never verified**, route to **safe
+   account recovery** (§4.3), never to the existing password.
+3. **Brand-new user** — create the account, empty password hash. Mark
+   `email_verified=True` only when `google_authoritative(payload)`; for a
+   third-party address (non-Gmail, no `hd`) create it UNVERIFIED and challenge
+   the inbox before anything trusts the email → issue session.
 
 Then issue your own session. Prowl issues an HS256 app JWT (72 h, `ver` claim
 for global revocation) delivered as an **HttpOnly, Secure, SameSite=Strict
@@ -261,11 +275,17 @@ npm i google-auth-library      # Node
 
 ### 4.2 Nonce — replay defense
 
-Generate a fresh random nonce per button render, pass it to
-`google.accounts.id.initialize({nonce})`, send it alongside the credential,
-compare server-side with the token's `nonce` claim
-(`web/auth.py:375-376`). A stolen/logged ID token can't be replayed later
-because the nonce won't match the new session's nonce.
+**The server issues the nonce; the client never invents one.** A
+client-generated nonce POSTed 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 forever. Fetch the nonce from
+`GET /api/auth/google/nonce` (the server stores it with a TTL, bound to a
+pre-auth HttpOnly session cookie), pass it to
+`google.accounts.id.initialize({nonce})`, and 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. First sign-in passes; a replay from a new session meets a different
+expectation; a replay in the same session meets a consumed one.
 
 ### 4.3 Account pre-hijacking guard (P3-01 in Prowl)
 
@@ -274,10 +294,31 @@ victim ever visits. Later the victim clicks "Sign in with Google". Naïve
 auto-linking attaches victim's Google to the **attacker's** record — attacker
 keeps password access to the merged account (its data and wallet).
 
-Defense (`web/auth.py:392-417`): when a Google login matches an existing
-**password** account whose email was **never verified**, refuse to auto-link;
-tell the user to sign in with the password. Link only when email ownership of
-the existing record is proven.
+Defense: `email_verified` is not proof of ownership OF THE LOCAL ACCOUNT, and
+Google is only authoritative for the *address* when it is Gmail or carries an
+`hd` Workspace claim — for a third-party email, ownership can have changed
+since Google verified it (Google's own guidance excludes non-Gmail without
+`hd`). So:
+
+```python
+def google_authoritative(payload):
+    email = (payload.get("email") or "").lower()
+    return bool(payload.get("email_verified")
+                and (email.endswith("@gmail.com") or payload.get("hd")))
+```
+
+- **Default** — link only after a **fresh re-auth of the existing local
+  account** (its password or existing factor). Proving you hold the account is
+  the only thing that authorizes attaching a new identity to it.
+- **Auto-link without re-auth** — permitted only when
+  `google_authoritative(payload)` AND the existing record's email ownership was
+  already proven. For any other address, run an **independent challenge** (a
+  verification link to that inbox) first.
+- **Unverified pre-registration** — when the existing password account's email
+  was never verified, DO NOT tell the victim to "sign in with the password":
+  that password may be the attacker's. Route them into a **safe
+  account-recovery flow** (reset via a fresh inbox challenge), which takes the
+  account away from whoever pre-registered it rather than handing it over.
 
 ### 4.4 Login-CSRF (P3-03 in Prowl)
 
@@ -287,12 +328,22 @@ attacker's account (victim then unknowingly feeds data/payments into it).
 
 Defense (`web/server.py:1657-1686`), covering both possible delivery flows:
 
-- **Form-POST flow** (GIS `login_uri` auto-POST): GIS double-submits
-  `g_csrf_token` in body *and* cookie — compare both, constant-time
-  (`hmac.compare_digest`). Reject if either is missing.
-- **JS-fetch flow** (this app): no `g_csrf_token`, so enforce same-origin via
-  **Fetch-Metadata** (`Sec-Fetch-Site: same-origin`) with an Origin-allowlist
-  fallback. These headers are browser-set and unforgeable by page script.
+The two flows are SEPARATE, explicitly typed paths chosen by Content-Type. A
+handler that claims form support but binds only a JSON body never runs the form
+contract — the CSRF check for the form flow (`g_csrf_token`) is on a request
+shape that flow never sends.
+
+- **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`). Reject if
+  either is missing.
+- **JS-fetch flow** (`application/json`): no `g_csrf_token`, so require a
+  trusted same-origin signal — `Sec-Fetch-Site: same-origin`, 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; with neither a trusted metadata value nor an allowed Origin the
+  request **fails closed**. These headers are browser-set and unforgeable by
+  page script. The CSRF decision runs BEFORE token verification.
 
 ### 4.5 Session hygiene
 
@@ -346,8 +397,8 @@ Defense (`web/server.py:1657-1686`), covering both possible delivery flows:
 
 ```python
 # --- backend ---
-import os, hmac
-from fastapi import FastAPI, HTTPException, Request, Response
+import os, hmac, secrets, time
+from fastapi import FastAPI, Form, HTTPException, Request, Response
 from pydantic import BaseModel
 from google.oauth2 import id_token
 from google.auth.transport import requests as google_requests
@@ -356,29 +407,79 @@ GOOGLE_CLIENT_ID = os.environ["GOOGLE_CLIENT_ID"]
 _transport = google_requests.Request()
 app = FastAPI()
 
+NONCE_TTL = 600
+_nonce_store: dict[str, tuple[str, float]] = {}   # sid -> (nonce, expires); use Redis in prod
+
+ALLOWED_ORIGINS = {"https://app.example.com"}   # your own origin(s)
+
+
 class GoogleAuthRequest(BaseModel):
     credential: str
-    nonce: str | None = None
-    g_csrf_token: str | None = None
-
-@app.post("/api/auth/google")
+    g_csrf_token: str | None = None               # no nonce in the body — the server holds it
+
+
+def _csrf_ok_form(cookie_token, form_token):
+    # The form flow's whole authorization: both present and equal, constant-time.
+    if not form_token or not cookie_token:
+        return False
+    return hmac.compare_digest(cookie_token, form_token)
+
+
+def _csrf_ok_json(sec_fetch_site, origin):
+    # Trusted metadata first; Origin allowlist ONLY as an explicit fallback when
+    # the header is absent. A missing Sec-Fetch-Site is not same-origin, and
+    # `none`/`cross-site` are rejected — fail closed when neither proves origin.
+    if sec_fetch_site == "same-origin":
+        return True
+    if sec_fetch_site in ("cross-site", "same-site", "none"):
+        return False
+    if sec_fetch_site is None:                     # header absent → exact Origin, allowlisted
+        return bool(origin) and origin in ALLOWED_ORIGINS
+    return False
+
+@app.get("/api/auth/google/nonce")
+async def google_nonce(req: Request, response: Response):
+    sid = req.cookies.get("preauth") or secrets.token_urlsafe(32)
+    nonce = secrets.token_urlsafe(32)
+    _nonce_store[sid] = (nonce, time.time() + NONCE_TTL)
+    response.set_cookie("preauth", sid, httponly=True, secure=True,
+                        samesite="lax", max_age=NONCE_TTL, path="/")
+    return {"nonce": nonce}
+
+# Two explicitly typed routes. Content-Type picks the flow; each runs ONLY its
+# own CSRF contract; both fail closed; the check is before any token call.
+
+@app.post("/api/auth/google/form")             # application/x-www-form-urlencoded
+async def google_auth_form(req: Request, response: Response,
+                           credential: str = Form(...),
+                           g_csrf_token: str = Form(None)):
+    if not _csrf_ok_form(req.cookies.get("g_csrf_token"), g_csrf_token):
+        raise HTTPException(403, "CSRF: g_csrf_token missing or mismatched")
+    return await _finish_google_auth(req, response, credential)
+
+
+@app.post("/api/auth/google")                  # application/json (JS fetch)
 async def google_auth(req: Request, data: GoogleAuthRequest, response: Response):
-    # CSRF: double-submit for form-POST flow, Fetch-Metadata for JS flow
-    if data.g_csrf_token:
-        cookie = req.cookies.get("g_csrf_token") or ""
-        if not hmac.compare_digest(cookie, data.g_csrf_token):
-            raise HTTPException(403, "CSRF token mismatch")
-    elif req.headers.get("sec-fetch-site", "same-origin") not in ("same-origin", "none"):
-        raise HTTPException(403, "Cross-site request rejected")
+    sec = req.headers.get("sec-fetch-site")    # None when the header is absent
+    if not _csrf_ok_json(sec, req.headers.get("origin")):
+        raise HTTPException(403, "CSRF: request origin not proven (fail closed)")
+    return await _finish_google_auth(req, response, data.credential)
 
+
+async def _finish_google_auth(req: Request, response: Response, credential: str):
     try:
-        payload = id_token.verify_oauth2_token(data.credential, _transport, GOOGLE_CLIENT_ID)
+        payload = id_token.verify_oauth2_token(credential, _transport, GOOGLE_CLIENT_ID)
     except Exception as exc:
         raise HTTPException(401, f"Invalid Google token: {exc}")
     if not payload.get("email_verified"):
         raise HTTPException(401, "Google account email is not verified")
-    if data.nonce and payload.get("nonce") != data.nonce:
-        raise HTTPException(401, "Nonce mismatch")
+    # One-time consume BEFORE any account work: pop() removes the expectation
+    # in the same step, so a replayed callback finds nothing. Mandatory — a
+    # missing claim or a missing expectation rejects; the body carries no nonce.
+    sid = req.cookies.get("preauth") or ""
+    expected, expires = _nonce_store.pop(sid, (None, 0.0))
+    if not expected or time.time() > expires or payload.get("nonce") != expected:
+        raise HTTPException(401, "Nonce missing, expired, replayed or not server-issued")
 
     user = await find_or_create_user(          # your 3-way linking here (§2.4, §4.3)
         google_id=payload["sub"], email=payload["email"].lower().strip(),
@@ -395,8 +496,8 @@ async def google_auth(req: Request, data: GoogleAuthRequest, response: Response)
 <script src="https://accounts.google.com/gsi/client" async defer></script>
 <div id="gbtn"></div>
 <script>
-  const NONCE = crypto.randomUUID();
-  window.onload = () => {
+  window.onload = async () => {
+    const NONCE = (await (await fetch("/api/auth/google/nonce")).json()).nonce;
     google.accounts.id.initialize({
       client_id: "YOUR_CLIENT_ID.apps.googleusercontent.com",
       nonce: NONCE,
@@ -404,7 +505,7 @@ async def google_auth(req: Request, data: GoogleAuthRequest, response: Response)
         const r = await fetch("/api/auth/google", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ credential, nonce: NONCE }),
+          body: JSON.stringify({ credential }),
         });
         if (r.ok) location.href = "/app";
       },

package/plugins/sheleg-dev/skills/stripe-billing/SKILL.md

@@ -198,7 +198,8 @@ export async function POST(request: Request) {
   }
 
   const claim = await claimEvent(event.id);              // INSERT on a primary key
-  if (claim === "duplicate") return json({ received: true, duplicate: true });
+  if (claim === "completed") return json({ received: true, duplicate: true });
+  if (claim === "in_flight") return json({ error: "in flight" }, 500); // retry later
 
   try {
     await handle(event);
@@ -215,16 +216,17 @@ export async function POST(request: Request) {
 - **Exempt this path — and only this path — from CSRF and session auth**, by
   exact match: a prefix match over `/api/billing` exempts checkout too, which is
   where the money is.
-- **Claim before working.** `SELECT` then `INSERT` is a race; two deliveries
-  40 ms apart both pass the read and both credit. Release the claim if
-  processing throws, or the retry finds the event "processed" and the work is
-  lost forever.
+- **Claim before working — a claim is a receipt, not completion.** `SELECT`
+  then `INSERT` is a race; two deliveries 40 ms apart both credit. The row
+  stays `processing` until the grant's transaction marks it `completed` —
+  states, expiry, takeover and release:
+  [`references/webhook-events.md`](references/webhook-events.md).
 - **Answer honestly.** 200 handled or duplicate, 400 bad signature, 5xx try
   again, 200 for types you do not handle. Never 200 on failure to stop retries —
   that discards a payment quietly.
 - **Order inside a handler:** fallible external calls first, then one
-  transaction, then side effects that must not run twice (emails, provisioning)
-  after it commits.
+  transaction — entitlement, dedup marker, completion, outbox rows — then side
+  effects drain from the outbox, each under its own consumer key.
 
 Per-event detail: [`references/webhook-events.md`](references/webhook-events.md).
 

package/plugins/sheleg-dev/skills/stripe-billing/fixtures/README.md

@@ -62,7 +62,17 @@ Run `node assert-money-invariants.mjs` and each line names the invariant it hold
 | `proration-invoice-grants-nothing` | cycle + proration | gives a month of product for a $40 proration invoice |
 | `sequential-redelivery-grants-once` | cycle + redelivery | answers `received` twice and sends the renewal notice and the server-side conversion twice |
 | `concurrent-redelivery-grants-once` | cycle + redelivery, in flight together | both deliveries pass the marker's `SELECT` and both credit |
+| `crash-after-receipt-is-retryable` | cycle (worker dies) + redelivery | tells the retry "duplicate" about work that never finished — the payment is swallowed forever |
+| `in-flight-claim-answers-retry-later` | cycle (worker dies) + redelivery | answers `duplicate` to a retry while the first worker may still be mid-grant |
+| `completion-is-recorded-with-the-grant` | cycle | leaves the claim row saying `processing` after answering done — every later retry reads it as a corpse |
+| `duplicate-of-completed-never-regrants` | cycle + redelivery, aged past the claim expiry | takes the completed row over as if the worker had died, and grants again |
+| `transaction-rolls-back-whole` | cycle (crash inside the transaction) | leaves the grant applied with no completion — half a payment no retry can see |
+| `crash-before-commit-applies-nothing` | cycle (crash) + redelivery | the retry double-applies or never applies what the crash interrupted |
+| `committed-retry-sends-once` | cycle, outbox redelivered | sends "your renewal" twice and counts the revenue twice |
 | `sequential-redelivery-grants-once-by-count-alone` | cycle + redelivery | *nothing* — kept because that is the finding; see below |
+| `concurrent-entry-points-grant-once` | cycle, webhook + reconciler in flight together | both pass the marker's read and one period is granted twice |
+| `serialization-conflict-does-not-lose-the-renewal` | cycle, one injected conflict | drops the conflicted transaction and answers 200 — the renewal silently never lands |
+| `exhausted-retries-answer-5xx-and-the-redelivery-lands` | cycle + redelivery, conflicts past the bound | swallows the conflict instead of answering 5xx, so nothing ever retries |
 | `reconciliation-does-not-regrant` | cycle | the nightly repair grants a period the webhook already granted |
 | `out-of-order-pair-does-not-rewind-state` | February then January | stores the older period, so the renewal date points at a period that ended |
 | `refund-total-is-cumulative` | both refunds | claws back $130 against a $90 charge |
@@ -80,7 +90,13 @@ a line a generated handler routinely omits:
 
 | Rule | The code it removes | The generated handler that ships without it |
 |---|---|---|
-| `claim` | `if (!store.claimEvent(event.id)) return duplicate` | reads the processed table, then writes it — two deliveries 40 ms apart both pass the read |
+| `claim` | the whole claim block at the top of `deliver` | reads the processed table, then writes it — two deliveries 40 ms apart both pass the read |
+| `claim-completion` | `store.completeEvent(event.id)` after the grant commits | leaves every row at `processing`, so a retry past the claim expiry reprocesses a completed event |
+| `claim-expiry` | the takeover of a `processing` row older than `CLAIM_TTL_MS` | answers "in flight" forever for a worker that died — received quietly read as completed |
+| `atomic-application` | the snapshot/restore around the business application | applies the grant and loses the completion when a crash lands mid-way |
+| `outbox-consumer-key` | the consumer's own dedup across redelivered rows | sends every redelivered outbox row again |
+| `grant-key-atomic` | the keyed INSERT claim on the period grant | falls back to read-then-mark — two concurrent grants of one period both pass the read |
+| `tx-retry-bounded` | the bounded serialization-retry loop | a conflicted transaction is dropped and the route answers 200 |
 | `billing-reason` | `if (invoice.billing_reason !== 'subscription_cycle') return` | handles `invoice.paid` as "a payment arrived" |
 | `grant-marker` | `if (granted.has(period.start)) return` | grants whenever an event says paid, including from the reconciliation job |
 | `ordering` | `if (period.start > mirror.periodStart)` around the mirror write | writes whatever arrived last |