@leanmcp/auth 0.2.0 → 0.3.0

package/README.md

@@ -5,11 +5,12 @@ Authentication module for LeanMCP providing token-based authentication decorator
 ## Features
 
 - **@Authenticated decorator** - Protect MCP tools, prompts, and resources with token authentication
+- **Automatic authUser injection** - Access decoded user info via global `authUser` variable in protected methods
 - **Multi-provider support** - AWS Cognito, Clerk, Auth0
 - **Method or class-level protection** - Apply to individual methods or entire services
 - **Automatic token validation** - Validates tokens before method execution
 - **Custom error handling** - Detailed error codes for different auth failures
-- **Type-safe** - Full TypeScript support with type inference
+- **Type-safe** - Full TypeScript support with type inference and global type declarations
 - **OAuth & Session modes** - Support for both session-based and OAuth refresh token flows
 
 ## Installation
@@ -59,13 +60,20 @@ import { Tool } from "@leanmcp/core";
 import { Authenticated } from "@leanmcp/auth";
 
 export class SentimentService {
-  // This method requires authentication
+  // This method requires authentication with automatic user info
   @Tool({ description: 'Analyze sentiment (requires auth)' })
-  @Authenticated(authProvider)
+  @Authenticated(authProvider) // getUser: true by default
   async analyzeSentiment(input: { text: string }) {
     // Token is automatically validated from _meta.authorization.token
-    // Only business arguments are passed to the method
-    return { sentiment: 'positive', score: 0.8 };
+    // authUser is automatically available with decoded JWT payload
+    console.log('User ID:', authUser.sub);
+    console.log('Email:', authUser.email);
+    
+    return { 
+      sentiment: 'positive', 
+      score: 0.8,
+      analyzedBy: authUser.sub
+    };
   }
 
   // This method is public
@@ -86,16 +94,134 @@ import { Authenticated } from "@leanmcp/auth";
 export class SecureService {
   @Tool({ description: 'Protected tool 1' })
   async tool1(input: { data: string }) {
-    // All methods require authentication via _meta
+    // authUser is automatically available in all methods
+    console.log('Authenticated user:', authUser.email);
+    return { data: input.data, userId: authUser.sub };
   }
 
   @Tool({ description: 'Protected tool 2' })
   async tool2(input: { data: string }) {
-    // All methods require authentication via _meta
+    // authUser is available here too
+    return { data: input.data, userId: authUser.sub };
   }
 }
 ```
 
+## authUser Variable
+
+### Automatic User Information Injection
+
+When you use the `@Authenticated` decorator, a global `authUser` variable is automatically injected into your protected methods containing the decoded JWT token payload.
+
+```typescript
+@Tool({ description: 'Create post' })
+@Authenticated(authProvider)
+async createPost(input: { title: string, content: string }) {
+  // authUser is automatically available - no need to pass it as a parameter
+  console.log('User ID:', authUser.sub);
+  console.log('Email:', authUser.email);
+  
+  return {
+    id: generateId(),
+    title: input.title,
+    content: input.content,
+    authorId: authUser.sub,
+    authorEmail: authUser.email
+  };
+}
+```
+
+### Controlling User Data Fetching
+
+You can control whether user information is fetched using the `getUser` option:
+
+```typescript
+// Fetch user info (default behavior)
+@Authenticated(authProvider, { getUser: true })
+async methodWithUserInfo(input: any) {
+  // authUser is available
+  console.log(authUser);
+}
+
+// Only verify token, don't fetch user info
+@Authenticated(authProvider, { getUser: false })
+async methodWithoutUserInfo(input: any) {
+  // authUser is undefined
+  // Faster execution, use when you only need token validation
+}
+```
+
+### Provider-Specific User Data
+
+The structure of `authUser` depends on your authentication provider:
+
+**AWS Cognito:**
+```typescript
+{
+  sub: 'user-uuid',
+  email: 'user@example.com',
+  email_verified: true,
+  'cognito:username': 'username',
+  'cognito:groups': ['admin', 'users'],
+  // ... other Cognito claims
+}
+```
+
+**Clerk:**
+```typescript
+{
+  sub: 'user_2abc123xyz',
+  userId: 'user_2abc123xyz',
+  email: 'user@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  imageUrl: 'https://img.clerk.com/...',
+  // ... other Clerk claims
+}
+```
+
+**Auth0:**
+```typescript
+{
+  sub: 'auth0|507f1f77bcf86cd799439011',
+  email: 'user@example.com',
+  email_verified: true,
+  name: 'John Doe',
+  picture: 'https://s.gravatar.com/avatar/...',
+  // ... other Auth0 claims
+}
+```
+
+### TypeScript Support
+
+The `authUser` variable is globally declared and available without TypeScript errors:
+
+```typescript
+// No need to import or declare authUser
+@Authenticated(authProvider)
+async myMethod(input: any) {
+  // TypeScript knows about authUser
+  const userId: string = authUser.sub;
+  const email: string = authUser.email;
+}
+```
+
+For better type safety, you can create a typed interface:
+
+```typescript
+interface MyAuthUser {
+  sub: string;
+  email: string;
+  name?: string;
+}
+
+@Authenticated(authProvider)
+async myMethod(input: any) {
+  const user = authUser as MyAuthUser;
+  console.log(user.email); // Fully typed
+}
+```
+
 ## Usage
 
 ### Client Side - Calling Protected Methods
@@ -345,13 +471,24 @@ class AuthProvider {
 ### @Authenticated Decorator
 
 ```typescript
-function Authenticated(authProvider: AuthProvider): ClassDecorator | MethodDecorator;
+function Authenticated(
+  authProvider: AuthProvider, 
+  options?: AuthenticatedOptions
+): ClassDecorator | MethodDecorator;
+
+interface AuthenticatedOptions {
+  getUser?: boolean; // Default: true
+}
 ```
 
 Can be applied to:
 - **Classes** - Protects all methods in the class
 - **Methods** - Protects individual methods
 
+**Options:**
+- `getUser: true` (default) - Fetches user info and injects `authUser` variable
+- `getUser: false` - Only validates token, skips user info fetch (faster)
+
 ### AuthenticationError
 
 ```typescript
@@ -415,9 +552,17 @@ await authProvider.init();
 // Create service with protected methods
 @Authenticated(authProvider)
 class MyService {
-  @Tool()
+  @Tool({ description: 'Process protected data' })
   async protectedTool(input: { data: string }) {
-    return { result: "Protected data" };
+    // authUser is automatically available
+    console.log('User:', authUser.sub);
+    console.log('Email:', authUser.email);
+    
+    return { 
+      result: "Protected data",
+      processedBy: authUser.sub,
+      userEmail: authUser.email
+    };
   }
 }
 
@@ -457,9 +602,27 @@ await authProviderOAuth.init();
 @Authenticated(authProvider)
 class UserService {
   @Tool({ description: 'Get user profile' })
-  async getProfile(input: { userId: string }) {
-    // Token is automatically validated
-    return { userId: input.userId, name: "John Doe" };
+  async getProfile() {
+    // authUser is automatically available with Clerk user data
+    return { 
+      userId: authUser.userId || authUser.sub,
+      email: authUser.email,
+      firstName: authUser.firstName,
+      lastName: authUser.lastName,
+      imageUrl: authUser.imageUrl
+    };
+  }
+  
+  @Tool({ description: 'Create user post' })
+  async createPost(input: { title: string, content: string }) {
+    // Access authUser in any protected method
+    return {
+      id: generateId(),
+      title: input.title,
+      content: input.content,
+      authorId: authUser.userId,
+      authorEmail: authUser.email
+    };
   }
 }
 
@@ -492,13 +655,27 @@ await authProvider.init();
 class SecureAPIService {
   @Tool({ description: 'Get sensitive data' })
   async getSensitiveData(input: { dataId: string }) {
-    // Token is automatically validated
-    return { dataId: input.dataId, data: "Sensitive information" };
+    // authUser is automatically available with Auth0 user data
+    console.log('User:', authUser.sub);
+    console.log('Email:', authUser.email);
+    
+    return { 
+      dataId: input.dataId, 
+      data: "Sensitive information",
+      accessedBy: authUser.sub,
+      userName: authUser.name
+    };
   }
   
   @Tool({ description: 'Update user settings' })
   async updateSettings(input: { settings: Record<string, any> }) {
-    return { success: true, settings: input.settings };
+    // Access authUser in any protected method
+    return { 
+      success: true, 
+      settings: input.settings,
+      userId: authUser.sub,
+      updatedBy: authUser.email
+    };
   }
 }
 
@@ -533,17 +710,27 @@ await auth0Auth.init();
 // Use different providers for different services
 @Authenticated(clerkAuth)
 class UserService {
-  @Tool()
-  async getUserData(input: { userId: string }) {
-    return { userId: input.userId };
+  @Tool({ description: 'Get user data' })
+  async getUserData() {
+    // authUser contains Clerk user data
+    return { 
+      userId: authUser.userId,
+      email: authUser.email,
+      firstName: authUser.firstName
+    };
   }
 }
 
 @Authenticated(auth0Auth)
 class AdminService {
-  @Tool()
-  async getAdminData(input: { adminId: string }) {
-    return { adminId: input.adminId };
+  @Tool({ description: 'Get admin data' })
+  async getAdminData() {
+    // authUser contains Auth0 user data
+    return { 
+      adminId: authUser.sub,
+      email: authUser.email,
+      name: authUser.name
+    };
   }
 }
 ```
@@ -554,14 +741,19 @@ class AdminService {
 2. **Decorator intercepts** the method call before execution
 3. **Token is extracted** from `_meta.authorization.token`
 4. **Token is validated** using the configured auth provider
-5. **Method executes** with clean business arguments (no token)
-6. **Response returns** to client
+5. **User info is fetched** (if `getUser: true`) and decoded from JWT
+6. **authUser is injected** as a global variable in method scope
+7. **Method executes** with clean business arguments and access to `authUser`
+8. **authUser is cleaned up** after method execution
+9. **Response returns** to client
 
 **Key Benefits:**
 - **Clean separation** - Authentication metadata separate from business data
 - **MCP compliant** - Follows standard `_meta` pattern
 - **Type-safe** - Input classes don't need token fields
+- **Automatic user injection** - Access user data via `authUser` without manual extraction
 - **Reusable** - Same input classes work for authenticated and public methods
+- **Secure** - `authUser` is scoped to method execution and cleaned up after
 
 ## Best Practices
 
@@ -575,6 +767,9 @@ class AdminService {
 8. **Choose the right mode** - Use Session mode for simpler setups, OAuth mode for refresh tokens
 9. **Test token expiration** - Ensure your app handles expired tokens gracefully
 10. **Monitor JWKS cache** - Providers cache JWKS keys for performance
+11. **Use authUser for user context** - Access user data via `authUser` instead of parsing tokens manually
+12. **Type authUser when needed** - Cast `authUser` to a typed interface for better type safety
+13. **Use getUser: false for performance** - Skip user fetch when you only need token validation
 
 ## Quick Reference
 
@@ -634,15 +829,28 @@ const type = authProvider.getProviderType(); // 'cognito' | 'clerk' | 'auth0'
 ### Decorator Usage
 
 ```typescript
-// Protect single method
+// Protect single method with authUser (default)
 @Authenticated(authProvider)
-async myMethod(input: { data: string }) { }
+async myMethod(input: { data: string }) {
+  console.log(authUser.sub); // User ID available
+}
+
+// Protect method without fetching user (faster)
+@Authenticated(authProvider, { getUser: false })
+async fastMethod(input: { data: string }) {
+  // Only token validation, no authUser
+}
 
 // Protect entire class
 @Authenticated(authProvider)
 class MyService {
-  @Tool() async method1() { }
-  @Tool() async method2() { }
+  @Tool() async method1() {
+    // authUser available in all methods
+    return { userId: authUser.sub };
+  }
+  @Tool() async method2() {
+    return { email: authUser.email };
+  }
 }
 
 // Check if authentication required
@@ -652,6 +860,39 @@ const required = isAuthenticationRequired(target, 'methodName');
 const provider = getAuthProvider(target, 'methodName');
 ```
 
+### authUser Quick Reference
+
+```typescript
+// Access user data in protected methods
+@Authenticated(authProvider)
+async createPost(input: { title: string }) {
+  // authUser is automatically available
+  const userId = authUser.sub;           // User ID (all providers)
+  const email = authUser.email;          // Email (all providers)
+  
+  // Provider-specific fields
+  const clerkId = authUser.userId;       // Clerk only
+  const firstName = authUser.firstName;  // Clerk only
+  const cognitoGroups = authUser['cognito:groups']; // Cognito only
+  const auth0Name = authUser.name;       // Auth0 only
+  
+  return { authorId: userId, authorEmail: email };
+}
+
+// Type authUser for better type safety
+interface MyUser {
+  sub: string;
+  email: string;
+  name?: string;
+}
+
+@Authenticated(authProvider)
+async typedMethod(input: any) {
+  const user = authUser as MyUser;
+  console.log(user.email); // Fully typed
+}
+```
+
 ## License
 
 MIT

package/dist/{auth0-A25F3NOH.mjs → auth0-54GZT2EI.mjs}

@@ -1,7 +1,7 @@
 import {
   AuthProviderBase,
   __name
-} from "./chunk-KKO5VLFX.mjs";
+} from "./chunk-EVD2TRPR.mjs";
 
 // src/providers/auth0.ts
 import axios from "axios";

package/dist/{chunk-KKO5VLFX.mjs → chunk-EVD2TRPR.mjs}

@@ -6,6 +6,21 @@ import "reflect-metadata";
 
 // src/decorators.ts
 import "reflect-metadata";
+import { AsyncLocalStorage } from "async_hooks";
+var authUserStorage = new AsyncLocalStorage();
+function getAuthUser() {
+  return authUserStorage.getStore();
+}
+__name(getAuthUser, "getAuthUser");
+if (typeof globalThis !== "undefined" && !Object.getOwnPropertyDescriptor(globalThis, "authUser")) {
+  Object.defineProperty(globalThis, "authUser", {
+    get() {
+      return authUserStorage.getStore();
+    },
+    configurable: true,
+    enumerable: false
+  });
+}
 var AuthenticationError = class extends Error {
   static {
     __name(this, "AuthenticationError");
@@ -16,11 +31,16 @@ var AuthenticationError = class extends Error {
     this.name = "AuthenticationError";
   }
 };
-function Authenticated(authProvider) {
+function Authenticated(authProvider, options) {
+  const authOptions = {
+    getUser: true,
+    ...options
+  };
   return function(target, propertyKey, descriptor) {
     if (!propertyKey && !descriptor) {
       Reflect.defineMetadata("auth:provider", authProvider, target);
       Reflect.defineMetadata("auth:required", true, target);
+      Reflect.defineMetadata("auth:options", authOptions, target);
       const prototype = target.prototype;
       const methodNames = Object.getOwnPropertyNames(prototype).filter((name) => name !== "constructor" && typeof prototype[name] === "function");
       for (const methodName of methodNames) {
@@ -29,7 +49,8 @@ function Authenticated(authProvider) {
           const originalMethod = originalDescriptor.value;
           Reflect.defineMetadata("auth:provider", authProvider, originalMethod);
           Reflect.defineMetadata("auth:required", true, originalMethod);
-          prototype[methodName] = createAuthenticatedMethod(originalMethod, authProvider);
+          Reflect.defineMetadata("auth:options", authOptions, originalMethod);
+          prototype[methodName] = createAuthenticatedMethod(originalMethod, authProvider, authOptions);
           copyMetadata(originalMethod, prototype[methodName]);
         }
       }
@@ -39,7 +60,8 @@ function Authenticated(authProvider) {
       const originalMethod = descriptor.value;
       Reflect.defineMetadata("auth:provider", authProvider, originalMethod);
       Reflect.defineMetadata("auth:required", true, originalMethod);
-      descriptor.value = createAuthenticatedMethod(originalMethod, authProvider);
+      Reflect.defineMetadata("auth:options", authOptions, originalMethod);
+      descriptor.value = createAuthenticatedMethod(originalMethod, authProvider, authOptions);
       copyMetadata(originalMethod, descriptor.value);
       return descriptor;
     }
@@ -47,7 +69,7 @@ function Authenticated(authProvider) {
   };
 }
 __name(Authenticated, "Authenticated");
-function createAuthenticatedMethod(originalMethod, authProvider) {
+function createAuthenticatedMethod(originalMethod, authProvider, options) {
   return async function(args, meta) {
     const token = meta?.authorization?.token;
     if (!token) {
@@ -64,9 +86,29 @@ function createAuthenticatedMethod(originalMethod, authProvider) {
       }
       throw new AuthenticationError(`Token verification failed: ${error instanceof Error ? error.message : String(error)}`, "VERIFICATION_FAILED");
     }
-    return originalMethod.apply(this, [
-      args
-    ]);
+    if (options.getUser !== false) {
+      try {
+        const user = await authProvider.getUser(token);
+        return await authUserStorage.run(user, async () => {
+          return await originalMethod.apply(this, [
+            args
+          ]);
+        });
+      } catch (error) {
+        console.warn("Failed to fetch user information:", error);
+        return await authUserStorage.run(void 0, async () => {
+          return await originalMethod.apply(this, [
+            args
+          ]);
+        });
+      }
+    } else {
+      return await authUserStorage.run(void 0, async () => {
+        return await originalMethod.apply(this, [
+          args
+        ]);
+      });
+    }
   };
 }
 __name(createAuthenticatedMethod, "createAuthenticatedMethod");
@@ -123,19 +165,19 @@ var AuthProvider = class extends AuthProviderBase {
     const finalConfig = config || this.config;
     switch (this.providerType) {
       case "cognito": {
-        const { AuthCognito } = await import("./cognito-2RRSLFKI.mjs");
+        const { AuthCognito } = await import("./cognito-I6V5YNYM.mjs");
         this.providerInstance = new AuthCognito();
         await this.providerInstance.init(finalConfig);
         break;
       }
       case "auth0": {
-        const { AuthAuth0 } = await import("./auth0-A25F3NOH.mjs");
+        const { AuthAuth0 } = await import("./auth0-54GZT2EI.mjs");
         this.providerInstance = new AuthAuth0();
         await this.providerInstance.init(finalConfig);
         break;
       }
       case "clerk": {
-        const { AuthClerk } = await import("./clerk-XNMGPYSN.mjs");
+        const { AuthClerk } = await import("./clerk-FR7ITM33.mjs");
         this.providerInstance = new AuthClerk();
         await this.providerInstance.init(finalConfig);
         break;
@@ -181,6 +223,7 @@ var AuthProvider = class extends AuthProviderBase {
 
 export {
   __name,
+  getAuthUser,
   AuthenticationError,
   Authenticated,
   isAuthenticationRequired,

package/dist/{clerk-XNMGPYSN.mjs → clerk-FR7ITM33.mjs}

@@ -1,7 +1,7 @@
 import {
   AuthProviderBase,
   __name
-} from "./chunk-KKO5VLFX.mjs";
+} from "./chunk-EVD2TRPR.mjs";
 
 // src/providers/clerk.ts
 import axios from "axios";

package/dist/{cognito-2RRSLFKI.mjs → cognito-I6V5YNYM.mjs}

@@ -1,7 +1,7 @@
 import {
   AuthProviderBase,
   __name
-} from "./chunk-KKO5VLFX.mjs";
+} from "./chunk-EVD2TRPR.mjs";
 
 // src/providers/cognito.ts
 import { CognitoIdentityProviderClient, InitiateAuthCommand } from "@aws-sdk/client-cognito-identity-provider";

package/dist/index.d.mts

@@ -1,3 +1,35 @@
+/**
+ * Shared types for @leanmcp/auth
+ */
+/**
+ * Options for the Authenticated decorator
+ */
+interface AuthenticatedOptions {
+    /**
+     * Whether to fetch and attach user information to authUser variable
+     * @default true
+     */
+    getUser?: boolean;
+}
+
+/**
+ * Global authUser type declaration
+ * This makes authUser available in @Authenticated methods without explicit declaration
+ */
+declare global {
+    /**
+     * Authenticated user object automatically available in @Authenticated methods
+     *
+     * Implemented as a getter that reads from AsyncLocalStorage for concurrency safety.
+     * Each request has its own isolated context - 100% safe for concurrent requests.
+     */
+    const authUser: any;
+}
+/**
+ * Get the current authenticated user from the async context
+ * This is safe for concurrent requests as each request has its own context
+ */
+declare function getAuthUser(): any;
 /**
  * Authentication error class for better error handling
  */
@@ -8,24 +40,40 @@ declare class AuthenticationError extends Error {
 /**
  * Decorator to protect MCP tools, prompts, resources, or entire services with authentication
  *
+ * CONCURRENCY SAFE: Uses AsyncLocalStorage to ensure each request has its own isolated
+ * authUser context, preventing race conditions in high-concurrency scenarios.
+ *
  * Usage:
  *
- * 1. Protect individual methods:
+ * 1. Protect individual methods with automatic user info:
  * ```typescript
  * @Tool({ description: 'Analyze sentiment' })
- * @Authenticated(authProvider)
+ * @Authenticated(authProvider, { getUser: true })
  * async analyzeSentiment(args: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
- *   // This method requires authentication
+ *   // authUser is automatically available in method scope
+ *   console.log('User:', authUser);
+ *   console.log('User ID:', authUser.sub);
+ * }
+ * ```
+ *
+ * 2. Protect without fetching user info:
+ * ```typescript
+ * @Tool({ description: 'Public tool' })
+ * @Authenticated(authProvider, { getUser: false })
+ * async publicTool(args: PublicToolInput): Promise<PublicToolOutput> {
+ *   // Only verifies token, doesn't fetch user info
  * }
  * ```
  *
- * 2. Protect entire service (all tools/prompts/resources):
+ * 3. Protect entire service (all tools/prompts/resources):
  * ```typescript
  * @Authenticated(authProvider)
  * export class SentimentAnalysisService {
  *   @Tool({ description: 'Analyze sentiment' })
  *   async analyzeSentiment(args: AnalyzeSentimentInput) {
  *     // All methods in this service require authentication
+ *     // authUser is automatically available in all methods
+ *     console.log('User:', authUser);
  *   }
  * }
  * ```
@@ -48,8 +96,9 @@ declare class AuthenticationError extends Error {
  * ```
  *
  * @param authProvider - Instance of AuthProviderBase to use for token verification
+ * @param options - Optional configuration for authentication behavior
  */
-declare function Authenticated(authProvider: AuthProviderBase): (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => any;
+declare function Authenticated(authProvider: AuthProviderBase, options?: AuthenticatedOptions): (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => any;
 /**
  * Check if a method or class requires authentication
  */
@@ -118,4 +167,4 @@ declare class AuthProvider extends AuthProviderBase {
     getProviderType(): string;
 }
 
-export { AuthProvider, AuthProviderBase, Authenticated, AuthenticationError, getAuthProvider, isAuthenticationRequired };
+export { AuthProvider, AuthProviderBase, Authenticated, type AuthenticatedOptions, AuthenticationError, getAuthProvider, getAuthUser, isAuthenticationRequired };

package/dist/index.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Shared types for @leanmcp/auth
+ */
+/**
+ * Options for the Authenticated decorator
+ */
+interface AuthenticatedOptions {
+    /**
+     * Whether to fetch and attach user information to authUser variable
+     * @default true
+     */
+    getUser?: boolean;
+}
+
+/**
+ * Global authUser type declaration
+ * This makes authUser available in @Authenticated methods without explicit declaration
+ */
+declare global {
+    /**
+     * Authenticated user object automatically available in @Authenticated methods
+     *
+     * Implemented as a getter that reads from AsyncLocalStorage for concurrency safety.
+     * Each request has its own isolated context - 100% safe for concurrent requests.
+     */
+    const authUser: any;
+}
+/**
+ * Get the current authenticated user from the async context
+ * This is safe for concurrent requests as each request has its own context
+ */
+declare function getAuthUser(): any;
 /**
  * Authentication error class for better error handling
  */
@@ -8,24 +40,40 @@ declare class AuthenticationError extends Error {
 /**
  * Decorator to protect MCP tools, prompts, resources, or entire services with authentication
  *
+ * CONCURRENCY SAFE: Uses AsyncLocalStorage to ensure each request has its own isolated
+ * authUser context, preventing race conditions in high-concurrency scenarios.
+ *
  * Usage:
  *
- * 1. Protect individual methods:
+ * 1. Protect individual methods with automatic user info:
  * ```typescript
  * @Tool({ description: 'Analyze sentiment' })
- * @Authenticated(authProvider)
+ * @Authenticated(authProvider, { getUser: true })
  * async analyzeSentiment(args: AnalyzeSentimentInput): Promise<AnalyzeSentimentOutput> {
- *   // This method requires authentication
+ *   // authUser is automatically available in method scope
+ *   console.log('User:', authUser);
+ *   console.log('User ID:', authUser.sub);
+ * }
+ * ```
+ *
+ * 2. Protect without fetching user info:
+ * ```typescript
+ * @Tool({ description: 'Public tool' })
+ * @Authenticated(authProvider, { getUser: false })
+ * async publicTool(args: PublicToolInput): Promise<PublicToolOutput> {
+ *   // Only verifies token, doesn't fetch user info
  * }
  * ```
  *
- * 2. Protect entire service (all tools/prompts/resources):
+ * 3. Protect entire service (all tools/prompts/resources):
  * ```typescript
  * @Authenticated(authProvider)
  * export class SentimentAnalysisService {
  *   @Tool({ description: 'Analyze sentiment' })
  *   async analyzeSentiment(args: AnalyzeSentimentInput) {
  *     // All methods in this service require authentication
+ *     // authUser is automatically available in all methods
+ *     console.log('User:', authUser);
  *   }
  * }
  * ```
@@ -48,8 +96,9 @@ declare class AuthenticationError extends Error {
  * ```
  *
  * @param authProvider - Instance of AuthProviderBase to use for token verification
+ * @param options - Optional configuration for authentication behavior
  */
-declare function Authenticated(authProvider: AuthProviderBase): (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => any;
+declare function Authenticated(authProvider: AuthProviderBase, options?: AuthenticatedOptions): (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => any;
 /**
  * Check if a method or class requires authentication
  */
@@ -118,4 +167,4 @@ declare class AuthProvider extends AuthProviderBase {
     getProviderType(): string;
 }
 
-export { AuthProvider, AuthProviderBase, Authenticated, AuthenticationError, getAuthProvider, isAuthenticationRequired };
+export { AuthProvider, AuthProviderBase, Authenticated, type AuthenticatedOptions, AuthenticationError, getAuthProvider, getAuthUser, isAuthenticationRequired };

package/dist/index.js

@@ -32,11 +32,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/decorators.ts
-function Authenticated(authProvider) {
+function getAuthUser() {
+  return authUserStorage.getStore();
+}
+function Authenticated(authProvider, options) {
+  const authOptions = {
+    getUser: true,
+    ...options
+  };
   return function(target, propertyKey, descriptor) {
     if (!propertyKey && !descriptor) {
       Reflect.defineMetadata("auth:provider", authProvider, target);
       Reflect.defineMetadata("auth:required", true, target);
+      Reflect.defineMetadata("auth:options", authOptions, target);
       const prototype = target.prototype;
       const methodNames = Object.getOwnPropertyNames(prototype).filter((name) => name !== "constructor" && typeof prototype[name] === "function");
       for (const methodName of methodNames) {
@@ -45,7 +53,8 @@ function Authenticated(authProvider) {
           const originalMethod = originalDescriptor.value;
           Reflect.defineMetadata("auth:provider", authProvider, originalMethod);
           Reflect.defineMetadata("auth:required", true, originalMethod);
-          prototype[methodName] = createAuthenticatedMethod(originalMethod, authProvider);
+          Reflect.defineMetadata("auth:options", authOptions, originalMethod);
+          prototype[methodName] = createAuthenticatedMethod(originalMethod, authProvider, authOptions);
           copyMetadata(originalMethod, prototype[methodName]);
         }
       }
@@ -55,14 +64,15 @@ function Authenticated(authProvider) {
       const originalMethod = descriptor.value;
       Reflect.defineMetadata("auth:provider", authProvider, originalMethod);
       Reflect.defineMetadata("auth:required", true, originalMethod);
-      descriptor.value = createAuthenticatedMethod(originalMethod, authProvider);
+      Reflect.defineMetadata("auth:options", authOptions, originalMethod);
+      descriptor.value = createAuthenticatedMethod(originalMethod, authProvider, authOptions);
       copyMetadata(originalMethod, descriptor.value);
       return descriptor;
     }
     throw new Error("@Authenticated can only be applied to classes or methods");
   };
 }
-function createAuthenticatedMethod(originalMethod, authProvider) {
+function createAuthenticatedMethod(originalMethod, authProvider, options) {
   return async function(args, meta) {
     const token = meta?.authorization?.token;
     if (!token) {
@@ -79,9 +89,29 @@ function createAuthenticatedMethod(originalMethod, authProvider) {
       }
       throw new AuthenticationError(`Token verification failed: ${error instanceof Error ? error.message : String(error)}`, "VERIFICATION_FAILED");
     }
-    return originalMethod.apply(this, [
-      args
-    ]);
+    if (options.getUser !== false) {
+      try {
+        const user = await authProvider.getUser(token);
+        return await authUserStorage.run(user, async () => {
+          return await originalMethod.apply(this, [
+            args
+          ]);
+        });
+      } catch (error) {
+        console.warn("Failed to fetch user information:", error);
+        return await authUserStorage.run(void 0, async () => {
+          return await originalMethod.apply(this, [
+            args
+          ]);
+        });
+      }
+    } else {
+      return await authUserStorage.run(void 0, async () => {
+        return await originalMethod.apply(this, [
+          args
+        ]);
+      });
+    }
   };
 }
 function copyMetadata(source, target) {
@@ -108,11 +138,23 @@ function isAuthenticationRequired(target) {
 function getAuthProvider(target) {
   return Reflect.getMetadata("auth:provider", target);
 }
-var import_reflect_metadata, AuthenticationError;
+var import_reflect_metadata, import_async_hooks, authUserStorage, AuthenticationError;
 var init_decorators = __esm({
   "src/decorators.ts"() {
     "use strict";
     import_reflect_metadata = require("reflect-metadata");
+    import_async_hooks = require("async_hooks");
+    authUserStorage = new import_async_hooks.AsyncLocalStorage();
+    __name(getAuthUser, "getAuthUser");
+    if (typeof globalThis !== "undefined" && !Object.getOwnPropertyDescriptor(globalThis, "authUser")) {
+      Object.defineProperty(globalThis, "authUser", {
+        get() {
+          return authUserStorage.getStore();
+        },
+        configurable: true,
+        enumerable: false
+      });
+    }
     AuthenticationError = class extends Error {
       static {
         __name(this, "AuthenticationError");
@@ -513,6 +555,7 @@ __export(index_exports, {
   Authenticated: () => Authenticated,
   AuthenticationError: () => AuthenticationError,
   getAuthProvider: () => getAuthProvider,
+  getAuthUser: () => getAuthUser,
   isAuthenticationRequired: () => isAuthenticationRequired
 });
 module.exports = __toCommonJS(index_exports);
@@ -610,5 +653,6 @@ init_index();
   Authenticated,
   AuthenticationError,
   getAuthProvider,
+  getAuthUser,
   isAuthenticationRequired
 });

package/dist/index.mjs

@@ -4,13 +4,15 @@ import {
   Authenticated,
   AuthenticationError,
   getAuthProvider,
+  getAuthUser,
   isAuthenticationRequired
-} from "./chunk-KKO5VLFX.mjs";
+} from "./chunk-EVD2TRPR.mjs";
 export {
   AuthProvider,
   AuthProviderBase,
   Authenticated,
   AuthenticationError,
   getAuthProvider,
+  getAuthUser,
   isAuthenticationRequired
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanmcp/auth",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Authentication and identity module supporting multiple providers",
   "main": "dist/index.js",
   "module": "dist/index.mjs",