@volter/twin-googleoauth 0.1.2 → 0.1.3

package/README.md

@@ -41,7 +41,7 @@ state builder in an isolated phase.
 Partial and honest. The manifest (`src/googleoauth-capabilities.ts`) is the **real vendor surface**
 as the denominator — authored top-down from Google's own OIDC discovery document and the four
 first-party protocol guides, **not** from what the twin has built. It currently reads
-**113 done / 164 total** (51 `todo`). The `todo`s are real Google surface this twin
+**115 done / 165 total** (50 `todo`). The `todo`s are real Google surface this twin
 does not model, most notably the whole **Google Identity Services** product (One Tap, the
 Sign in with Google button, `initTokenClient`/`initCodeClient`), the **device / limited-input flow**,
 the **implicit and hybrid** response types, and **RISC** cross-account protection.
@@ -108,6 +108,13 @@ The widely-repeated claim that `invalid_grant`'s `error_description` is `"Bad Re
 that string belongs to a malformed `invalid_request` on the jwt-bearer grant. The twin uses Google's
 documented wording for `invalid_grant` instead.
 
+The OAuth2 API v2's userinfo (`www.googleapis.com/oauth2/v2/userinfo` and its `/userinfo/v2/me` alias, which
+`@googleapis/oauth2`'s `oauth2_v2` client calls: Cal.com reads the person's photo through it when they connect Google
+Calendar) answers its Discovery document's `Userinfo` schema: `id` and `verified_email`, not v3's `sub` and
+`email_verified`, filtered by the granted scopes. It is a Discovery API, so a bad credential is its API error envelope
+(401 `UNAUTHENTICATED` with a `WWW-Authenticate: Bearer` challenge), in Google's published API wording; unlike the rows
+above, that body was not captured from this endpoint.
+
 ### Host claiming (path-aware, deliberately)
 
 `accounts.google.com` is **not an API host**: it is Google's entire sign-in web property. The
@@ -119,7 +126,7 @@ claims only the OAuth/OIDC paths this pack serves across four hosts, and everyth
 |---|---|
 | `accounts.google.com` | `/o/oauth2/*auth*`, `/o/oauth2/token`, `/signin/oauth/error`, `/.well-known/openid-configuration`, `/_twin/*` |
 | `oauth2.googleapis.com` | `/token`, `/oauth2/v4/token`, `/revoke`, `/tokeninfo` |
-| `www.googleapis.com` | `/oauth2/v1/certs`, `/oauth2/v3/{certs,userinfo}` — shared with `youtube`, split by path |
+| `www.googleapis.com` | `/oauth2/v1/certs`, `/oauth2/v3/{certs,userinfo}`, `/oauth2/v2/userinfo`, `/userinfo/v2/me` — shared with `youtube` and `googlecalendar`, split by path |
 | `openidconnect.googleapis.com` | all of it |
 
 The pack is declared **before** the pack-less `googleauth` key, so a world running both routes the

package/dist/src/googleoauth-capabilities.js

