secure-upload-fastify-sdk 1.0.0

package/dist/server/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * SDK 公共类型
+ *
+ * 包含:
+ *   - SecureUploadOptions (插件入参)
+ *   - SecureUploadRuntime (运行时上下文,挂到 fastify)
+ *   - 业务响应类型
+ */
+import type { Redis } from 'ioredis';
+import type { StorageAdapter } from './utils/storage/types';
+import type { MultipartRepository, FileRepository, MultipartRecord, FileRecord } from './utils/repository/types';
+import type { StrategyConfig } from './utils/strategy';
+/**
+ * 安全模式
+ *  - 'raw':           SDK 不读加密字段,直接读 req.body / req.headers(网关已解密的明文)
+ *  - 'secure-crypto': SDK 读 req.secureRequest.biz + x-secure-raw-base64(从加密 SDK 拿数据)
+ */
+export type SecureMode = 'raw' | 'secure-crypto';
+/**
+ * 数据层配置
+ *  - kind: 'prisma'  → SDK 内部用 PrismaMultipartRepository + PrismaFileRepository
+ *  - kind: 'custom'  → 用户注入自己的实现(Drizzle / TypeORM / 内存 / Mongo)
+ */
+type AnyPrisma = any;
+export type RepositoryConfig = {
+    kind: 'prisma';
+    prisma: AnyPrisma;
+} | {
+    kind: 'custom';
+    multipart: MultipartRepository;
+    file: FileRepository;
+};
+/**
+ * 存储配置
+ *  - 字符串 preset → SDK 内部 new LocalStorage
+ *  - 直接传 StorageAdapter 实例 → S3 / OSS / COS / 自定义
+ */
+export type StorageConfig = {
+    adapter: 'local';
+    options: {
+        baseDir: string;
+    };
+} | StorageAdapter;
+/**
+ * Session 验证函数
+ *  - 入参: session token (JWT 字符串,可能为 undefined)
+ *  - 返回: userId(非公开文件必须返回有效 userId) / null(公开文件)
+ *  - 抛错: 鉴权失败(BINARY_AUTH_REQUIRED / BINARY_AUTH_FAILED)
+ *
+ * SDK 默认实现: base64 解码 JWT payload,读 sub / exp 字段
+ * 高级场景: 用户注入自己的 jwt.verify() 验签
+ */
+export type SessionValidator = (token: string | undefined, isPublic: boolean) => Promise<number | null> | number | null;
+/**
+ * 路径前缀
+ *  - 默认 '/multipart' 和 '/smart'
+ *  - 业务挂到 '/api/v1/upload' 时,传 pathPrefix: '/api/v1/upload'
+ *    实际端点 = pathPrefix + '/multipart/init' = '/api/v1/upload/multipart/init'
+ */
+export interface PathPrefixConfig {
+    multipart?: string;
+    smart?: string;
+}
+export interface SecureUploadOptions {
+    /** 存储适配器 */
+    storage: StorageConfig;
+    /** 数据层(Prisma 注入 / 自实现) */
+    repository: RepositoryConfig;
+    /**
+     * 安全模式(默认 'raw')
+     *  - 'raw':           业务直传,SDK 读 req.body / req.headers
+     *  - 'secure-crypto': 与 secure-crypto-top-zod-sdk 桥接,读 req.secureRequest.biz
+     */
+    secure?: {
+        mode: SecureMode;
+    };
+    /** Redis 客户端(ioredis)。不传则 SDK 用内存版限流 + 锁(单进程) */
+    redis?: Redis;
+    /** Smart 策略(默认 DEFAULT_STRATEGY_CONFIG) */
+    strategy?: Partial<StrategyConfig>;
+    /** 限流配置 */
+    rateLimit?: {
+        /** 每用户每分钟 init 次数(默认 30) */
+        initPerMin?: number;
+        /** 每用户每分钟 part 次数(默认 600) */
+        partPerMin?: number;
+        /** /smart/init 单次最多文件数(默认 50) */
+        smartMaxFilesPerInit?: number;
+    };
+    /** 分片上传总开关(默认 true) */
+    enabled?: boolean;
+    /** 单文件总大小上限,字节(默认 5GB) */
+    fileMaxSize?: number;
+    /** 分片大小配置(字节) */
+    partSize?: {
+        min?: number;
+        max?: number;
+        default?: number;
+    };
+    /** TTL(秒),init 后多久必须完成(默认 24h) */
+    ttlSeconds?: number;
+    /** 客户端并发建议值(默认 3) */
+    suggestedClientConcurrency?: number;
+    /** 路径前缀(默认 '/multipart' '/smart') */
+    pathPrefix?: PathPrefixConfig;
+    /**
+     * 文件下载 URL 前缀(用于 complete 响应中的 url 字段)
+     *  - 默认 '/files'
+     *  - 业务挂到 '/api/v1/upload' 时,应传 '/api/v1/upload/files'
+     *    → complete 返回 url = '/api/v1/upload/files/<fileId>'
+     */
+    fileUrlPrefix?: string;
+    /** 自定义 session 验证(默认 base64 解 JWT payload) */
+    sessionValidator?: SessionValidator;
+    /** 清理过期 uploadId 任务(默认 true) */
+    cleanupTask?: {
+        enabled?: boolean;
+        intervalSeconds?: number;
+        batchLimit?: number;
+    };
+    /** 孤儿文件扫描任务(默认 true) */
+    orphanScan?: {
+        enabled?: boolean;
+        intervalSeconds?: number;
+        lookbackDays?: number;
+        batchSize?: number;
+    };
+}
+/**
+ * 运行时上下文(挂到 fastify.secureUpload)
+ *  - 路由处理函数从这里拿 storage / repo / validator
+ */
+export interface SecureUploadRuntime {
+    storage: StorageAdapter;
+    multipartRepo: MultipartRepository;
+    fileRepo: FileRepository;
+    redis: Redis | null;
+    config: {
+        enabled: boolean;
+        secure: SecureMode;
+        fileMaxSize: number;
+        partMin: number;
+        partMax: number;
+        partDefault: number;
+        ttlSeconds: number;
+        suggestedConcurrency: number;
+        initRateLimit: number;
+        partRateLimit: number;
+        smartMaxFiles: number;
+        smartInitRateLimit: number;
+        multipartPath: string;
+        smartPath: string;
+        fileUrlPrefix: string;
+        strategy: StrategyConfig;
+    };
+    /** session → userId,默认 base64 JWT,用户可注入 */
+    validateSession: SessionValidator;
+}
+declare module 'fastify' {
+    interface FastifyInstance {
+        secureUpload: SecureUploadRuntime;
+    }
+}
+export interface InitResponse {
+    success: true;
+    data: {
+        uploadId: string;
+        partSize: number;
+        totalParts: number;
+        totalSize: number;
+        expiresAt: string;
+        ttl: number;
+        suggestedConcurrency: number;
+        dedup?: {
+            fileId: string;
+            filename: string;
+            size: number;
+            contentType: string;
+            url: string;
+        };
+    };
+}
+export interface PartResponse {
+    success: true;
+    data: {
+        uploadId: string;
+        partNumber: number;
+        size: number;
+        receivedCount: number;
+        totalParts: number;
+    };
+}
+export interface CompleteResponse {
+    success: true;
+    data: {
+        fileId: string;
+        filename: string;
+        size: number;
+        contentType: string;
+        url: string;
+        finalHash: string;
+        idempotent: boolean;
+    };
+}
+export interface AbortResponse {
+    success: true;
+    data: {
+        uploadId: string;
+        status: 'ABORTED';
+        idempotent?: boolean;
+    };
+}
+export interface StatusResponse {
+    success: true;
+    data: {
+        uploadId: string;
+        status: string;
+        filename: string;
+        contentType: string;
+        totalSize: number;
+        partSize: number;
+        totalParts: number;
+        receivedParts: number[];
+        receivedCount: number;
+        isPublic: boolean;
+        expiresAt: string;
+        createdAt: string;
+        completedAt: string | null;
+        fileId: string | null;
+    };
+}
+export type { MultipartRecord, FileRecord };
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/server/utils/cleaner.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 后台清理过期 uploadId 任务
+ *
+ *  - 每 intervalSeconds 扫描一次
+ *  - 把超时的 INIT/UPLOADING 标记为 EXPIRED + 清理磁盘
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import type { StorageAdapter } from './storage/types';
+import type { MultipartRepository } from './repository/types';
+export interface MultipartCleanerOptions {
+    enabled: boolean;
+    intervalSeconds: number;
+    batchLimit: number;
+    storage: StorageAdapter;
+    multipartRepo: MultipartRepository;
+    log: FastifyBaseLogger;
+    onClose: (cb: () => void) => void;
+}
+export declare function startMultipartCleanupTask(opts: MultipartCleanerOptions): void;
+//# sourceMappingURL=cleaner.d.ts.map

