@pya-platform/auth 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @pya/auth
+
+## 0.1.0
+
+### Minor Changes
+
+- a9ca6bf: Initial release of the Pya platform packages. Extracted from `pyaeats-app`, consumed by `pyaeats-app` (food delivery) and `pyaserv` (services classifieds).
+
+  Each package exposes a Hono router factory (auth/cms/reviews/comments) or a typed helper (email/audit/cf) parameterised over Cloudflare D1 + KV bindings. UI primitives ship as Lit web components on top of `@pya/tokens` (CSS custom properties). See `ROADMAP.md` and `docs/phase-6-rollout.md` for the consumer cutover plan.
+
+### Patch Changes
+
+- Updated dependencies [a9ca6bf]
+  - @pya/shared@0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pya-platform/auth",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/undeadliner/pya-platform.git"
+  },
+  "type": "module",
+  "description": "Auth engine — passwordless (OTP + magic link), passkey/WebAuthn, OAuth, recovery codes, sessions (KV), CSRF. Hono router factories parameterised over D1/KV bindings.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./routes/passwordless": "./src/routes/passwordless.ts",
+    "./routes/oauth": "./src/routes/oauth.ts",
+    "./routes/dev-bypass": "./src/routes/dev-bypass.ts",
+    "./session": "./src/session.ts",
+    "./migrations/*": "./src/migrations/*"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "echo '@pya/auth has no tests yet'"
+  },
+  "dependencies": {
+    "@pya-platform/shared": "workspace:*",
+    "@simplewebauthn/server": "^13.3.0",
+    "effect": "^3.10.0",
+    "hono": "^4.6.0",
+    "jose": "^5.9.0",
+    "valibot": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^4.20240909.0"
+  }
+}

package/src/env.ts

@@ -0,0 +1,57 @@
+// The shape every Pya host worker must supply to `@pya-platform/auth` via `Bindings`.
+// Hosts can extend this with their own bindings — Hono merges via intersection.
+// Keep this interface narrow: only what auth itself touches.
+
+export interface PyaAuthBindings {
+  /** Primary database (sessions/users/passkeys/recovery_codes/audit) */
+  readonly DB: D1Database
+  /** Session KV — bound to a separate namespace from cache KVs */
+  readonly SESSIONS: KVNamespace
+  /** OAuth state KV — short-TTL nonces */
+  readonly OAUTH_STATE: KVNamespace
+  /** Deployment env — controls SameSite policy and dev-bypass gating */
+  readonly ENVIRONMENT: 'development' | 'preview' | 'staging' | 'production'
+  /** Customer-facing site origin (cookie domain anchoring) */
+  readonly SITE_ORIGIN: string
+  /** Admin site origin (separate cookie name) */
+  readonly ADMIN_ORIGIN: string
+  /** API self origin (for OAuth callback URL construction) */
+  readonly API_ORIGIN: string
+
+  /** Pepper for IP/UA hashes — rotate without invalidating sessions */
+  readonly SESSION_PEPPER?: string
+  /** CSRF HMAC signing key */
+  readonly CSRF_HMAC_KEY?: string
+  /** Cloudflare Turnstile secret (bot protection) */
+  readonly TURNSTILE_SECRET?: string
+
+  /** Resend API key (passwordless email) */
+  readonly RESEND_API_KEY?: string
+  /** Email "from" domain — must be verified in Resend */
+  readonly EMAIL_DOMAIN?: string
+
+  /** WebAuthn relying-party identifier (e.g. `pyaeats.com`) */
+  readonly WEBAUTHN_RP_ID?: string
+  /** Comma-separated allowed origins for WebAuthn assertions */
+  readonly WEBAUTHN_ORIGINS?: string
+
+  /** OAuth provider secrets — optional, providers without secrets return 501 */
+  readonly GOOGLE_OAUTH_CLIENT_ID?: string
+  readonly GOOGLE_OAUTH_CLIENT_SECRET?: string
+  readonly FACEBOOK_APP_ID?: string
+  readonly FACEBOOK_APP_SECRET?: string
+
+  /** OAuth endpoint overrides (E2E sidecar). Defaults baked in providers/*.ts */
+  readonly GOOGLE_AUTH_URL?: string
+  readonly GOOGLE_TOKEN_URL?: string
+  readonly GOOGLE_JWKS_URL?: string
+}
+
+// Re-exported as global `Env` so the existing code (which references `Env`
+// directly via Hono's `Bindings`) compiles without further edits. Each host
+// worker declares its own `Env` that extends `PyaAuthBindings` plus host-
+// specific fields; that augmented `Env` is what Hono sees at runtime.
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-empty-interface
+  interface Env extends PyaAuthBindings {}
+}