@@ -1168,7 +1168,7 @@ export const GOOGLEOAUTH_CAPABILITIES = [
         // todos (`/gsi/client`, `/o/oauth2/postmessageRelay`) — refusing those is the point: an
         // unmodelled operation must fail, not be answered by a twin that cannot serve it.
         const e = (r) => (body(r).error ?? {});
-        const paths = ['/o/oauth2/postmessageRelay', '/gsi/client', '/device/code', '/oauth2/v2/userinfo', '/oauth2/v2/certs', '/no/such/thing'];
+        const paths = ['/o/oauth2/postmessageRelay', '/gsi/client', '/device/code', '/oauth2/v2/tokeninfo', '/oauth2/v2/certs', '/no/such/thing'];
         for (const path of paths) {
             const r = await h({ m: 'GET', p: path });
             if (r.status !== 404 || e(r).code !== 404 || e(r).status !== 'NOT_FOUND')
@@ -1635,7 +1635,41 @@ export const GOOGLEOAUTH_CAPABILITIES = [
     todo('googleoauth.device.polling_errors', 'device', 'authorization_pending / slow_down / expired_token while the app polls', 'api', 'common'),
     // ── Remaining protocol surface ───────────────────────────────────────────────────────────────
     todo('googleoauth.endpoints.legacy_revoke_path', 'errors', 'GET /o/oauth2/revoke — the legacy accounts.google.com revocation path', 'api', 'niche'),
-    todo('googleoauth.endpoints.userinfo_v2', 'userinfo', 'GET /oauth2/v2/userinfo — the oldest userinfo alias (a different field set)', 'api', 'niche'),
+    done('googleoauth.endpoints.userinfo_v2', 'userinfo', 'GET /oauth2/v2/userinfo (and /userinfo/v2/me) — the OAuth2 API v2\'s Userinfo: id and verified_email, not sub and email_verified, filtered by the granted scopes', 'api', 'common', () => withRoot(async (h) => {
+        const all = await fullFlow(h, { params: { scope: 'openid email profile' } });
+        const auth = { authorization: `Bearer ${all.tokens.access_token}` };
+        const v2 = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: auth });
+        const me = await h({ m: 'GET', p: '/userinfo/v2/me', h: auth });
+        const u = body(v2);
+        const full = ok(v2) && u.id === ADA.sub && u.email === ADA.email && u.verified_email === true && u.name === ADA.name
+            && u.given_name === ADA.givenName && u.family_name === ADA.familyName && u.picture === ADA.picture
+            && u.sub === undefined && u.email_verified === undefined
+            && ok(me) && JSON.stringify(body(me)) === JSON.stringify(u);
+        // Cal.com's grant: userinfo.profile with the Calendar scopes and no email scope, so no address
+        const profileOnly = await fullFlow(h, { params: { scope: 'https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/calendar.readonly' } });
+        const p = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: `Bearer ${profileOnly.tokens.access_token}` } });
+        const emailOnly = await fullFlow(h, { params: { scope: 'https://www.googleapis.com/auth/userinfo.email' } });
+        const e = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: `Bearer ${emailOnly.tokens.access_token}` } });
+        return full
+            && ok(p) && body(p).id === ADA.sub && body(p).name === ADA.name && body(p).picture === ADA.picture && body(p).email === undefined && body(p).verified_email === undefined
+            && ok(e) && body(e).email === ADA.email && body(e).verified_email === true && body(e).name === undefined && body(e).picture === undefined;
+    })),
+    done('googleoauth.userinfo.v2_unauthenticated', 'userinfo', 'v2 userinfo refuses a missing, unknown, expired or scope-less credential with the API\'s 401 UNAUTHENTICATED envelope and a Bearer challenge — never v3\'s flat body', 'api', 'common', () => withRoot(async (h) => {
+        const unauthenticated = (r, invalid) => r.status === 401
+            && body(r).error?.status === 'UNAUTHENTICATED' && body(r).error?.code === 401
+            && String(body(r).error?.message).startsWith(invalid ? 'Request had invalid authentication credentials.' : 'Request is missing required authentication credential.')
+            && (r.headers?.['www-authenticate'] ?? '').startsWith('Bearer realm="https://accounts.google.com/"')
+            && (r.headers?.['www-authenticate'] ?? '').includes('invalid_token') === invalid;
+        const none = await h({ m: 'GET', p: '/oauth2/v2/userinfo' });
+        const bogus = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: 'Bearer ya29.not-a-real-token' } });
+        const flow = await fullFlow(h, { params: { scope: 'openid email profile' } });
+        const later = new Date(Date.parse(AT) + 3600_000).toISOString();
+        const expired = await h({ m: 'GET', p: '/oauth2/v2/userinfo', at: later, h: { authorization: `Bearer ${flow.tokens.access_token}` } });
+        const calendarOnly = await fullFlow(h, { params: { scope: 'https://www.googleapis.com/auth/calendar.readonly' } });
+        const noScope = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: `Bearer ${calendarOnly.tokens.access_token}` } });
+        return unauthenticated(none, false) && unauthenticated(bogus, true) && unauthenticated(expired, true) && unauthenticated(noScope, true)
+            && body(noScope).id === undefined;
+    })),
     todo('googleoauth.authorize.approval_prompt_legacy', 'authorize', 'approval_prompt=force — the pre-`prompt` legacy parameter still in the wild', 'api', 'niche'),
     todo('googleoauth.authorize.include_granted_scopes_incremental_ui', 'authorize', 'The consent screen shows only the NEW scopes during incremental authorization', 'ui', 'common'),
     todo('googleoauth.accounts.multi_login_authuser', 'authorize', 'The `authuser` index and multi-login sessions (several accounts signed in at once)', 'api', 'common'),

