@dangao/bun-server 1.8.0 → 1.8.2

package/docs/zh/request-lifecycle.md

@@ -20,6 +20,10 @@ HTTP Request
 └─────────────────────────────────────┘
     ↓
 ┌─────────────────────────────────────┐
+│             守卫                     │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
 │         拦截器（前置）               │
 └─────────────────────────────────────┘
     ↓
@@ -167,7 +171,39 @@ class UserController {
 }
 ```
 
-## 4. 拦截器（前置处理）
+## 4. 守卫
+
+守卫在路由匹配之后、拦截器之前执行，提供细粒度的访问控制。它们可以访问 `ExecutionContext`，提供关于当前请求的丰富信息。
+
+### 执行顺序
+
+1. **全局守卫** - 通过 `SecurityModule.forRoot({ globalGuards: [...] })` 注册
+2. **控制器守卫** - 通过 `@UseGuards()` 应用于控制器类
+3. **方法守卫** - 通过 `@UseGuards()` 应用于方法
+
+### 内置守卫
+
+- `AuthGuard`：要求认证
+- `OptionalAuthGuard`：可选认证
+- `RolesGuard`：基于角色的授权（与 `@Roles()` 装饰器一起使用）
+
+### 示例
+
+```typescript
+@Controller('/api/admin')
+@UseGuards(AuthGuard, RolesGuard)
+class AdminController {
+  @GET('/dashboard')
+  @Roles('admin')
+  public dashboard() {
+    return { message: '管理员仪表板' };
+  }
+}
+```
+
+详细文档请参阅 [守卫](./guards.md)。
+
+## 5. 拦截器（前置处理）
 
 拦截器在控制器方法之前和之后运行。前置拦截器按顺序执行：
 
@@ -200,7 +236,7 @@ class ApiController {}
 - 响应转换
 - 性能监控
 
-## 5. 参数绑定和验证
+## 6. 参数绑定和验证
 
 ### 参数装饰器
 
@@ -208,9 +244,11 @@ class ApiController {}
 |--------|------|------|
 | `@Param(name)` | URL 路径参数 | `/users/:id` → `@Param('id')` |
 | `@Query(name)` | 查询字符串 | `?page=1` → `@Query('page')` |
+| `@QueryMap()` | 所有查询参数 | `?page=1&limit=10` → `@QueryMap()` 返回 `{ page: '1', limit: '10' }` |
 | `@Body()` | 请求体 | JSON 请求体 |
 | `@Body(name)` | 请求体属性 | `body.name` → `@Body('name')` |
 | `@Header(name)` | 请求头 | `@Header('Authorization')` |
+| `@HeaderMap()` | 所有请求头 | `@HeaderMap()` 返回所有请求头作为对象 |
 | `@Context()` | 完整上下文 | 请求上下文对象 |
 | `@Session()` | 会话数据 | 会话对象 |
 
@@ -262,7 +300,7 @@ public createUser(
 }
 ```
 
-## 6. 控制器方法执行
+## 7. 控制器方法执行
 
 验证通过后，使用已解析的依赖和绑定的参数调用控制器方法。
 