package/dist/server/utils/cleaner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleaner.d.ts","sourceRoot":"","sources":["../../../src/server/utils/cleaner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,EAAE,mBAAmB,CAAC;IACnC,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CA+B7E"}

package/dist/server/utils/memory-rate-limit.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 内存版限流 + 锁(单进程降级)
+ *
+ * 当 SDK 未注入 redis 时,使用本实现:
+ *   - 限流: 进程内 Map<key, timestamps[]>(滑动窗口)
+ *   - 锁:   进程内 Map<key, boolean>(互斥)
+ *
+ * 注意: 内存版只在单进程内有效,多实例部署请传 redis。
+ */
+export declare function memorySlidingWindowRateLimit(key: string, windowMs: number, limit: number): {
+    ok: boolean;
+    retryAfterMs: number;
+    remaining: number;
+};
+export declare function memoryAcquireLock(key: string): boolean;
+export declare function memoryReleaseLock(key: string): void;
+export declare function memoryWithLock<T>(key: string, fn: () => Promise<T>, retries?: number): Promise<T>;
+/** 内部:统一抽象(让路由层不感知 redis / 内存) */
+export interface LockLike {
+    withLock<T>(key: string, ttlMs: number, fn: () => Promise<T>, retries?: number): Promise<T>;
+}
+export interface RateLimitLike {
+    rateLimit(key: string, windowMs: number, limit: number): Promise<{
+        ok: boolean;
+        retryAfterMs: number;
+        remaining: number;
+    }>;
+}
+//# sourceMappingURL=memory-rate-limit.d.ts.map