package/dist/src/googleoauth-conformance.js

@@ -194,6 +194,20 @@ const PROBES = {
         status: [200],
         expect: (b) => isObject(b) && b.sub === DEFAULT_ACCOUNTS[0].sub,
     },
+    'GET /oauth2/v2/userinfo': {
+        method: 'GET',
+        path: '/oauth2/v2/userinfo',
+        headers: { authorization: `Bearer ${ACCESS}` },
+        status: [200],
+        expect: (b) => isObject(b) && b.id === DEFAULT_ACCOUNTS[0].sub && b.verified_email === true && b.sub === undefined,
+    },
+    'GET /userinfo/v2/me': {
+        method: 'GET',
+        path: '/userinfo/v2/me',
+        headers: { authorization: `Bearer ${ACCESS}` },
+        status: [200],
+        expect: (b) => isObject(b) && b.id === DEFAULT_ACCOUNTS[0].sub && b.email === DEFAULT_ACCOUNTS[0].email,
+    },
 };
 /**
  * Every method/path pair a reader of `routeGoogleOAuthTwinRequest` can see the router branch on,
@@ -223,6 +237,8 @@ const ROUTER_SURFACE = [
     ['GET', '/oauth2/v3/userinfo'],
     ['POST', '/oauth2/v3/userinfo'],
     ['GET', '/oauth2/v2/userinfo'],
+    ['POST', '/oauth2/v2/userinfo'],
+    ['GET', '/userinfo/v2/me'],
     ['GET', '/device/code'],
     ['POST', '/device/code'],
 ];

package/dist/src/googleoauth-twin.js

@@ -11,6 +11,7 @@
 //                         GET  /tokeninfo
 //   www.googleapis.com    GET  /oauth2/v3/certs    (+ legacy /oauth2/v1/certs) → the JWKS
 //                         GET  /oauth2/v3/userinfo
+//                         GET  /oauth2/v2/userinfo  (+ /userinfo/v2/me) → the OAuth2 API v2's Userinfo
 //   openidconnect.googleapis.com GET|POST /v1/userinfo
 //
 // ── WHY THIS PACK IS BROWSER-FACING, AND WHAT THAT MEANS ────────────────────────────────────────
@@ -862,6 +863,61 @@ function userinfo(req, path, query) {
         return apiError(404, 'Requested entity was not found.', 'NOT_FOUND');
     return { status: 200, body: { sub: account.id, ...profileClaims(account, scopes) }, headers: { ...NOSTORE } };
 }
+/**
+ * The OAuth2 API v2's `userinfo.get` (`GET /oauth2/v2/userinfo`) and its `userinfo.v2.me.get` alias
+ * (`GET /userinfo/v2/me`), both on www.googleapis.com — what `@googleapis/oauth2`'s `oauth2_v2` client and
+ * `googleapis`' `google.oauth2('v2').userinfo.get()` call (Cal.com's Google Calendar callback reads the person's
+ * photo through it). Its answer is the Discovery document's `Userinfo` schema, NOT the OIDC claim set of v3:
+ * `id` (not `sub`), `verified_email` (not `email_verified`), with `email`/`verified_email` under the email scope
+ * and `name`/`given_name`/`family_name`/`picture` under the profile scope (test-fixtures/google-oauth2-v2-discovery.json,
+ * whose methods list `openid`, `userinfo.email` and `userinfo.profile`).
+ *
+ * v2 is a Discovery API served by Google's API front end, so a missing or refused credential is its API error
+ * envelope, 401 `UNAUTHENTICATED` with a `WWW-Authenticate: Bearer` challenge (Google's "Request is missing required
+ * authentication credential" / "Request had invalid authentication credentials" wording for its APIs), not the flat
+ * OAuth body v3 answers. That wording is Google's published API error text, not a capture of this endpoint. A token
+ * with none of the method's scopes is refused with the same envelope, as v3 refuses it with its own
+ * (`googleoauth.userinfo.insufficient_scope_shape` stays the todo for the exact answer).
+ */
+const V2_USERINFO_PATHS = new Set(['/oauth2/v2/userinfo', '/userinfo/v2/me']);
+const API_CREDENTIAL_HELP = 'Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.';
+function userinfoV2Unauthenticated(missing) {
+    const refused = apiError(401, `${missing ? 'Request is missing required authentication credential' : 'Request had invalid authentication credentials'}. ${API_CREDENTIAL_HELP}`, 'UNAUTHENTICATED');
+    return { ...refused, headers: { ...refused.headers, 'www-authenticate': missing ? 'Bearer realm="https://accounts.google.com/"' : 'Bearer realm="https://accounts.google.com/", error="invalid_token"' } };
+}
+function userinfoV2(req, query) {
+    const root = req.root;
+    const header = req.headers?.authorization ?? '';
+    const bearer = /^bearer\s+(.+)$/i.exec(header)?.[1]?.trim() ?? query.get('access_token') ?? query.get('oauth_token');
+    if (!bearer)
+        return userinfoV2Unauthenticated(true);
+    const row = readOne(root, 'access_token', bearer);
+    if (!row || row.revoked === true)
+        return userinfoV2Unauthenticated(false);
+    if (typeof row.expiresAt === 'number' && nowSeconds(req.occurredAt) >= row.expiresAt)
+        return userinfoV2Unauthenticated(false);
+    const scopes = parseScopeParam(String(row.scope));
+    const wantsEmail = scopes.includes('email') || scopes.includes('https://www.googleapis.com/auth/userinfo.email');
+    const wantsProfile = scopes.includes('profile') || scopes.includes('https://www.googleapis.com/auth/userinfo.profile');
+    if (!wantsEmail && !wantsProfile && !scopes.includes('openid'))
+        return userinfoV2Unauthenticated(false);
+    const account = readOne(root, 'account', String(row.sub));
+    if (!account)
+        return apiError(404, 'Requested entity was not found.', 'NOT_FOUND');
+    const present = (v) => v !== undefined && v !== null && v !== '';
+    const body = { id: account.id };
+    if (wantsEmail)
+        Object.assign(body, { email: account.email, verified_email: account.emailVerified === true });
+    if (wantsProfile) {
+        for (const [field, value] of [['name', account.name], ['given_name', account.givenName], ['family_name', account.familyName], ['picture', account.picture]]) {
+            if (present(value))
+                body[field] = value;
+        }
+    }
+    if (present(account.hd))
+        body.hd = account.hd;
+    return { status: 200, body, headers: { ...NOSTORE } };
+}
 /**
  * The OIDC discovery document. Every URL is rendered against `origin` when the caller supplied one,
  * so a DISCOVERY-DRIVEN client (openid-client) that reads this document stays inside the twin
@@ -914,6 +970,8 @@ export function googleOAuthTwinSnapshot() {
             'POST /v1/userinfo',
             'GET /oauth2/v3/userinfo',
             'POST /oauth2/v3/userinfo',
+            'GET /oauth2/v2/userinfo',
+            'GET /userinfo/v2/me',
         ],
         resourceTypes: STORE_RESOURCE_TYPES,
         grantTypes: ['authorization_code', 'refresh_token', 'urn:ietf:params:oauth:grant-type:jwt-bearer'],
@@ -1034,13 +1092,12 @@ async function routeGoogleOAuthTwinRequest(req) {
     }
     if (method === 'GET' && path === '/tokeninfo')
         return tokeninfo(req, query);
-    // `/oauth2/v2/userinfo` is NOT served: it is Google's oldest alias and returns a DIFFERENT field
-    // set, which this twin does not model (`googleoauth.endpoints.userinfo_v2`, todo). Answering it
-    // with the v3 shape would be a fake success on a route the pack itself says is unmodelled
-    // (§9 round one).
     if ((method === 'GET' || method === 'POST') && (path === '/v1/userinfo' || path === '/oauth2/v3/userinfo')) {
         return userinfo(req, path, query);
     }
+    // the OAuth2 API v2's userinfo, a different field set from v3's (userinfoV2); its Discovery methods are GET only
+    if (method === 'GET' && V2_USERINFO_PATHS.has(path))
+        return userinfoV2(req, query);
     // An operation the twin does not model fails like the vendor — never a fake success. Google's own
     // 404 on these hosts is the API error envelope.
     if (AUTH_PATHS.has(path) || path === '/token' || path === '/revoke' || path === '/tokeninfo') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-googleoauth",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Local Google OAuth 2.0 / OpenID Connect twin — the real consent screen, the real authorization-code round trip, and real RS256 id_tokens an unmodified OAuth client library completes a full flow against. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -57,10 +57,10 @@
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.2"
+    "@volter/world-core": "2.0.3"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.2",
+    "@volter/world-core": "2.0.3",
     "@volter/world-tooling": "0.1.0",
     "google-auth-library": "^9.15.1",
     "@types/bun": "^1.2.20",

package/src/googleoauth-capabilities.ts

@@ -1281,7 +1281,7 @@ export const GOOGLEOAUTH_CAPABILITIES: CapabilitySpec[] = [
       // todos (`/gsi/client`, `/o/oauth2/postmessageRelay`) — refusing those is the point: an
       // unmodelled operation must fail, not be answered by a twin that cannot serve it.
       const e = (r: GoogleOAuthResponse) => (body(r).error ?? {}) as Body;
-      const paths = ['/o/oauth2/postmessageRelay', '/gsi/client', '/device/code', '/oauth2/v2/userinfo', '/oauth2/v2/certs', '/no/such/thing'];
+      const paths = ['/o/oauth2/postmessageRelay', '/gsi/client', '/device/code', '/oauth2/v2/tokeninfo', '/oauth2/v2/certs', '/no/such/thing'];
       for (const path of paths) {
         const r = await h({ m: 'GET', p: path });
         if (r.status !== 404 || e(r).code !== 404 || e(r).status !== 'NOT_FOUND') return false;
@@ -1757,7 +1757,43 @@ export const GOOGLEOAUTH_CAPABILITIES: CapabilitySpec[] = [
 
   // ── Remaining protocol surface ───────────────────────────────────────────────────────────────
   todo('googleoauth.endpoints.legacy_revoke_path', 'errors', 'GET /o/oauth2/revoke — the legacy accounts.google.com revocation path', 'api', 'niche'),
-  todo('googleoauth.endpoints.userinfo_v2', 'userinfo', 'GET /oauth2/v2/userinfo — the oldest userinfo alias (a different field set)', 'api', 'niche'),
+  done('googleoauth.endpoints.userinfo_v2', 'userinfo', 'GET /oauth2/v2/userinfo (and /userinfo/v2/me) — the OAuth2 API v2\'s Userinfo: id and verified_email, not sub and email_verified, filtered by the granted scopes', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const all = await fullFlow(h, { params: { scope: 'openid email profile' } });
+      const auth = { authorization: `Bearer ${all.tokens.access_token}` };
+      const v2 = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: auth });
+      const me = await h({ m: 'GET', p: '/userinfo/v2/me', h: auth });
+      const u = body(v2);
+      const full = ok(v2) && u.id === ADA.sub && u.email === ADA.email && u.verified_email === true && u.name === ADA.name
+        && u.given_name === ADA.givenName && u.family_name === ADA.familyName && u.picture === ADA.picture
+        && u.sub === undefined && u.email_verified === undefined
+        && ok(me) && JSON.stringify(body(me)) === JSON.stringify(u);
+      // Cal.com's grant: userinfo.profile with the Calendar scopes and no email scope, so no address
+      const profileOnly = await fullFlow(h, { params: { scope: 'https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/calendar.readonly' } });
+      const p = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: `Bearer ${profileOnly.tokens.access_token}` } });
+      const emailOnly = await fullFlow(h, { params: { scope: 'https://www.googleapis.com/auth/userinfo.email' } });
+      const e = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: `Bearer ${emailOnly.tokens.access_token}` } });
+      return full
+        && ok(p) && body(p).id === ADA.sub && body(p).name === ADA.name && body(p).picture === ADA.picture && body(p).email === undefined && body(p).verified_email === undefined
+        && ok(e) && body(e).email === ADA.email && body(e).verified_email === true && body(e).name === undefined && body(e).picture === undefined;
+    })),
+  done('googleoauth.userinfo.v2_unauthenticated', 'userinfo', 'v2 userinfo refuses a missing, unknown, expired or scope-less credential with the API\'s 401 UNAUTHENTICATED envelope and a Bearer challenge — never v3\'s flat body', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const unauthenticated = (r: GoogleOAuthResponse, invalid: boolean) => r.status === 401
+        && (body(r).error as Body | undefined)?.status === 'UNAUTHENTICATED' && (body(r).error as Body | undefined)?.code === 401
+        && String((body(r).error as Body | undefined)?.message).startsWith(invalid ? 'Request had invalid authentication credentials.' : 'Request is missing required authentication credential.')
+        && (r.headers?.['www-authenticate'] ?? '').startsWith('Bearer realm="https://accounts.google.com/"')
+        && (r.headers?.['www-authenticate'] ?? '').includes('invalid_token') === invalid;
+      const none = await h({ m: 'GET', p: '/oauth2/v2/userinfo' });
+      const bogus = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: 'Bearer ya29.not-a-real-token' } });
+      const flow = await fullFlow(h, { params: { scope: 'openid email profile' } });
+      const later = new Date(Date.parse(AT) + 3600_000).toISOString();
+      const expired = await h({ m: 'GET', p: '/oauth2/v2/userinfo', at: later, h: { authorization: `Bearer ${flow.tokens.access_token}` } });
+      const calendarOnly = await fullFlow(h, { params: { scope: 'https://www.googleapis.com/auth/calendar.readonly' } });
+      const noScope = await h({ m: 'GET', p: '/oauth2/v2/userinfo', h: { authorization: `Bearer ${calendarOnly.tokens.access_token}` } });
+      return unauthenticated(none, false) && unauthenticated(bogus, true) && unauthenticated(expired, true) && unauthenticated(noScope, true)
+        && body(noScope).id === undefined;
+    })),
   todo('googleoauth.authorize.approval_prompt_legacy', 'authorize', 'approval_prompt=force — the pre-`prompt` legacy parameter still in the wild', 'api', 'niche'),
   todo('googleoauth.authorize.include_granted_scopes_incremental_ui', 'authorize', 'The consent screen shows only the NEW scopes during incremental authorization', 'ui', 'common'),
   todo('googleoauth.accounts.multi_login_authuser', 'authorize', 'The `authuser` index and multi-login sessions (several accounts signed in at once)', 'api', 'common'),

package/src/googleoauth-conformance.ts

@@ -222,6 +222,20 @@ const PROBES: Record<string, Probe> = {
     status: [200],
     expect: (b) => isObject(b) && b.sub === DEFAULT_ACCOUNTS[0]!.sub,
   },
+  'GET /oauth2/v2/userinfo': {
+    method: 'GET',
+    path: '/oauth2/v2/userinfo',
+    headers: { authorization: `Bearer ${ACCESS}` },
+    status: [200],
+    expect: (b) => isObject(b) && b.id === DEFAULT_ACCOUNTS[0]!.sub && b.verified_email === true && b.sub === undefined,
+  },
+  'GET /userinfo/v2/me': {
+    method: 'GET',
+    path: '/userinfo/v2/me',
+    headers: { authorization: `Bearer ${ACCESS}` },
+    status: [200],
+    expect: (b) => isObject(b) && b.id === DEFAULT_ACCOUNTS[0]!.sub && b.email === DEFAULT_ACCOUNTS[0]!.email,
+  },
 };
 
 /**
@@ -252,6 +266,8 @@ const ROUTER_SURFACE: Array<[string, string]> = [
   ['GET', '/oauth2/v3/userinfo'],
   ['POST', '/oauth2/v3/userinfo'],
   ['GET', '/oauth2/v2/userinfo'],
+  ['POST', '/oauth2/v2/userinfo'],
+  ['GET', '/userinfo/v2/me'],
   ['GET', '/device/code'],
   ['POST', '/device/code'],
 ];

package/src/googleoauth-twin.ts

@@ -11,6 +11,7 @@
 //                         GET  /tokeninfo
 //   www.googleapis.com    GET  /oauth2/v3/certs    (+ legacy /oauth2/v1/certs) → the JWKS
 //                         GET  /oauth2/v3/userinfo
+//                         GET  /oauth2/v2/userinfo  (+ /userinfo/v2/me) → the OAuth2 API v2's Userinfo
 //   openidconnect.googleapis.com GET|POST /v1/userinfo
 //
 // ── WHY THIS PACK IS BROWSER-FACING, AND WHAT THAT MEANS ────────────────────────────────────────
@@ -1006,6 +1007,56 @@ function userinfo(req: GoogleOAuthRequest, path: string, query: URLSearchParams)
   return { status: 200, body: { sub: account.id, ...profileClaims(account, scopes) }, headers: { ...NOSTORE } };
 }
 
+/**
+ * The OAuth2 API v2's `userinfo.get` (`GET /oauth2/v2/userinfo`) and its `userinfo.v2.me.get` alias
+ * (`GET /userinfo/v2/me`), both on www.googleapis.com — what `@googleapis/oauth2`'s `oauth2_v2` client and
+ * `googleapis`' `google.oauth2('v2').userinfo.get()` call (Cal.com's Google Calendar callback reads the person's
+ * photo through it). Its answer is the Discovery document's `Userinfo` schema, NOT the OIDC claim set of v3:
+ * `id` (not `sub`), `verified_email` (not `email_verified`), with `email`/`verified_email` under the email scope
+ * and `name`/`given_name`/`family_name`/`picture` under the profile scope (test-fixtures/google-oauth2-v2-discovery.json,
+ * whose methods list `openid`, `userinfo.email` and `userinfo.profile`).
+ *
+ * v2 is a Discovery API served by Google's API front end, so a missing or refused credential is its API error
+ * envelope, 401 `UNAUTHENTICATED` with a `WWW-Authenticate: Bearer` challenge (Google's "Request is missing required
+ * authentication credential" / "Request had invalid authentication credentials" wording for its APIs), not the flat
+ * OAuth body v3 answers. That wording is Google's published API error text, not a capture of this endpoint. A token
+ * with none of the method's scopes is refused with the same envelope, as v3 refuses it with its own
+ * (`googleoauth.userinfo.insufficient_scope_shape` stays the todo for the exact answer).
+ */
+const V2_USERINFO_PATHS = new Set(['/oauth2/v2/userinfo', '/userinfo/v2/me']);
+const API_CREDENTIAL_HELP = 'Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.';
+
+function userinfoV2Unauthenticated(missing: boolean): GoogleOAuthResponse {
+  const refused = apiError(401, `${missing ? 'Request is missing required authentication credential' : 'Request had invalid authentication credentials'}. ${API_CREDENTIAL_HELP}`, 'UNAUTHENTICATED');
+  return { ...refused, headers: { ...refused.headers, 'www-authenticate': missing ? 'Bearer realm="https://accounts.google.com/"' : 'Bearer realm="https://accounts.google.com/", error="invalid_token"' } };
+}
+
+function userinfoV2(req: GoogleOAuthRequest, query: URLSearchParams): GoogleOAuthResponse {
+  const root = req.root;
+  const header = req.headers?.authorization ?? '';
+  const bearer = /^bearer\s+(.+)$/i.exec(header)?.[1]?.trim() ?? query.get('access_token') ?? query.get('oauth_token');
+  if (!bearer) return userinfoV2Unauthenticated(true);
+  const row = readOne(root, 'access_token', bearer);
+  if (!row || row.revoked === true) return userinfoV2Unauthenticated(false);
+  if (typeof row.expiresAt === 'number' && nowSeconds(req.occurredAt) >= row.expiresAt) return userinfoV2Unauthenticated(false);
+  const scopes = parseScopeParam(String(row.scope));
+  const wantsEmail = scopes.includes('email') || scopes.includes('https://www.googleapis.com/auth/userinfo.email');
+  const wantsProfile = scopes.includes('profile') || scopes.includes('https://www.googleapis.com/auth/userinfo.profile');
+  if (!wantsEmail && !wantsProfile && !scopes.includes('openid')) return userinfoV2Unauthenticated(false);
+  const account = readOne(root, 'account', String(row.sub));
+  if (!account) return apiError(404, 'Requested entity was not found.', 'NOT_FOUND');
+  const present = (v: unknown) => v !== undefined && v !== null && v !== '';
+  const body: Record<string, unknown> = { id: account.id };
+  if (wantsEmail) Object.assign(body, { email: account.email, verified_email: account.emailVerified === true });
+  if (wantsProfile) {
+    for (const [field, value] of [['name', account.name], ['given_name', account.givenName], ['family_name', account.familyName], ['picture', account.picture]] as const) {
+      if (present(value)) body[field] = value;
+    }
+  }
+  if (present(account.hd)) body.hd = account.hd;
+  return { status: 200, body, headers: { ...NOSTORE } };
+}
+
 /**
  * The OIDC discovery document. Every URL is rendered against `origin` when the caller supplied one,
  * so a DISCOVERY-DRIVEN client (openid-client) that reads this document stays inside the twin
@@ -1059,6 +1110,8 @@ export function googleOAuthTwinSnapshot(): { implementedEndpoints: string[]; res
       'POST /v1/userinfo',
       'GET /oauth2/v3/userinfo',
       'POST /oauth2/v3/userinfo',
+      'GET /oauth2/v2/userinfo',
+      'GET /userinfo/v2/me',
     ],
     resourceTypes: STORE_RESOURCE_TYPES,
     grantTypes: ['authorization_code', 'refresh_token', 'urn:ietf:params:oauth:grant-type:jwt-bearer'],
@@ -1190,13 +1243,11 @@ async function routeGoogleOAuthTwinRequest(req: GoogleOAuthRequest): Promise<Goo
     return revoke(req, form.get('token') ?? query.get('token'));
   }
   if (method === 'GET' && path === '/tokeninfo') return tokeninfo(req, query);
-  // `/oauth2/v2/userinfo` is NOT served: it is Google's oldest alias and returns a DIFFERENT field
-  // set, which this twin does not model (`googleoauth.endpoints.userinfo_v2`, todo). Answering it
-  // with the v3 shape would be a fake success on a route the pack itself says is unmodelled
-  // (§9 round one).
   if ((method === 'GET' || method === 'POST') && (path === '/v1/userinfo' || path === '/oauth2/v3/userinfo')) {
     return userinfo(req, path, query);
   }
+  // the OAuth2 API v2's userinfo, a different field set from v3's (userinfoV2); its Discovery methods are GET only
+  if (method === 'GET' && V2_USERINFO_PATHS.has(path)) return userinfoV2(req, query);
 
   // An operation the twin does not model fails like the vendor — never a fake success. Google's own
   // 404 on these hosts is the API error envelope.