@@ -294,7 +332,7 @@ class UserController {
 - **void** - 空响应（204）
 - **Promise** - 异步操作
 
-## 7. 拦截器（后置处理）
+## 8. 拦截器（后置处理）
 
 处理器执行后，后置拦截器按相反顺序运行：
 
@@ -318,7 +356,7 @@ class TransformInterceptor implements Interceptor {
 }
 ```
 
-## 8. 异常过滤器
+## 9. 异常过滤器
 
 如果在请求生命周期中抛出任何异常，它会被异常过滤器捕获。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/tests/auth/auth-decorators.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import 'reflect-metadata';
+
+import {
+  Auth,
+  getAuthMetadata,
+  requiresAuth,
+  checkRoles,
+  type AuthConfig,
+} from '../../src/auth/decorators';
+
+describe('Auth Decorator', () => {
+  describe('@Auth', () => {
+    test('should set auth metadata with default options', () => {
+      class TestController {
+        @Auth()
+        public protectedMethod(): void {}
+      }
+
+      const metadata = getAuthMetadata(TestController.prototype, 'protectedMethod');
+      expect(metadata).toBeDefined();
+      expect(metadata?.required).toBe(true);
+      expect(metadata?.roles).toEqual([]);
+      expect(metadata?.allowAnonymous).toBe(false);
+    });
+
+    test('should set auth metadata with required=false', () => {
+      class TestController {
+        @Auth({ required: false })
+        public optionalAuthMethod(): void {}
+      }
+
+      const metadata = getAuthMetadata(TestController.prototype, 'optionalAuthMethod');
+      expect(metadata?.required).toBe(false);
+    });
+
+    test('should set auth metadata with roles', () => {
+      class TestController {
+        @Auth({ roles: ['admin', 'moderator'] })
+        public adminMethod(): void {}
+      }
+
+      const metadata = getAuthMetadata(TestController.prototype, 'adminMethod');
+      expect(metadata?.roles).toEqual(['admin', 'moderator']);
+    });
+
+    test('should set auth metadata with allowAnonymous', () => {
+      class TestController {
+        @Auth({ allowAnonymous: true })
+        public publicMethod(): void {}
+      }
+
+      const metadata = getAuthMetadata(TestController.prototype, 'publicMethod');
+      expect(metadata?.allowAnonymous).toBe(true);
+    });
+
+    test('should set all options together', () => {
+      const config: AuthConfig = {
+        required: true,
+        roles: ['admin'],
+        allowAnonymous: false,
+      };
+
+      class TestController {
+        @Auth(config)
+        public fullConfigMethod(): void {}
+      }
+
+      const metadata = getAuthMetadata(TestController.prototype, 'fullConfigMethod');
+      expect(metadata?.required).toBe(true);
+      expect(metadata?.roles).toEqual(['admin']);
+      expect(metadata?.allowAnonymous).toBe(false);
+    });
+
+    test('should handle multiple methods with different configs', () => {
+      class TestController {
+        @Auth({ roles: ['admin'] })
+        public adminMethod(): void {}
+
+        @Auth({ roles: ['user'] })
+        public userMethod(): void {}
+
+        @Auth({ allowAnonymous: true })
+        public publicMethod(): void {}
+      }
+
+      const adminMetadata = getAuthMetadata(TestController.prototype, 'adminMethod');
+      const userMetadata = getAuthMetadata(TestController.prototype, 'userMethod');
+      const publicMetadata = getAuthMetadata(TestController.prototype, 'publicMethod');
+
+      expect(adminMetadata?.roles).toEqual(['admin']);
+      expect(userMetadata?.roles).toEqual(['user']);
+      expect(publicMetadata?.allowAnonymous).toBe(true);
+    });
+  });
+
+  describe('getAuthMetadata', () => {
+    test('should return undefined for non-decorated method', () => {
+      class TestController {
+        public normalMethod(): void {}
+      }
+
+      const metadata = getAuthMetadata(TestController.prototype, 'normalMethod');
+      expect(metadata).toBeUndefined();
+    });
+
+    test('should return metadata for decorated method', () => {
+      class TestController {
+        @Auth({ roles: ['admin'] })
+        public protectedMethod(): void {}
+      }
+
+      const metadata = getAuthMetadata(TestController.prototype, 'protectedMethod');
+      expect(metadata).toBeDefined();
+      expect(metadata?.roles).toEqual(['admin']);
+    });
+  });
+
+  describe('requiresAuth', () => {
+    test('should return false for non-decorated method', () => {
+      class TestController {
+        public normalMethod(): void {}
+      }
+
+      const requires = requiresAuth(TestController.prototype, 'normalMethod');
+      expect(requires).toBe(false);
+    });
+
+    test('should return true for decorated method with default config', () => {
+      class TestController {
+        @Auth()
+        public protectedMethod(): void {}
+      }
+
+      const requires = requiresAuth(TestController.prototype, 'protectedMethod');
+      expect(requires).toBe(true);
+    });
+
+    test('should return true when required is explicitly true', () => {
+      class TestController {
+        @Auth({ required: true })
+        public protectedMethod(): void {}
+      }
+
+      const requires = requiresAuth(TestController.prototype, 'protectedMethod');
+      expect(requires).toBe(true);
+    });
+
+    test('should return false when required is false', () => {
+      class TestController {
+        @Auth({ required: false })
+        public optionalMethod(): void {}
+      }
+
+      const requires = requiresAuth(TestController.prototype, 'optionalMethod');
+      expect(requires).toBe(false);
+    });
+  });
+
+  describe('checkRoles', () => {
+    test('should return true when no roles required', () => {
+      class TestController {
+        @Auth()
+        public anyAuthMethod(): void {}
+      }
+
+      const hasAccess = checkRoles(TestController.prototype, 'anyAuthMethod', ['user']);
+      expect(hasAccess).toBe(true);
+    });
+
+    test('should return true when roles is empty array', () => {
+      class TestController {
+        @Auth({ roles: [] })
+        public anyAuthMethod(): void {}
+      }
+
+      const hasAccess = checkRoles(TestController.prototype, 'anyAuthMethod', ['user']);
+      expect(hasAccess).toBe(true);
+    });
+
+    test('should return true when user has required role', () => {
+      class TestController {
+        @Auth({ roles: ['admin'] })
+        public adminMethod(): void {}
+      }
+
+      const hasAccess = checkRoles(TestController.prototype, 'adminMethod', ['admin']);
+      expect(hasAccess).toBe(true);
+    });
+
+    test('should return true when user has one of required roles', () => {
+      class TestController {
+        @Auth({ roles: ['admin', 'moderator'] })
+        public modMethod(): void {}
+      }
+
+      const hasAccess = checkRoles(TestController.prototype, 'modMethod', ['moderator']);
+      expect(hasAccess).toBe(true);
+    });
+
+    test('should return false when user lacks required role', () => {
+      class TestController {
+        @Auth({ roles: ['admin'] })
+        public adminMethod(): void {}
+      }
+
+      const hasAccess = checkRoles(TestController.prototype, 'adminMethod', ['user']);
+      expect(hasAccess).toBe(false);
+    });
+
+    test('should return false when user has no roles', () => {
+      class TestController {
+        @Auth({ roles: ['admin'] })
+        public adminMethod(): void {}
+      }
+
+      const hasAccess = checkRoles(TestController.prototype, 'adminMethod', []);
+      expect(hasAccess).toBe(false);
+    });
+
+    test('should return true for non-decorated method', () => {
+      class TestController {
+        public normalMethod(): void {}
+      }
+
+      const hasAccess = checkRoles(TestController.prototype, 'normalMethod', []);
+      expect(hasAccess).toBe(true);
+    });
+
+    test('should handle default empty userRoles parameter', () => {
+      class TestController {
+        @Auth({ roles: ['admin'] })
+        public adminMethod(): void {}
+      }
+
+      // checkRoles 默认参数为空数组
+      const hasAccess = checkRoles(TestController.prototype, 'adminMethod');
+      expect(hasAccess).toBe(false);
+    });
+  });
+});

package/tests/auth/oauth2-service.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import 'reflect-metadata';
+
+import { OAuth2Service } from '../../src/auth/oauth2';
+import { JWTUtil } from '../../src/auth/jwt';
+import type { OAuth2Client, UserInfo } from '../../src/auth/types';
+
+describe('OAuth2Service', () => {
+  let jwtUtil: JWTUtil;
+  let oauth2Service: OAuth2Service;
+  let testClient: OAuth2Client;
+
+  beforeEach(() => {
+    jwtUtil = new JWTUtil({
+      secret: 'test-secret-key-for-oauth2-testing',
+      accessTokenExpiresIn: 3600,
+      refreshTokenExpiresIn: 86400,
+    });
+
+    testClient = {
+      clientId: 'test-client',
+      clientSecret: 'test-secret',
+      redirectUris: ['http://localhost:3000/callback'],
+      grantTypes: ['authorization_code'],
+      scopes: ['read', 'write'],
+    };
+
+    oauth2Service = new OAuth2Service(jwtUtil, [testClient]);
+  });
+
+  describe('registerClient', () => {
+    test('should register a new client', () => {
+      const newClient: OAuth2Client = {
+        clientId: 'new-client',
+        clientSecret: 'new-secret',
+        redirectUris: ['http://example.com/callback'],
+        grantTypes: ['authorization_code'],
+      };
+
+      oauth2Service.registerClient(newClient);
+
+      // Verify by trying to validate a request with this client
+      const result = oauth2Service.validateAuthorizationRequest({
+        clientId: 'new-client',
+        responseType: 'code',
+        redirectUri: 'http://example.com/callback',
+      });
+
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe('validateAuthorizationRequest', () => {
+    test('should return valid for correct request', () => {
+      const result = oauth2Service.validateAuthorizationRequest({
+        clientId: 'test-client',
+        responseType: 'code',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result.valid).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    test('should return invalid for unknown client', () => {
+      const result = oauth2Service.validateAuthorizationRequest({
+        clientId: 'unknown-client',
+        responseType: 'code',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe('invalid_client');
+    });
+
+    test('should return invalid for unsupported response type', () => {
+      const result = oauth2Service.validateAuthorizationRequest({
+        clientId: 'test-client',
+        responseType: 'token' as any,
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe('unsupported_response_type');
+    });
+
+    test('should return invalid for wrong redirect uri', () => {
+      const result = oauth2Service.validateAuthorizationRequest({
+        clientId: 'test-client',
+        responseType: 'code',
+        redirectUri: 'http://evil.com/callback',
+      });
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe('invalid_redirect_uri');
+    });
+  });
+
+  describe('generateAuthorizationCode', () => {
+    test('should generate a code', () => {
+      const code = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+        'read write',
+      );
+
+      expect(code).toBeDefined();
+      expect(typeof code).toBe('string');
+      expect(code.length).toBe(32);
+    });
+
+    test('should generate unique codes', () => {
+      const code1 = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+      );
+      const code2 = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-456',
+      );
+
+      expect(code1).not.toBe(code2);
+    });
+  });
+
+  describe('exchangeCodeForToken', () => {
+    test('should exchange valid code for tokens', async () => {
+      const code = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+        'read',
+      );
+
+      const result = await oauth2Service.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code,
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result).not.toBeNull();
+      expect(result?.accessToken).toBeDefined();
+      expect(result?.refreshToken).toBeDefined();
+      expect(result?.tokenType).toBe('Bearer');
+      expect(result?.scope).toBe('read');
+    });
+
+    test('should return null for wrong grant type', async () => {
+      const result = await oauth2Service.exchangeCodeForToken({
+        grantType: 'client_credentials' as any,
+        code: 'some-code',
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result).toBeNull();
+    });
+
+    test('should return null for invalid code', async () => {
+      const result = await oauth2Service.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code: 'invalid-code',
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result).toBeNull();
+    });
+
+    test('should return null for wrong client secret', async () => {
+      const code = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+      );
+
+      const result = await oauth2Service.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code,
+        clientId: 'test-client',
+        clientSecret: 'wrong-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result).toBeNull();
+    });
+
+    test('should return null for wrong redirect uri', async () => {
+      const code = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+      );
+
+      const result = await oauth2Service.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code,
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://different.com/callback',
+      });
+
+      expect(result).toBeNull();
+    });
+
+    test('should not allow code reuse', async () => {
+      const code = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+      );
+
+      // First exchange should work
+      const result1 = await oauth2Service.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code,
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result1).not.toBeNull();
+
+      // Second exchange should fail
+      const result2 = await oauth2Service.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code,
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result2).toBeNull();
+    });
+  });
+
+  describe('refreshToken', () => {
+    test('should refresh token', async () => {
+      const code = oauth2Service.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+      );
+
+      const tokenResponse = await oauth2Service.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code,
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(tokenResponse?.refreshToken).toBeDefined();
+
+      const refreshResult = await oauth2Service.refreshToken(tokenResponse!.refreshToken!);
+
+      expect(refreshResult).not.toBeNull();
+      expect(refreshResult?.accessToken).toBeDefined();
+      expect(refreshResult?.refreshToken).toBeDefined();
+    });
+
+    test('should return null for invalid refresh token', async () => {
+      const result = await oauth2Service.refreshToken('invalid-token');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('with userProvider', () => {
+    test('should use userProvider for token generation', async () => {
+      const userProvider = async (userId: string): Promise<UserInfo | null> => {
+        if (userId === 'user-123') {
+          return {
+            id: userId,
+            username: 'alice',
+            roles: ['admin', 'user'],
+          };
+        }
+        return null;
+      };
+
+      const serviceWithProvider = new OAuth2Service(
+        jwtUtil,
+        [testClient],
+        {},
+        userProvider,
+      );
+
+      const code = serviceWithProvider.generateAuthorizationCode(
+        'test-client',
+        'http://localhost:3000/callback',
+        'user-123',
+      );
+
+      const result = await serviceWithProvider.exchangeCodeForToken({
+        grantType: 'authorization_code',
+        code,
+        clientId: 'test-client',
+        clientSecret: 'test-secret',
+        redirectUri: 'http://localhost:3000/callback',
+      });
+
+      expect(result).not.toBeNull();
+
+      // Verify the token contains the user info
+      const decoded = jwtUtil.verify(result!.accessToken);
+      expect(decoded?.username).toBe('alice');
+      expect(decoded?.roles).toContain('admin');
+    });
+  });
+});