package/dist/server/utils/memory-rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-rate-limit.d.ts","sourceRoot":"","sources":["../../../src/server/utils/memory-rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAiB1D;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAItD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED,wBAAsB,cAAc,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,SAAI,GACV,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7F;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5H"}

package/dist/server/utils/orphan-scanner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 孤儿文件扫描任务
+ *
+ * 背景:
+ *   秒传路径只查 DB,可能存在"DB 有 / 磁盘无"的不一致:
+ *     - 用户/运维手动 rm 磁盘文件
+ *     - 容器重启后丢失 volume mount
+ *     - 分布式存储同步失败
+ *
+ *   已有被动防御:秒传命中 DB 后 storage.exists() 二次校验
+ *   本任务作为"主动巡检"兜底:定期扫一遍,自动 soft-delete,
+ *   防止其他业务路径(如 /files/:id GET)又返回 404 "文件已丢失"。
+ *
+ * 触发:服务冷启动(setImmediate) + setInterval
+ * 容错:
+ *   - 单条 storage.exists() 抛错 → 跳过该条,记 warn
+ *   - 单条 fileRepo.softDelete 失败 → 跳过该条,记 warn
+ *   - 整个 tick 失败 → 记 error,不影响下次
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import type { StorageAdapter } from './storage/types';
+import type { FileRepository } from './repository/types';
+export interface OrphanScannerOptions {
+    enabled: boolean;
+    intervalSeconds: number;
+    lookbackDays: number;
+    batchSize: number;
+    storage: StorageAdapter;
+    fileRepo: FileRepository;
+    log: FastifyBaseLogger;
+    onClose: (cb: () => void) => void;
+}
+export declare function startOrphanFileScanTask(opts: OrphanScannerOptions): void;
+//# sourceMappingURL=orphan-scanner.d.ts.map