package/src/identity-link.ts

@@ -0,0 +1,64 @@
+import { type ProviderClaims, uuidV7 } from '@pya-platform/shared'
+import { IdentityConflictError } from '@pya-platform/shared'
+
+export interface LinkResult {
+  readonly userId: string
+  readonly created: boolean
+  readonly linked: boolean
+}
+
+const insertIdentity = (db: D1Database, userId: string, claims: ProviderClaims, ts: number) =>
+  db
+    .prepare(
+      `INSERT INTO user_identities (user_id, provider, subject, email_at_link, linked_at)
+       VALUES (?, ?, ?, ?, ?)`,
+    )
+    .bind(userId, claims.provider, claims.subject, claims.email, ts)
+
+export const provisionOrLink = async (
+  db: D1Database,
+  claims: ProviderClaims,
+  intent: 'login' | 'link',
+  currentUserId: string | undefined,
+): Promise<LinkResult> => {
+  const now = Math.floor(Date.now() / 1000)
+
+  const existing = await db
+    .prepare('SELECT user_id FROM user_identities WHERE provider = ? AND subject = ?')
+    .bind(claims.provider, claims.subject)
+    .first<{ user_id: string }>()
+
+  if (existing !== null) {
+    if (intent === 'link' && currentUserId !== undefined && existing.user_id !== currentUserId) {
+      throw new IdentityConflictError({ provider: claims.provider })
+    }
+    return { userId: existing.user_id, created: false, linked: false }
+  }
+
+  if (intent === 'link' && currentUserId !== undefined) {
+    await insertIdentity(db, currentUserId, claims, now).run()
+    return { userId: currentUserId, created: false, linked: true }
+  }
+
+  const existingUser = await db
+    .prepare("SELECT id FROM users WHERE email = ? AND status != 'deleted'")
+    .bind(claims.email)
+    .first<{ id: string }>()
+
+  if (existingUser !== null) {
+    await insertIdentity(db, existingUser.id, claims, now).run()
+    return { userId: existingUser.id, created: false, linked: true }
+  }
+
+  const userId = uuidV7()
+  await db.batch([
+    db
+      .prepare(
+        `INSERT INTO users (id, email, email_verified, display_name, locale, created_at, status)
+         VALUES (?, ?, 1, ?, ?, ?, 'active')`,
+      )
+      .bind(userId, claims.email, claims.displayName ?? null, claims.locale ?? 'es-PY', now),
+    insertIdentity(db, userId, claims, now),
+  ])
+  return { userId, created: true, linked: false }
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+// @pya-platform/auth — public surface.
+//
+// Hono router factories + middleware. Each consumer wires its own Worker
+// like so:
+//
+//   const app = new Hono<{ Bindings: Env }>()
+//   app.route('/api/auth', passwordlessRoutes)
+//   app.route('/api/auth', oauthRoutes)
+//   app.route('/api/auth/dev', createDevBypassRoutes({ onCronSweep }))
+//   app.use('/v1/*', requireAuth)
+//
+// The `Env` interface is contributed by `./env.ts` (PyaAuthBindings). Hosts
+// extend it with their own bindings — Hono merges via intersection.
+
+import './env.ts'
+
+export type { PyaAuthBindings } from './env.ts'
+export { requireAuth, issueSession, revokeSession } from './session.ts'
+export { passwordlessRoutes } from './routes/passwordless.ts'
+export { oauthRoutes } from './routes/oauth.ts'
+export { createDevBypassRoutes } from './routes/dev-bypass.ts'
+export { logAuth, type AuthEvent } from './log.ts'
+export { provisionOrLink } from './identity-link.ts'
+export {
+  newSessionId,
+  readSession,
+  touchSession,
+  writeSession,
+  deleteSession,
+} from './store/session-store.ts'
+// Re-export domain errors so consumers don't need to import @pya-platform/shared
+// separately just for `mapErrorToStatus` / `UnauthorizedError` / etc.
+export {
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  RateLimitedError,
+  UpstreamError,
+  InvalidTokenError,
+  IdentityConflictError,
+  ProviderNotEnabledError,
+  mapErrorToStatus,
+  type DomainError,
+} from '@pya-platform/shared'

package/src/log.ts

@@ -0,0 +1,27 @@
+import type { IdentityProvider } from '@pya-platform/shared'
+
+export type AuthEvent =
+  | 'auth.login.oauth'
+  | 'auth.login.email'
+  | 'auth.login.passkey'
+  | 'auth.login.recovery'
+  | 'auth.login.rejected'
+  | 'auth.email.send_failed'
+  | 'auth.passkey.registered'
+  | 'auth.recovery.generated'
+
+export type AuthProvider = IdentityProvider | 'recovery'
+
+export interface AuthLogEvent {
+  readonly event: AuthEvent
+  readonly ts: number
+  readonly userId?: string
+  readonly provider: AuthProvider
+  readonly ipHash?: string
+  readonly outcome: 'created' | 'linked' | 'reused' | 'rejected' | 'sent'
+  readonly reason?: string
+}
+
+export const logAuth = (event: AuthLogEvent): void => {
+  console.log(JSON.stringify({ stream: 'audit', ...event }))
+}

package/src/migrations/0001_users_sessions.sql

@@ -0,0 +1,70 @@
+-- 0001_init — identity & audit foundations.
+-- Migrations are applied via `wrangler d1 migrations apply` per environment.
+
+CREATE TABLE users (
+  id            TEXT PRIMARY KEY,                       -- UUID v7
+  email         TEXT NOT NULL,                          -- normalised lowercase
+  email_verified INTEGER NOT NULL DEFAULT 0,            -- 0/1
+  display_name  TEXT,
+  locale        TEXT NOT NULL DEFAULT 'es-PY',
+  created_at    INTEGER NOT NULL,                       -- unix seconds
+  status        TEXT NOT NULL DEFAULT 'active'          -- active | suspended | deleted
+);
+
+CREATE UNIQUE INDEX ux_users_email_active ON users(email) WHERE status != 'deleted';
+
+CREATE TABLE user_identities (
+  user_id        TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  provider       TEXT NOT NULL,                          -- google | apple | facebook
+  subject        TEXT NOT NULL,                          -- provider 'sub' claim
+  email_at_link  TEXT,
+  linked_at      INTEGER NOT NULL,
+  PRIMARY KEY (provider, subject)
+);
+
+CREATE INDEX ix_identities_user ON user_identities(user_id);
+
+CREATE TABLE roles (
+  user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  role        TEXT NOT NULL,                              -- customer | store_owner | store_staff | courier | admin | super_admin
+  store_id    TEXT,                                       -- NULL for global roles
+  granted_by  TEXT REFERENCES users(id),
+  granted_at  INTEGER NOT NULL,
+  PRIMARY KEY (user_id, role, store_id)
+);
+
+CREATE INDEX ix_roles_user ON roles(user_id);
+CREATE INDEX ix_roles_store ON roles(store_id, role);
+
+CREATE TABLE audit_log (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts              INTEGER NOT NULL,
+  actor_user_id   TEXT,
+  actor_role      TEXT NOT NULL,
+  actor_ip_hash   TEXT,                                   -- HMAC-SHA256(ip, SESSION_PEPPER)
+  action          TEXT NOT NULL,
+  target_type     TEXT,
+  target_id       TEXT,
+  store_id        TEXT,
+  details_json    TEXT,
+  prev_hash       TEXT NOT NULL,
+  row_hash        TEXT NOT NULL
+);
+
+CREATE INDEX ix_audit_ts ON audit_log(ts);
+CREATE INDEX ix_audit_actor ON audit_log(actor_user_id, ts);
+
+-- RUM events from web-vitals beacons.
+CREATE TABLE rum_events (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  name        TEXT NOT NULL,
+  value       REAL NOT NULL,
+  rating      TEXT,
+  url         TEXT NOT NULL,
+  ua          TEXT,
+  ts          INTEGER NOT NULL,
+  session_id  TEXT
+);
+
+CREATE INDEX ix_rum_name_ts ON rum_events(name, ts);
+CREATE INDEX ix_rum_url ON rum_events(url, ts);

package/src/migrations/0002_passkeys.sql

@@ -0,0 +1,17 @@
+-- 0004_passkeys — WebAuthn credential storage for spec 011.
+-- Applied via `wrangler d1 migrations apply pyaeats-preview --remote`.
+
+CREATE TABLE passkeys (
+  credential_id     TEXT PRIMARY KEY,                          -- base64url
+  user_id           TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  public_key        TEXT NOT NULL,                              -- base64url-encoded COSE key bytes
+  sign_count        INTEGER NOT NULL DEFAULT 0,
+  transports        TEXT,                                       -- JSON array, e.g. ["internal","hybrid"]
+  label             TEXT,                                       -- user-friendly device label
+  created_at        INTEGER NOT NULL,                           -- unix seconds
+  last_used_at      INTEGER NOT NULL,
+  backup_eligible   INTEGER NOT NULL DEFAULT 0,                 -- 0/1
+  backup_state      INTEGER NOT NULL DEFAULT 0                  -- 0/1
+);
+
+CREATE INDEX ix_passkeys_user ON passkeys(user_id);

package/src/migrations/0003_recovery_codes.sql

@@ -0,0 +1,24 @@
+-- Recovery codes — one-time fallback when both passkey AND email OTP fail
+-- (lost device + lost mailbox + lost recovery key on the third device, etc).
+--
+-- A user enrolling a passkey for the first time gets 8 codes generated and
+-- displayed ONCE. They store them outside the app (password manager, paper).
+-- Redeeming a code:
+--   • marks it used (`used_at`)
+--   • invalidates ALL existing passkeys for that user (security best practice —
+--     a leaked code means the account is compromised; force re-enrolment)
+--   • mints a session
+--
+-- We store only the hash, never the plaintext. PBKDF2-SHA256 1-round w/
+-- per-row salt is enough for short-lived (~years) high-entropy (64 bits)
+-- secrets; we don't need Argon2 cost overhead. Salt + hash are both 32 bytes,
+-- encoded as 64-char hex.
+CREATE TABLE recovery_codes (
+  user_id    TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  salt_hex   TEXT NOT NULL,                 -- 32 bytes hex = 64 chars
+  code_hash  TEXT NOT NULL,                 -- 32 bytes hex = 64 chars
+  used_at    INTEGER,                       -- unix-seconds when redeemed
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (user_id, code_hash)
+);
+CREATE INDEX ix_recovery_codes_user ON recovery_codes(user_id, used_at);

package/src/oauth-callback.ts

@@ -0,0 +1,102 @@
+import {
+  type OAuthProvider,
+  OAuthProviderSchema,
+  type OAuthState,
+  OAuthStateSchema,
+  type ProviderClaims,
+} from '@pya-platform/shared'
+import { UnauthorizedError } from '@pya-platform/shared'
+import type { Context } from 'hono'
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
+import * as v from 'valibot'
+import { provisionOrLink } from './identity-link.ts'
+import { logAuth } from './log.ts'
+import { exchangeAndVerifyApple } from './providers/apple.ts'
+import { exchangeAndVerifyFacebook } from './providers/facebook.ts'
+import { exchangeAndVerifyGoogle } from './providers/google.ts'
+import { issueSession } from './session.ts'
+
+export const buildRedirectUri = (env: Env, provider: OAuthProvider): string =>
+  `${env.API_ORIGIN}/api/auth/callback/${provider}`
+
+const exchangeForProvider = (
+  env: Env,
+  provider: OAuthProvider,
+  redirectUri: string,
+  code: string,
+  state: OAuthState,
+): Promise<ProviderClaims> => {
+  switch (provider) {
+    case 'google':
+      return exchangeAndVerifyGoogle(env, redirectUri, code, state.verifier, state.nonce)
+    case 'facebook':
+      return exchangeAndVerifyFacebook(env, redirectUri, code, state.verifier, state.nonce)
+    case 'apple':
+      return exchangeAndVerifyApple(env, redirectUri, code, state.verifier, state.nonce)
+  }
+}
+
+const sha256Hex = async (input: string): Promise<string> => {
+  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input))
+  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+const outcomeOf = (created: boolean, linked: boolean): 'created' | 'linked' | 'reused' =>
+  created ? 'created' : linked ? 'linked' : 'reused'
+
+export const handleOAuthCallback = async (c: Context<{ Bindings: Env }>): Promise<Response> => {
+  const provider = v.parse(OAuthProviderSchema, c.req.param('provider'))
+
+  const code = c.req.query('code')
+  const stateQ = c.req.query('state')
+  const cookieState = getCookie(c, 'pya_oauth_state')
+  deleteCookie(c, 'pya_oauth_state', { path: '/api/auth' })
+
+  if (
+    code === undefined ||
+    stateQ === undefined ||
+    cookieState === undefined ||
+    stateQ !== cookieState
+  ) {
+    throw new UnauthorizedError({ reason: 'invalid state' })
+  }
+
+  const raw = await c.env.OAUTH_STATE.get(`oauth:state:${stateQ}`, { type: 'json' })
+  if (raw === null) {
+    throw new UnauthorizedError({ reason: 'expired or replayed state' })
+  }
+  await c.env.OAUTH_STATE.delete(`oauth:state:${stateQ}`)
+
+  const stateRecord = v.parse(OAuthStateSchema, raw)
+  if (stateRecord.provider !== provider) {
+    throw new UnauthorizedError({ reason: 'provider mismatch' })
+  }
+
+  const redirectUri = buildRedirectUri(c.env, provider)
+  const claims = await exchangeForProvider(c.env, provider, redirectUri, code, stateRecord)
+
+  const link = await provisionOrLink(
+    c.env.DB,
+    claims,
+    stateRecord.intent ?? 'login',
+    stateRecord.currentUserId,
+  )
+
+  const ip = c.req.header('CF-Connecting-IP') ?? ''
+  logAuth({
+    event: 'auth.login.oauth',
+    ts: Math.floor(Date.now() / 1000),
+    userId: link.userId,
+    provider,
+    ipHash: await sha256Hex(ip + (c.env.SESSION_PEPPER ?? '')),
+    outcome: outcomeOf(link.created, link.linked),
+  })
+
+  await issueSession(c, setCookie, false, {
+    userId: link.userId,
+    roles: ['customer'],
+    storeIds: [],
+  })
+
+  return c.redirect(stateRecord.redirectAfter, 302)
+}

