@nest-omni/core 4.1.3-20 → 4.1.3-23

package/ip-filter/decorators/ip-filter.decorator.d.ts

@@ -0,0 +1,58 @@
+import { IpFilterMetadata } from '../interfaces';
+/**
+ * IP过滤装饰器
+ * 用于控制器或方法级别配置IP访问控制
+ *
+ * @example
+ * ```typescript
+ * // 控制器级别
+ * @IpFilter({
+ *   mode: 'whitelist',
+ *   ipRanges: ['192.168.1.0/24', '10.0.0.0/8'],
+ *   priority: 100
+ * })
+ * @Controller('admin')
+ * export class AdminController {}
+ *
+ * // 方法级别
+ * @Get()
+ * @IpFilter({
+ *   mode: 'blacklist',
+ *   ipRanges: ['203.0.113.0/24']
+ * })
+ * getData() {}
+ * ```
+ *
+ * @param options IP过滤配置选项
+ */
+export declare const IpFilter: (options: IpFilterMetadata) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * 白名单装饰器（快捷方式）
+ * 仅允许指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpWhitelist(['192.168.1.0/24', '10.0.0.0/8'], 'Office network')
+ * @Get('admin')
+ * adminDashboard() {}
+ * ```
+ *
+ * @param ipRanges 允许的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+export declare const IpWhitelist: (ipRanges: string[], description?: string) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * 黑名单装饰器（快捷方式）
+ * 禁止指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpBlacklist(['203.0.113.0/24'], 'Blocked malicious IPs')
+ * @Get('sensitive')
+ * sensitiveData() {}
+ * ```
+ *
+ * @param ipRanges 禁止的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+export declare const IpBlacklist: (ipRanges: string[], description?: string) => import("@nestjs/common").CustomDecorator<string>;

package/ip-filter/decorators/ip-filter.decorator.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IpBlacklist = exports.IpWhitelist = exports.IpFilter = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("../constants");
+/**
+ * IP过滤装饰器
+ * 用于控制器或方法级别配置IP访问控制
+ *
+ * @example
+ * ```typescript
+ * // 控制器级别
+ * @IpFilter({
+ *   mode: 'whitelist',
+ *   ipRanges: ['192.168.1.0/24', '10.0.0.0/8'],
+ *   priority: 100
+ * })
+ * @Controller('admin')
+ * export class AdminController {}
+ *
+ * // 方法级别
+ * @Get()
+ * @IpFilter({
+ *   mode: 'blacklist',
+ *   ipRanges: ['203.0.113.0/24']
+ * })
+ * getData() {}
+ * ```
+ *
+ * @param options IP过滤配置选项
+ */
+const IpFilter = (options) => (0, common_1.SetMetadata)(constants_1.IP_FILTER_KEY, options);
+exports.IpFilter = IpFilter;
+/**
+ * 白名单装饰器（快捷方式）
+ * 仅允许指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpWhitelist(['192.168.1.0/24', '10.0.0.0/8'], 'Office network')
+ * @Get('admin')
+ * adminDashboard() {}
+ * ```
+ *
+ * @param ipRanges 允许的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+const IpWhitelist = (ipRanges, description) => {
+    return (0, exports.IpFilter)({
+        mode: 'whitelist',
+        ipRanges,
+        priority: 100,
+        description,
+    });
+};
+exports.IpWhitelist = IpWhitelist;
+/**
+ * 黑名单装饰器（快捷方式）
+ * 禁止指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpBlacklist(['203.0.113.0/24'], 'Blocked malicious IPs')
+ * @Get('sensitive')
+ * sensitiveData() {}
+ * ```
+ *
+ * @param ipRanges 禁止的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+const IpBlacklist = (ipRanges, description) => {
+    return (0, exports.IpFilter)({
+        mode: 'blacklist',
+        ipRanges,
+        priority: 100,
+        description,
+    });
+};
+exports.IpBlacklist = IpBlacklist;

package/ip-filter/guards/index.d.ts

@@ -0,0 +1 @@
+export * from './ip-filter.guard';

package/ip-filter/guards/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ip-filter.guard"), exports);

package/ip-filter/guards/ip-filter.guard.d.ts

@@ -0,0 +1,62 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { IpFilterService } from '../services/ip-filter.service';
+/**
+ * IP过滤守卫
+ * 用于保护路由，只允许授权的IP访问
+ *
+ * @example
+ * ```typescript
+ * // 在控制器上使用
+ * @UseGuards(IpFilterGuard)
+ * @Controller('admin')
+ * export class AdminController {}
+ *
+ * // 在方法上使用
+ * @Get()
+ * @UseGuards(IpFilterGuard)
+ * getData() {}
+ *
+ * // 全局启用（在 app.module.ts）
+ * providers: [
+ *   {
+ *     provide: APP_GUARD,
+ *     useClass: IpFilterGuard,
+ *   },
+ * ]
+ * ```
+ */
+export declare class IpFilterGuard implements CanActivate {
+    private readonly reflector;
+    private readonly ipFilterService;
+    private readonly logger;
+    constructor(reflector: Reflector, ipFilterService: IpFilterService);
+    /**
+     * 判断是否允许访问
+     */
+    canActivate(context: ExecutionContext): boolean;
+    /**
+     * 从请求中提取客户端IP
+     * 使用 Express 的 req.ip（当启用了 trust proxy 时）
+     * 或回退到 socket.remoteAddress
+     */
+    private extractClientIp;
+    /**
+     * 判断是否应该记录IP（出于安全考虑，生产环境可能不记录完整IP）
+     */
+    private shouldLogIp;
+    /**
+     * 记录被拒绝的访问
+     */
+    private logBlockedAccess;
+    /**
+     * 记录允许的访问
+     */
+    private logAllowedAccess;
+    /**
+     * 掩码IP地址（用于日志记录，保护隐私）
+     * 192.168.1.100 -> 192.168.1.*
+     * 2001:db8::1 -> 2001:db8::*
+     */
+    private maskIp;
+}

