@leanmcp/auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LeanMCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,321 @@
+# @leanmcp/auth
+
+Authentication module for LeanMCP providing token-based authentication decorators and multi-provider support.
+
+## Features
+
+- **@Authenticated decorator** - Protect MCP tools, prompts, and resources with token authentication
+- **Multi-provider support** - AWS Cognito (more providers coming soon)
+- **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
+
+## Installation
+
+```bash
+npm install @leanmcp/auth @leanmcp/core
+```
+
+### Provider Dependencies
+
+For AWS Cognito:
+```bash
+npm install @aws-sdk/client-cognito-identity-provider axios jsonwebtoken jwk-to-pem
+```
+
+## Quick Start
+
+### 1. Initialize Auth Provider
+
+```typescript
+import { AuthProvider } from "@leanmcp/auth";
+
+// Initialize with AWS Cognito
+const authProvider = new AuthProvider('cognito', {
+  region: 'us-east-1',
+  userPoolId: 'us-east-1_XXXXXXXXX',
+  clientId: 'your-client-id'
+});
+
+await authProvider.init();
+```
+
+### 2. Protect Individual Methods
+
+```typescript
+import { Tool } from "@leanmcp/core";
+import { Authenticated } from "@leanmcp/auth";
+
+export class SentimentService {
+  // This method requires authentication
+  @Tool({ description: 'Analyze sentiment (requires auth)' })
+  @Authenticated(authProvider)
+  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 };
+  }
+
+  // This method is public
+  @Tool({ description: 'Get sentiment categories (public)' })
+  async getCategories() {
+    return { categories: ['positive', 'negative', 'neutral'] };
+  }
+}
+```
+
+### 3. Protect Entire Service
+
+```typescript
+import { Authenticated } from "@leanmcp/auth";
+
+// All methods in this class require authentication
+@Authenticated(authProvider)
+export class SecureService {
+  @Tool({ description: 'Protected tool 1' })
+  async tool1(input: { data: string }) {
+    // All methods require authentication via _meta
+  }
+
+  @Tool({ description: 'Protected tool 2' })
+  async tool2(input: { data: string }) {
+    // All methods require authentication via _meta
+  }
+}
+```
+
+## Usage
+
+### Client Side - Calling Protected Methods
+
+Authentication tokens are passed via the `_meta` field following MCP protocol standards:
+
+```typescript
+// With token (succeeds)
+await mcpClient.callTool({
+  name: "analyzeSentiment",
+  arguments: {
+    text: "Hello world"
+  },
+  _meta: {
+    authorization: {
+      type: "bearer",
+      token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+    }
+  }
+});
+
+// Without token (fails with MISSING_TOKEN error)
+await mcpClient.callTool({
+  name: "analyzeSentiment",
+  arguments: {
+    text: "Hello world"
+  }
+});
+```
+
+### Raw MCP Request Format
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "analyzeSentiment",
+    "arguments": {
+      "text": "Hello world"
+    },
+    "_meta": {
+      "authorization": {
+        "type": "bearer",
+        "token": "your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+import { AuthenticationError } from "@leanmcp/auth";
+
+try {
+  await service.protectedMethod({ text: "test" });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    switch (error.code) {
+      case 'MISSING_TOKEN':
+        console.log('No token provided in request');
+        break;
+      case 'INVALID_TOKEN':
+        console.log('Token is invalid or expired');
+        break;
+      case 'VERIFICATION_FAILED':
+        console.log('Token verification failed:', error.message);
+        break;
+    }
+  }
+}
+```
+
+## Error Codes
+
+| Code | When | Message |
+|------|------|---------|
+| `MISSING_TOKEN` | No token in `_meta` | "Authentication required. Please provide a valid token in _meta.authorization.token" |
+| `INVALID_TOKEN` | Token invalid/expired | "Invalid or expired token. Please authenticate again." |
+| `VERIFICATION_FAILED` | Verification error | "Token verification failed: [details]" |
+
+## Supported Auth Providers
+
+### AWS Cognito
+
+```typescript
+const authProvider = new AuthProvider('cognito', {
+  region: 'us-east-1',
+  userPoolId: 'us-east-1_XXXXXXXXX',
+  clientId: 'your-client-id'
+});
+await authProvider.init();
+```
+
+**Token Requirements:**
+- JWT token from AWS Cognito User Pool
+- Token must be valid and not expired
+- Token must be issued by the configured User Pool
+
+### More Providers Coming Soon
+
+- Clerk
+- Auth0
+- Firebase Auth
+- Custom JWT providers
+
+## API Reference
+
+### AuthProvider
+
+```typescript
+class AuthProvider {
+  constructor(provider: string, config: any);
+  async init(config?: any): Promise<void>;
+  async verifyToken(token: string): Promise<boolean>;
+  async refreshToken(refreshToken: string, username?: string): Promise<any>;
+  async getUser(token: string): Promise<any>;
+  getProviderType(): string;
+}
+```
+
+### @Authenticated Decorator
+
+```typescript
+function Authenticated(authProvider: AuthProvider): ClassDecorator | MethodDecorator;
+```
+
+Can be applied to:
+- **Classes** - Protects all methods in the class
+- **Methods** - Protects individual methods
+
+### AuthenticationError
+
+```typescript
+class AuthenticationError extends Error {
+  code: 'MISSING_TOKEN' | 'INVALID_TOKEN' | 'VERIFICATION_FAILED';
+  constructor(message: string, code: string);
+}
+```
+
+### Helper Functions
+
+```typescript
+// Check if method/class requires authentication
+function isAuthenticationRequired(target: any, propertyKey?: string): boolean;
+
+// Get auth provider for method/class
+function getAuthProvider(target: any, propertyKey?: string): AuthProvider | undefined;
+```
+
+## Environment Variables
+
+For AWS Cognito:
+```bash
+AWS_REGION=us-east-1
+COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
+COGNITO_CLIENT_ID=your-client-id
+```
+
+## Complete Example
+
+See [examples/slack-with-auth](../../examples/slack-with-auth) for a complete working example with AWS Cognito.
+
+```typescript
+import { createHTTPServer, MCPServer } from "@leanmcp/core";
+import { AuthProvider, Authenticated } from "@leanmcp/auth";
+
+// Initialize auth
+const authProvider = new AuthProvider('cognito', {
+  region: process.env.AWS_REGION,
+  userPoolId: process.env.COGNITO_USER_POOL_ID,
+  clientId: process.env.COGNITO_CLIENT_ID
+});
+await authProvider.init();
+
+// Create service with protected methods
+@Authenticated(authProvider)
+class MyService {
+  @Tool()
+  async protectedTool(input: { data: string }) {
+    return { result: "Protected data" };
+  }
+}
+
+// Start server
+const serverFactory = () => {
+  const server = new MCPServer({ name: "auth-server", version: "1.0.0" });
+  server.registerService(new MyService());
+  return server.getServer();
+};
+
+await createHTTPServer(serverFactory, { port: 3000 });
+```
+
+## How It Works
+
+1. **Request arrives** with `_meta.authorization.token`
+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
+
+**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
+- **Reusable** - Same input classes work for authenticated and public methods
+
+## Best Practices
+
+1. **Always use HTTPS in production** - Tokens should never be sent over HTTP
+2. **Store tokens securely** - Use secure storage mechanisms (keychain, encrypted storage)
+3. **Implement token refresh** - Use refresh tokens to get new access tokens
+4. **Add rate limiting** - Protect against brute force attacks
+5. **Log authentication failures** - Monitor for suspicious activity
+6. **Use environment variables** - Never hardcode credentials
+7. **Use _meta for auth** - Don't include tokens in business arguments
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@leanmcp/core](../core) - Core MCP server functionality
+- [@leanmcp/cli](../cli) - CLI tool for creating new projects
+- [@leanmcp/utils](../utils) - Utility functions
+
+## Links
+
+- [GitHub Repository](https://github.com/LeanMCP/leanmcp-sdk)
+- [Documentation](https://github.com/LeanMCP/leanmcp-sdk#readme)

package/dist/chunk-NALGJYQB.mjs

@@ -0,0 +1,185 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import "reflect-metadata";
+
+// src/decorators.ts
+import "reflect-metadata";
+var AuthenticationError = class extends Error {
+  static {
+    __name(this, "AuthenticationError");
+  }
+  code;
+  constructor(message, code) {
+    super(message), this.code = code;
+    this.name = "AuthenticationError";
+  }
+};
+function Authenticated(authProvider) {
+  return function(target, propertyKey, descriptor) {
+    if (!propertyKey && !descriptor) {
+      Reflect.defineMetadata("auth:provider", authProvider, target);
+      Reflect.defineMetadata("auth:required", true, target);
+      const prototype = target.prototype;
+      const methodNames = Object.getOwnPropertyNames(prototype).filter((name) => name !== "constructor" && typeof prototype[name] === "function");
+      for (const methodName of methodNames) {
+        const originalDescriptor = Object.getOwnPropertyDescriptor(prototype, methodName);
+        if (originalDescriptor && typeof originalDescriptor.value === "function") {
+          const originalMethod = originalDescriptor.value;
+          Reflect.defineMetadata("auth:provider", authProvider, originalMethod);
+          Reflect.defineMetadata("auth:required", true, originalMethod);
+          prototype[methodName] = createAuthenticatedMethod(originalMethod, authProvider);
+          copyMetadata(originalMethod, prototype[methodName]);
+        }
+      }
+      return target;
+    }
+    if (descriptor && typeof descriptor.value === "function") {
+      const originalMethod = descriptor.value;
+      Reflect.defineMetadata("auth:provider", authProvider, originalMethod);
+      Reflect.defineMetadata("auth:required", true, originalMethod);
+      descriptor.value = createAuthenticatedMethod(originalMethod, authProvider);
+      copyMetadata(originalMethod, descriptor.value);
+      return descriptor;
+    }
+    throw new Error("@Authenticated can only be applied to classes or methods");
+  };
+}
+__name(Authenticated, "Authenticated");
+function createAuthenticatedMethod(originalMethod, authProvider) {
+  return async function(args, meta) {
+    const token = meta?.authorization?.token;
+    if (!token) {
+      throw new AuthenticationError("Authentication required. Please provide a valid token in _meta.authorization.token", "MISSING_TOKEN");
+    }
+    try {
+      const isValid = await authProvider.verifyToken(token);
+      if (!isValid) {
+        throw new AuthenticationError("Invalid or expired token. Please authenticate again.", "INVALID_TOKEN");
+      }
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        throw error;
+      }
+      throw new AuthenticationError(`Token verification failed: ${error instanceof Error ? error.message : String(error)}`, "VERIFICATION_FAILED");
+    }
+    return originalMethod.apply(this, [
+      args
+    ]);
+  };
+}
+__name(createAuthenticatedMethod, "createAuthenticatedMethod");
+function copyMetadata(source, target) {
+  const metadataKeys = Reflect.getMetadataKeys(source);
+  for (const key of metadataKeys) {
+    const value = Reflect.getMetadata(key, source);
+    Reflect.defineMetadata(key, value, target);
+  }
+  const designKeys = [
+    "design:type",
+    "design:paramtypes",
+    "design:returntype"
+  ];
+  for (const key of designKeys) {
+    const value = Reflect.getMetadata(key, source);
+    if (value !== void 0) {
+      Reflect.defineMetadata(key, value, target);
+    }
+  }
+}
+__name(copyMetadata, "copyMetadata");
+function isAuthenticationRequired(target) {
+  return Reflect.getMetadata("auth:required", target) === true;
+}
+__name(isAuthenticationRequired, "isAuthenticationRequired");
+function getAuthProvider(target) {
+  return Reflect.getMetadata("auth:provider", target);
+}
+__name(getAuthProvider, "getAuthProvider");
+
+// src/index.ts
+var AuthProviderBase = class {
+  static {
+    __name(this, "AuthProviderBase");
+  }
+};
+var AuthProvider = class extends AuthProviderBase {
+  static {
+    __name(this, "AuthProvider");
+  }
+  providerInstance = null;
+  providerType;
+  config;
+  constructor(provider, config) {
+    super();
+    this.providerType = provider.toLowerCase();
+    this.config = config;
+  }
+  /**
+  * Initialize the selected auth provider
+  */
+  async init(config) {
+    const finalConfig = config || this.config;
+    switch (this.providerType) {
+      case "cognito": {
+        const { AuthCognito } = await import("./cognito-VCVS77OX.mjs");
+        this.providerInstance = new AuthCognito();
+        await this.providerInstance.init(finalConfig);
+        break;
+      }
+      // Add more providers here in the future
+      // case 'clerk': {
+      //   const { AuthClerk } = await import('./providers/clerk');
+      //   this.providerInstance = new AuthClerk();
+      //   await this.providerInstance.init(finalConfig);
+      //   break;
+      // }
+      default:
+        throw new Error(`Unsupported auth provider: ${this.providerType}. Supported providers: cognito`);
+    }
+  }
+  /**
+  * Refresh an authentication token
+  */
+  async refreshToken(refreshToken, username) {
+    if (!this.providerInstance) {
+      throw new Error("AuthProvider not initialized. Call init() first.");
+    }
+    return this.providerInstance.refreshToken(refreshToken, username);
+  }
+  /**
+  * Verify if a token is valid
+  */
+  async verifyToken(token) {
+    if (!this.providerInstance) {
+      throw new Error("AuthProvider not initialized. Call init() first.");
+    }
+    return this.providerInstance.verifyToken(token);
+  }
+  /**
+  * Get user information from a token
+  */
+  async getUser(token) {
+    if (!this.providerInstance) {
+      throw new Error("AuthProvider not initialized. Call init() first.");
+    }
+    return this.providerInstance.getUser(token);
+  }
+  /**
+  * Get the provider type
+  */
+  getProviderType() {
+    return this.providerType;
+  }
+};
+
+export {
+  __name,
+  AuthenticationError,
+  Authenticated,
+  isAuthenticationRequired,
+  getAuthProvider,
+  AuthProviderBase,
+  AuthProvider
+};