package/src/providers/apple.ts

@@ -0,0 +1,12 @@
+import type { ProviderClaims } from '@pya-platform/shared'
+import { ProviderNotEnabledError } from '@pya-platform/shared'
+
+export const exchangeAndVerifyApple = async (
+  _env: Env,
+  _redirectUri: string,
+  _code: string,
+  _verifier: string,
+  _nonce: string,
+): Promise<ProviderClaims> => {
+  throw new ProviderNotEnabledError({ provider: 'apple' })
+}

package/src/providers/facebook.ts

@@ -0,0 +1,12 @@
+import type { ProviderClaims } from '@pya-platform/shared'
+import { ProviderNotEnabledError } from '@pya-platform/shared'
+
+export const exchangeAndVerifyFacebook = async (
+  _env: Env,
+  _redirectUri: string,
+  _code: string,
+  _verifier: string,
+  _nonce: string,
+): Promise<ProviderClaims> => {
+  throw new ProviderNotEnabledError({ provider: 'facebook' })
+}

package/src/providers/google.ts

@@ -0,0 +1,117 @@
+import { type ProviderClaims, ProviderClaimsSchema } from '@pya-platform/shared'
+import { InvalidTokenError, UpstreamError } from '@pya-platform/shared'
+import { type JSONWebKeySet, createLocalJWKSet, jwtVerify } from 'jose'
+import * as v from 'valibot'
+
+const DEFAULT_TOKEN_URL = 'https://oauth2.googleapis.com/token'
+const DEFAULT_JWKS_URL = 'https://www.googleapis.com/oauth2/v3/certs'
+const ISSUERS: ReadonlySet<string> = new Set(['accounts.google.com', 'https://accounts.google.com'])
+
+interface TokenResponse {
+  readonly id_token?: string
+}
+
+const buildBody = (
+  code: string,
+  clientId: string,
+  clientSecret: string,
+  redirectUri: string,
+  verifier: string,
+): URLSearchParams =>
+  new URLSearchParams({
+    code,
+    client_id: clientId,
+    client_secret: clientSecret,
+    redirect_uri: redirectUri,
+    grant_type: 'authorization_code',
+    code_verifier: verifier,
+  })
+
+interface JwksEntry {
+  readonly jwks: JSONWebKeySet
+  readonly fetchedAt: number
+}
+const jwksCache = new Map<string, JwksEntry>()
+const JWKS_TTL_MS = 6 * 60 * 60 * 1000
+
+const fetchJwks = async (url: string): Promise<JSONWebKeySet> => {
+  const cached = jwksCache.get(url)
+  if (cached !== undefined && Date.now() - cached.fetchedAt < JWKS_TTL_MS) {
+    return cached.jwks
+  }
+  const res = await fetch(url)
+  if (!res.ok) throw new UpstreamError({ provider: 'google', status: res.status })
+  const jwks = (await res.json()) as JSONWebKeySet
+  jwksCache.set(url, { jwks, fetchedAt: Date.now() })
+  return jwks
+}
+
+/** Test-only: clear JWKS cache. */
+export const __resetJwksCache = (): void => {
+  jwksCache.clear()
+}
+
+export const exchangeAndVerifyGoogle = async (
+  env: Env,
+  redirectUri: string,
+  code: string,
+  verifier: string,
+  nonce: string,
+): Promise<ProviderClaims> => {
+  const clientId = env.GOOGLE_OAUTH_CLIENT_ID ?? ''
+  const clientSecret = env.GOOGLE_OAUTH_CLIENT_SECRET ?? ''
+  const tokenUrl = env.GOOGLE_TOKEN_URL ?? DEFAULT_TOKEN_URL
+  const jwksUrl = env.GOOGLE_JWKS_URL ?? DEFAULT_JWKS_URL
+
+  const res = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: buildBody(code, clientId, clientSecret, redirectUri, verifier),
+  })
+  if (!res.ok) throw new UpstreamError({ provider: 'google', status: res.status })
+
+  const tokenJson = (await res.json()) as TokenResponse
+  const idToken = tokenJson.id_token
+  if (idToken === undefined) {
+    throw new InvalidTokenError({ reason: 'missing id_token' })
+  }
+
+  const jwksSet = createLocalJWKSet(await fetchJwks(jwksUrl))
+  const verified = await verifyOrThrow(idToken, jwksSet, clientId)
+  const payload = verified.payload
+
+  if (typeof payload.iss !== 'string' || !ISSUERS.has(payload.iss)) {
+    throw new InvalidTokenError({ reason: 'bad iss' })
+  }
+  if (payload.nonce !== nonce) {
+    throw new InvalidTokenError({ reason: 'nonce mismatch' })
+  }
+  if (payload.email_verified !== true) {
+    throw new InvalidTokenError({ reason: 'email_unverified' })
+  }
+  if (typeof payload.sub !== 'string' || typeof payload.email !== 'string') {
+    throw new InvalidTokenError({ reason: 'missing sub/email' })
+  }
+
+  return v.parse(ProviderClaimsSchema, {
+    provider: 'google',
+    subject: payload.sub,
+    email: payload.email,
+    emailVerified: true,
+    displayName: typeof payload.name === 'string' ? payload.name : undefined,
+    locale: typeof payload.locale === 'string' ? payload.locale : undefined,
+  })
+}
+
+const verifyOrThrow = async (
+  idToken: string,
+  jwks: ReturnType<typeof createLocalJWKSet>,
+  audience: string,
+): Promise<Awaited<ReturnType<typeof jwtVerify>>> => {
+  try {
+    return await jwtVerify(idToken, jwks, { audience })
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : 'verify failed'
+    throw new InvalidTokenError({ reason })
+  }
+}