package/ip-filter/guards/ip-filter.guard.js

@@ -0,0 +1,174 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var IpFilterGuard_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IpFilterGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const ip_filter_service_1 = require("../services/ip-filter.service");
+const constants_1 = require("../constants");
+const utils_1 = require("../utils");
+/**
+ * IP过滤守卫
+ * 用于保护路由，只允许授权的IP访问
+ *
+ * @example
+ * ```typescript
+ * // 在控制器上使用
+ * @UseGuards(IpFilterGuard)
+ * @Controller('admin')
+ * export class AdminController {}
+ *
+ * // 在方法上使用
+ * @Get()
+ * @UseGuards(IpFilterGuard)
+ * getData() {}
+ *
+ * // 全局启用（在 app.module.ts）
+ * providers: [
+ *   {
+ *     provide: APP_GUARD,
+ *     useClass: IpFilterGuard,
+ *   },
+ * ]
+ * ```
+ */
+let IpFilterGuard = IpFilterGuard_1 = class IpFilterGuard {
+    constructor(reflector, ipFilterService) {
+        this.reflector = reflector;
+        this.ipFilterService = ipFilterService;
+        this.logger = new common_1.Logger(IpFilterGuard_1.name);
+    }
+    /**
+     * 判断是否允许访问
+     */
+    canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        // 1. 获取客户端IP
+        const ip = this.extractClientIp(request);
+        request.clientIp = ip; // 保存到请求对象供后续使用
+        // 2. 获取路由级别的IP过滤元数据
+        const routeMetadata = this.reflector.getAllAndOverride(constants_1.IP_FILTER_KEY, [context.getHandler(), context.getClass()]);
+        // 3. 检查是否在路由级别禁用了IP过滤
+        if ((routeMetadata === null || routeMetadata === void 0 ? void 0 : routeMetadata.enabled) === false) {
+            return true;
+        }
+        // 4. 执行IP检查
+        const result = this.ipFilterService.checkIp(ip, routeMetadata);
+        // 5. 根据检查结果决定是否允许访问
+        if (!result.allowed) {
+            const errorResponse = this.ipFilterService.getErrorResponse();
+            this.logBlockedAccess(request, ip, result);
+            throw new common_1.ForbiddenException({
+                statusCode: errorResponse.statusCode,
+                message: errorResponse.message,
+                error: result.reason,
+                ip: this.shouldLogIp() ? ip : undefined,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        this.logAllowedAccess(request, ip, result);
+        return true;
+    }
+    /**
+     * 从请求中提取客户端IP
+     * 使用 Express 的 req.ip（当启用了 trust proxy 时）
+     * 或回退到 socket.remoteAddress
+     */
+    extractClientIp(request) {
+        var _a;
+        // 优先使用 Express 的 req.ip
+        // 当 app.set('trust proxy', true) 启用时，Express 会自动设置正确的 IP
+        if (request.ip) {
+            return utils_1.IpUtils.normalizeIp(request.ip);
+        }
+        // 回退到 socket.remoteAddress
+        if ((_a = request.socket) === null || _a === void 0 ? void 0 : _a.remoteAddress) {
+            return utils_1.IpUtils.normalizeIp(request.socket.remoteAddress);
+        }
+        // 最后回退到 headers（如果有的话）
+        const headers = request.headers;
+        const ipHeaders = [
+            'x-forwarded-for',
+            'x-real-ip',
+            'cf-connecting-ip',
+            'x-client-ip',
+        ];
+        for (const header of ipHeaders) {
+            const value = headers[header];
+            if (value) {
+                // X-Forwarded-For 可能包含多个IP，取第一个
+                const ip = Array.isArray(value) ? value[0] : value.split(',')[0];
+                return utils_1.IpUtils.normalizeIp(ip.trim());
+            }
+        }
+        return '0.0.0.0';
+    }
+    /**
+     * 判断是否应该记录IP（出于安全考虑，生产环境可能不记录完整IP）
+     */
+    shouldLogIp() {
+        return process.env.NODE_ENV === 'development' || process.env.LOG_IPS === 'true';
+    }
+    /**
+     * 记录被拒绝的访问
+     */
+    logBlockedAccess(request, ip, result) {
+        const logData = {
+            method: request.method,
+            url: request.url,
+            ip: this.shouldLogIp() ? ip : this.maskIp(ip),
+            reason: result.reason,
+            matchedRule: result.matchedRule,
+        };
+        this.logger.warn(`Access denied: ${JSON.stringify(logData)}`);
+    }
+    /**
+     * 记录允许的访问
+     */
+    logAllowedAccess(request, ip, result) {
+        if (process.env.LOG_ALLOWED_IPS === 'true') {
+            const logData = {
+                method: request.method,
+                url: request.url,
+                ip: this.shouldLogIp() ? ip : this.maskIp(ip),
+                matchedRule: result.matchedRule,
+            };
+            this.logger.log(`Access allowed: ${JSON.stringify(logData)}`);
+        }
+    }
+    /**
+     * 掩码IP地址（用于日志记录，保护隐私）
+     * 192.168.1.100 -> 192.168.1.*
+     * 2001:db8::1 -> 2001:db8::*
+     */
+    maskIp(ip) {
+        if (!ip)
+            return '*';
+        if (ip.includes(':')) {
+            // IPv6: 只显示前两段
+            const parts = ip.split(':');
+            return `${parts[0]}:${parts[1]}:*`;
+        }
+        // IPv4: 只显示前三段
+        const parts = ip.split('.');
+        if (parts.length === 4) {
+            return `${parts[0]}.${parts[1]}.${parts[2]}.*`;
+        }
+        return '*';
+    }
+};
+exports.IpFilterGuard = IpFilterGuard;
+exports.IpFilterGuard = IpFilterGuard = IpFilterGuard_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        ip_filter_service_1.IpFilterService])
+], IpFilterGuard);

