feat(google): add hd claim to ID tokens and userinfo (#73)

Adds support for the Google Workspace `hd` (hosted domain) claim on
issued ID tokens and the `/oauth2/v2/userinfo` response, and advertises
it in the OIDC discovery document.

By default the claim is derived from the user's email domain, matching
real Google behavior for Workspace accounts. Consumer domains
(`gmail.com`, `googlemail.com`) are treated as non-Workspace and omit
the claim. Configs can override the derived value by setting `hd` on a
seeded user, or disable the claim by setting it to an empty string.

Co-authored-by: Claude <noreply@anthropic.com>

Author: disintegrator

packages/@emulators/google/src/__tests__/google.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it } from "vitest";
 import { Hono } from "hono";
+import { decodeJwt } from "jose";
 import {
   Store,
   WebhookDispatcher,
@@ -30,7 +31,11 @@ function createTestApp() {
   googlePlugin.register(app as any, store, webhooks, base, tokenMap);
   googlePlugin.seed?.(store, base);
   seedFromConfig(store, base, {
-    users: [{ email: "testuser@example.com", name: "Test User" }],
+    users: [
+      { email: "testuser@example.com", name: "Test User" },
+      { email: "consumer@gmail.com", name: "Consumer User" },
+      { email: "workspaceuser@example.com", name: "Workspace User", hd: "override.io" },
+    ],
     oauth_clients: [
       {
         client_id: "emu_google_client_id",
@@ -892,6 +897,42 @@ describe("Google plugin integration", () => {
     expect(refreshBody.scope).toBe(tokenBody.scope);
   });
 
+  it("derives, overrides, and omits the hd claim based on user config", async () => {
+    async function getIdTokenClaims(email: string) {
+      const authorize = await formRequest(app, "/o/oauth2/v2/auth/callback", {
+        email,
+        redirect_uri: "http://localhost:3000/api/auth/callback/google",
+        scope: "openid email profile",
+        client_id: "emu_google_client_id",
+      });
+      const code = new URL(authorize.headers.get("Location")!).searchParams.get("code")!;
+      const tokenRes = await formRequest(app, "/oauth2/token", {
+        code,
+        grant_type: "authorization_code",
+        redirect_uri: "http://localhost:3000/api/auth/callback/google",
+        client_id: "emu_google_client_id",
+        client_secret: "emu_google_client_secret",
+      });
+      const body = (await tokenRes.json()) as { id_token: string; access_token: string };
+      return { claims: decodeJwt(body.id_token) as { hd?: string }, accessToken: body.access_token };
+    }
+
+    const derived = await getIdTokenClaims("testuser@example.com");
+    expect(derived.claims.hd).toBe("example.com");
+
+    const overridden = await getIdTokenClaims("workspaceuser@example.com");
+    expect(overridden.claims.hd).toBe("override.io");
+
+    const consumer = await getIdTokenClaims("consumer@gmail.com");
+    expect(consumer.claims.hd).toBeUndefined();
+
+    const userinfoRes = await app.request(`${base}/oauth2/v2/userinfo`, {
+      headers: { Authorization: `Bearer ${overridden.accessToken}` },
+    });
+    expect(userinfoRes.status).toBe(200);
+    expect(((await userinfoRes.json()) as { hd?: string }).hd).toBe("override.io");
+  });
+
   it("lists calendar resources, creates events, queries freebusy, and deletes events", async () => {
     const calendarListRes = await app.request(`${base}/calendar/v3/users/me/calendarList`, {
       headers: authHeaders(),

packages/@emulators/google/src/entities.ts

@@ -9,6 +9,7 @@ export interface GoogleUser extends Entity {
   picture: string | null;
   email_verified: boolean;
   locale: string;
+  hd: string | null;
 }
 
 export interface GoogleOAuthClient extends Entity {

packages/@emulators/google/src/index.ts

@@ -32,6 +32,7 @@ export interface GoogleSeedUser {
   picture?: string;
   locale?: string;
   email_verified?: boolean;
+  hd?: string;
 }
 
 export interface GoogleSeedLabel {
@@ -141,6 +142,7 @@ function seedDefaults(store: Store, _baseUrl: string): void {
       picture: null,
       email_verified: true,
       locale: "en",
+      hd: null,
     });
   }
 
@@ -275,6 +277,20 @@ function seedDefaults(store: Store, _baseUrl: string): void {
   );
 }
 
+const CONSUMER_EMAIL_DOMAINS = new Set(["gmail.com", "googlemail.com"]);
+
+function deriveHd(email: string): string | null {
+  const domain = email.split("@")[1]?.toLowerCase();
+  if (!domain) return null;
+  if (CONSUMER_EMAIL_DOMAINS.has(domain)) return null;
+  return domain;
+}
+
+function resolveHd(user: GoogleSeedUser): string | null {
+  if (user.hd !== undefined) return user.hd || null;
+  return deriveHd(user.email);
+}
+
 export function seedFromConfig(store: Store, _baseUrl: string, config: GoogleSeedConfig): void {
   const gs = getGoogleStore(store);
 
@@ -292,6 +308,7 @@ export function seedFromConfig(store: Store, _baseUrl: string, config: GoogleSee
           picture: user.picture ?? null,
           email_verified: user.email_verified ?? true,
           locale: user.locale ?? "en",
+          hd: resolveHd(user),
         });
       }
 

packages/@emulators/google/src/routes/oauth.ts

@@ -76,6 +76,7 @@ async function createIdToken(
     family_name: user.family_name,
     picture: user.picture,
     locale: user.locale,
+    ...(user.hd ? { hd: user.hd } : {}),
     ...(nonce ? { nonce } : {}),
   })
     .setProtectedHeader({ alg: "HS256", typ: "JWT" })
@@ -105,7 +106,17 @@ export function oauthRoutes({ app, store, baseUrl, tokenMap }: RouteContext): vo
       id_token_signing_alg_values_supported: ["HS256"],
       scopes_supported: ["openid", "email", "profile"],
       token_endpoint_auth_methods_supported: ["client_secret_post", "client_secret_basic"],
-      claims_supported: ["sub", "email", "email_verified", "name", "given_name", "family_name", "picture", "locale"],
+      claims_supported: [
+        "sub",
+        "email",
+        "email_verified",
+        "name",
+        "given_name",
+        "family_name",
+        "picture",
+        "locale",
+        "hd",
+      ],
       code_challenge_methods_supported: ["plain", "S256"],
     });
   });
@@ -377,6 +388,7 @@ export function oauthRoutes({ app, store, baseUrl, tokenMap }: RouteContext): vo
       family_name: user.family_name,
       picture: user.picture,
       locale: user.locale,
+      ...(user.hd ? { hd: user.hd } : {}),
     });
   });