package/dist/server/utils/orphan-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-scanner.d.ts","sourceRoot":"","sources":["../../../src/server/utils/orphan-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAgExE"}

package/dist/server/utils/redis-helpers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Redis 辅助工具(可选注入,分布式场景使用)
+ *
+ * 提供:
+ *   - slidingWindowRateLimit: 滑动窗口限流(Lua + ZSET,精确无突刺)
+ *   - acquireLock / releaseLock / withLock: 分布式锁
+ *
+ * ioredis 客户端作为 SDK peerDependency(可选),不传时 SDK 用内存降级
+ */
+import type Redis from 'ioredis';
+export declare function slidingWindowRateLimit(redis: Redis, key: string, windowMs: number, limit: number): Promise<{
+    ok: boolean;
+    retryAfterMs: number;
+    remaining: number;
+}>;
+export declare function acquireLock(redis: Redis, key: string, ttlMs?: number): Promise<{
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    token: null;
+}>;
+export declare function releaseLock(redis: Redis, key: string, token: string): Promise<boolean>;
+export declare function withLock<T>(redis: Redis, key: string, ttlMs: number, fn: () => Promise<T>, retries?: number): Promise<T>;
+//# sourceMappingURL=redis-helpers.d.ts.map

package/dist/server/utils/redis-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-helpers.d.ts","sourceRoot":"","sources":["../../../src/server/utils/redis-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AA6CjC,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBnE;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,KAAK,SAAQ,GACZ,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,CAAC,CAKnE;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG5F;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,SAAI,GACV,OAAO,CAAC,CAAC,CAAC,CAsBZ"}

package/dist/server/utils/repository/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Repository 统一导出
+ *
+ * 用法 1:用 Prisma(SDK 内置实现)
+ *   import { PrismaMultipartRepository, PrismaFileRepository } from '.../repository';
+ *   const multipart = new PrismaMultipartRepository(prisma);
+ *   const file = new PrismaFileRepository(prisma);
+ *   await app.register(secureUploadPlugin, {
+ *     repository: { kind: 'custom', multipart, file },
+ *     ...
+ *   });
+ *
+ * 用法 2:用内存实现(测试)
+ *   import { InMemoryMultipartRepository, InMemoryFileRepository } from '.../repository';
+ *
+ * 用法 3:完全自实现(Drizzle / TypeORM / Mongo / ...)
+ *   class MyMultipartRepo implements MultipartRepository { ... }
+ *   await app.register(secureUploadPlugin, {
+ *     repository: { kind: 'custom', multipart: new MyMultipartRepo(), file: new MyFileRepo() },
+ *     ...
+ *   });
+ */
+export { PrismaMultipartRepository, PrismaFileRepository, } from './prisma';
+export { InMemoryMultipartRepository, InMemoryFileRepository, } from './memory';
+export { MultipartStatus, FileStatus, type MultipartRecord, type FileRecord, type CreateInitInput, type CreateFileInput, type AddPartOutcome, type MultipartRepository, type FileRepository, } from './types';
+export type { MultipartStatusT, FileStatusT } from './types-extra';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/utils/repository/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/repository/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}