package/ip-filter/index.d.ts

@@ -0,0 +1,7 @@
+export * from './interfaces';
+export * from './decorators';
+export * from './guards';
+export * from './services';
+export * from './utils';
+export * from './constants';
+export * from './ip-filter.module';

package/ip-filter/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./interfaces"), exports);
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./guards"), exports);
+__exportStar(require("./services"), exports);
+__exportStar(require("./utils"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./ip-filter.module"), exports);

package/ip-filter/interfaces/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ip-rule.interface';
+export * from './ip-filter-options.interface';
+export * from './ip-filter-metadata.interface';
+export * from './ip-filter-async-options.interface';

package/ip-filter/interfaces/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ip-rule.interface"), exports);
+__exportStar(require("./ip-filter-options.interface"), exports);
+__exportStar(require("./ip-filter-metadata.interface"), exports);
+__exportStar(require("./ip-filter-async-options.interface"), exports);

package/ip-filter/interfaces/ip-filter-async-options.interface.d.ts

@@ -0,0 +1,15 @@
+import { ModuleMetadata } from '@nestjs/common';
+import { IpFilterModuleOptions } from './ip-filter-options.interface';
+/**
+ * IP过滤模块异步配置选项
+ */
+export interface IpFilterModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    /**
+     * 异步工厂函数
+     */
+    useFactory: (...args: any[]) => Promise<IpFilterModuleOptions> | IpFilterModuleOptions;
+    /**
+     * 依赖注入的tokens
+     */
+    inject?: any[];
+}

package/ip-filter/interfaces/ip-filter-async-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/ip-filter/interfaces/ip-filter-metadata.interface.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 路由级别的IP过滤元数据
+ * 用于装饰器配置
+ */
+export interface IpFilterMetadata {
+    /**
+     * 是否启用IP过滤
+     */
+    enabled?: boolean;
+    /**
+     * 过滤模式
+     */
+    mode?: 'whitelist' | 'blacklist';
+    /**
+     * IP范围列表（CIDR格式）
+     */
+    ipRanges?: string[];
+    /**
+     * 优先级
+     */
+    priority?: number;
+    /**
+     * 描述
+     */
+    description?: string;
+}

package/ip-filter/interfaces/ip-filter-metadata.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/ip-filter/interfaces/ip-filter-options.interface.d.ts

@@ -0,0 +1,34 @@
+import { IpRule } from './ip-rule.interface';
+/**
+ * IP过滤模块配置选项
+ */
+export interface IpFilterModuleOptions {
+    /**
+     * 过滤模式
+     * - whitelist: 仅白名单模式（需要配置白名单规则）
+     * - blacklist: 仅黑名单模式（禁止黑名单中的IP，其他全部允许）
+     * - mixed: 混合模式（同时使用白名单和黑名单）
+     */
+    mode: 'whitelist' | 'blacklist' | 'mixed';
+    /**
+     * 默认策略
+     * - allow: 默认允许访问
+     * - deny: 默认拒绝访问
+     */
+    defaultPolicy: 'allow' | 'deny';
+    /**
+     * IP规则列表
+     */
+    rules: IpRule[];
+    /**
+     * 拒绝访问时的错误响应
+     */
+    errorResponse?: {
+        message?: string;
+        statusCode?: number;
+    };
+    /**
+     * 是否启用日志记录
+     */
+    enableLogging?: boolean;
+}

package/ip-filter/interfaces/ip-filter-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/ip-filter/interfaces/ip-rule.interface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * IP规则接口
+ */
+export interface IpRule {
+    /**
+     * 规则唯一标识
+     */
+    id: string;
+    /**
+     * 规则类型
+     * - whitelist: 白名单（只允许这些IP）
+     * - blacklist: 黑名单（禁止这些IP）
+     */
+    type: 'whitelist' | 'blacklist';
+    /**
+     * IP范围列表（支持CIDR格式）
+     * 示例:
+     * - '192.168.1.0/24' (CIDR)
+     * - '10.0.0.1' (单个IP)
+     * - '2001:db8::/32' (IPv6 CIDR)
+     */
+    ipRanges: string[];
+    /**
+     * 规则描述
+     */
+    description?: string;
+    /**
+     * 是否启用
+     */
+    enabled: boolean;
+    /**
+     * 优先级（数字越大越优先）
+     * 默认: 50
+     */
+    priority?: number;
+}

package/ip-filter/interfaces/ip-rule.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/ip-filter/ip-filter.module.d.ts

@@ -0,0 +1,55 @@
+import { DynamicModule } from '@nestjs/common';
+import { IpFilterModuleOptions, IpFilterModuleAsyncOptions } from './interfaces';
+/**
+ * IP过滤模块
+ * 提供IP访问控制功能
+ *
+ * @example
+ * ```typescript
+ * // 同步配置
+ * @Module({
+ *   imports: [
+ *     IpFilterModule.register({
+ *       mode: 'whitelist',
+ *       defaultPolicy: 'deny',
+ *       rules: [
+ *         {
+ *           id: 'office-network',
+ *           type: 'whitelist',
+ *           ipRanges: ['192.168.1.0/24', '10.0.0.0/8'],
+ *           enabled: true,
+ *           priority: 100,
+ *         },
+ *       ],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // 异步配置
+ * @Module({
+ *   imports: [
+ *     IpFilterModule.registerAsync({
+ *       imports: [ConfigModule],
+ *       inject: [ConfigService],
+ *       useFactory: (config: ConfigService) => ({
+ *         mode: 'whitelist',
+ *         defaultPolicy: 'deny',
+ *         rules: config.get('ipFilterRules'),
+ *       }),
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class IpFilterModule {
+    /**
+     * 同步注册模块
+     */
+    static register(options: IpFilterModuleOptions): DynamicModule;
+    /**
+     * 异步注册模块
+     */
+    static registerAsync(options: IpFilterModuleAsyncOptions): DynamicModule;
+}