refactor: rename user to userClaims and UserIdentity to UserClaims

Sets the right expectation that ctx.userClaims is JWT-derived
identity, not the full Supabase User object. JSDoc points to
supabase.auth.getUser() for the complete User.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tomaspozo

README.md

@@ -40,7 +40,7 @@ Deno.serve(
   withSupabase({ allow: 'user' }, async (req, ctx) => {
     // ctx.supabase — RLS-scoped to the authenticated user
     // ctx.supabaseAdmin — bypasses RLS (service role)
-    // ctx.user — user identity (id, email, role)
+    // ctx.userClaims — user identity from JWT (id, email, role)
     // ctx.claims — JWT claims
     // ctx.authType — which auth mode matched
 
@@ -76,7 +76,7 @@ Deno.serve(
 ```ts
 Deno.serve(
   withSupabase({ allow: ['user', 'secret'] }, async (req, ctx) => {
-    const userId = ctx.user?.id ?? (await req.json()).user_id
+    const userId = ctx.userClaims?.id ?? (await req.json()).user_id
     const { data } = await ctx.supabaseAdmin
       .from('reports')
       .select()
@@ -107,7 +107,7 @@ Every handler receives a `SupabaseContext`:
 interface SupabaseContext {
   supabase: SupabaseClient // RLS-scoped (user or anon depending on auth)
   supabaseAdmin: SupabaseClient // Bypasses RLS
-  user: UserIdentity | null // Present when auth is JWT
+  userClaims: UserClaims | null // JWT-derived identity (for full User, call supabase.auth.getUser())
   claims: JWTClaims | null // Present when auth is JWT
   authType: Allow // Which auth mode matched
 }

src/core/verify-credentials.test.ts

@@ -253,8 +253,8 @@ describe('verifyCredentials', () => {
       })
       expect(result.error).toBeNull()
       expect(result.data!.authType).toBe('user')
-      expect(result.data!.user!.id).toBe('user-123')
-      expect(result.data!.user!.email).toBe('test@example.com')
+      expect(result.data!.userClaims!.id).toBe('user-123')
+      expect(result.data!.userClaims!.email).toBe('test@example.com')
       expect(result.data!.claims!.sub).toBe('user-123')
       expect(result.data!.token).toBe(validToken)
     })

src/core/verify-credentials.ts

@@ -8,7 +8,7 @@ import type {
   Credentials,
   JWTClaims,
   SupabaseEnv,
-  UserIdentity,
+  UserClaims,
 } from '../types.js'
 import { timingSafeEqual } from './utils/timing-safe-equal.js'
 import { resolveEnv } from './resolve-env.js'
@@ -37,7 +37,7 @@ function parseAllowMode(mode: AllowWithKey): {
   return { base, keyName }
 }
 
-function claimsToUser(claims: JWTClaims): UserIdentity {
+function claimsToUserClaims(claims: JWTClaims): UserClaims {
   return {
     id: claims.sub,
     role: claims.role,
@@ -56,7 +56,7 @@ async function tryMode(
 
   switch (base) {
     case 'always':
-      return { authType: 'always', token: null, user: null, claims: null }
+      return { authType: 'always', token: null, userClaims: null, claims: null }
 
     case 'public': {
       if (!credentials.apikey) return null
@@ -65,14 +65,24 @@ async function tryMode(
       if (keyName === '*') {
         for (const value of Object.values(keys)) {
           if (await timingSafeEqual(credentials.apikey, value)) {
-            return { authType: 'public', token: null, user: null, claims: null }
+            return {
+              authType: 'public',
+              token: null,
+              userClaims: null,
+              claims: null,
+            }
           }
         }
       } else {
         const name = keyName ?? 'default'
         const value = keys[name]
         if (value && (await timingSafeEqual(credentials.apikey, value))) {
-          return { authType: 'public', token: null, user: null, claims: null }
+          return {
+            authType: 'public',
+            token: null,
+            userClaims: null,
+            claims: null,
+          }
         }
       }
       return null
@@ -85,14 +95,24 @@ async function tryMode(
       if (keyName === '*') {
         for (const value of Object.values(keys)) {
           if (await timingSafeEqual(credentials.apikey, value)) {
-            return { authType: 'secret', token: null, user: null, claims: null }
+            return {
+              authType: 'secret',
+              token: null,
+              userClaims: null,
+              claims: null,
+            }
           }
         }
       } else {
         const name = keyName ?? 'default'
         const value = keys[name]
         if (value && (await timingSafeEqual(credentials.apikey, value))) {
-          return { authType: 'secret', token: null, user: null, claims: null }
+          return {
+            authType: 'secret',
+            token: null,
+            userClaims: null,
+            claims: null,
+          }
         }
       }
       return null
@@ -111,7 +131,7 @@ async function tryMode(
         return {
           authType: 'user',
           token: credentials.token,
-          user: claimsToUser(claims),
+          userClaims: claimsToUserClaims(claims),
           claims,
         }
       } catch {

src/create-supabase-context.test.ts

@@ -31,7 +31,7 @@ describe('createSupabaseContext', () => {
       env: baseEnv,
     })
 
-    expect(result.data!.user).toBeNull()
+    expect(result.data!.userClaims).toBeNull()
     expect(result.data!.claims).toBeNull()
   })
 

src/create-supabase-context.ts

@@ -28,7 +28,7 @@ export async function createSupabaseContext(
       data: {
         supabase,
         supabaseAdmin,
-        user: auth.user,
+        userClaims: auth.userClaims,
         claims: auth.claims,
         authType: auth.authType,
       },

src/index.ts

@@ -14,7 +14,7 @@ export type {
   JWTClaims,
   SupabaseContext,
   SupabaseEnv,
-  UserIdentity,
+  UserClaims,
   WithSupabaseConfig,
 } from './types.js'
 export { AuthError, EnvError } from './errors.js'

src/types.ts

@@ -22,7 +22,7 @@ export interface Credentials {
 export interface AuthResult {
   authType: Allow
   token: string | null
-  user: UserIdentity | null
+  userClaims: UserClaims | null
   claims: JWTClaims | null
 }
 
@@ -39,7 +39,7 @@ export interface JWTClaims {
   [key: string]: unknown
 }
 
-export interface UserIdentity {
+export interface UserClaims {
   id: string
   role?: string
   email?: string
@@ -56,7 +56,8 @@ export interface WithSupabaseConfig {
 export interface SupabaseContext {
   supabase: SupabaseClient
   supabaseAdmin: SupabaseClient
-  user: UserIdentity | null
+  /** JWT-derived identity. For the full Supabase User object, call `supabase.auth.getUser()`. */
+  userClaims: UserClaims | null
   claims: JWTClaims | null
   authType: Allow
 }