weifuwu 0.56.0 → 0.57.0

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,70 @@
+/**
+ * weifuwu/rateLimit — 限流中间件
+ *
+ * 注入 ctx.limit（手动限流）+ 全局请求限流。
+ *
+ * store:
+ *   - redis（默认）：fixed（INCR + EXPIRE，原子无竞态）或 sliding（ZSET 时间戳），
+ *     计数在 redis 内 → 多实例天然一致
+ *   - memory：进程内 Map，仅单实例/开发环境（多实例会互相放行，文档红线）
+ *
+ * 裁剪声明：
+ *   ✅ fixed / sliding / redis / memory / 响应头 / ctx.limit / 自定义 key
+ *   ❌ 多级限流 DSL、配额策略引擎、动态规则热更新、按租户配额（应用层）
+ *
+ * ```ts
+ * import { rateLimit } from 'weifuwu'
+ *
+ * app.use(redis())
+ * app.use(rateLimit({ windowMs: 60_000, max: 100 }))       // 全局限流
+ *
+ * app.get('/api/search', async (req, ctx) => {
+ *   await ctx.limit('search', { max: 30, windowMs: 60_000 }) // 手动限流
+ *   ...
+ * })
+ * ```
+ */
+import type { Context, Middleware } from '../types.ts';
+export type RateLimitAlgorithm = 'fixed' | 'sliding';
+export type RateLimitStore = 'redis' | 'memory';
+export interface RateLimitOptions {
+    /** 时间窗口（ms）。默认 60_000。 */
+    windowMs?: number;
+    /** 窗口内最大请求数。默认 100。 */
+    max?: number;
+    /** 限流键（默认取 X-Forwarded-For 首个 IP；生产环境请配置反向代理注入该头）。 */
+    key?: (req: Request) => string;
+    /** 算法。'fixed'（默认）| 'sliding'（sliding 仅支持 redis store） */
+    algorithm?: RateLimitAlgorithm;
+    /** 存储。'redis'（默认）| 'memory'（单实例/开发） */
+    store?: RateLimitStore;
+    /** 超限状态码。默认 429。 */
+    statusCode?: number;
+    /** 超限错误消息。默认 'Too Many Requests'。 */
+    message?: string;
+    /** 是否输出 RateLimit-* / Retry-After 响应头。默认 true。 */
+    headers?: boolean;
+}
+/** ctx.limit 手动限流注入 */
+export interface RateLimitInjected {
+    /**
+     * 手动限流（handler 内对特定资源限流）。
+     * 超限抛 HttpError（默认 429）。
+     *
+     * ```ts
+     * await ctx.limit('search', { max: 30, windowMs: 60_000 })
+     * ```
+     */
+    limit: (name: string, opts?: {
+        max?: number;
+        windowMs?: number;
+    }) => Promise<void>;
+}
+declare module '../types.ts' {
+    interface Context {
+        limit?: RateLimitInjected['limit'];
+    }
+}
+export interface RateLimitClient extends Middleware<Context, Context & RateLimitInjected> {
+}
+export declare function rateLimit(options?: RateLimitOptions): RateLimitClient;

package/dist/queue/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * weifuwu/queue — 可靠任务队列（Redis Streams 消费组）
+ *
+ * 语义（文档红线）：
+ *   - at-least-once：handler 可能重复执行（崩溃/超时重投）——幂等由业务保证
+ *   - visibility timeout：处理失败不 XACK → 超时后被 XAUTOCLAIM 重新投递
+ *   - attempts 用尽 → DLQ（q:{name}:dead）
+ *   - 多 worker 实例安全：消费组内 entry 只被一个 consumer 处理
+ *
+ * 诚实裁剪：
+ *   ✅ add / worker（concurrency / visibilityTimeout）/ 重试（固定间隔 =
+ *      visibilityTimeout）/ DLQ / length
+ *   ❌ 延迟调度、cron、优先级、指数退避、速率限制（间隔固定为
+ *      visibilityTimeout）、流式进度（应用层实现）
+ *
+ * ```ts
+ * import { queue } from 'weifuwu'
+ *
+ * const q = queue()          // 默认 REDIS_URL
+ * app.use(q)                 // 注入 ctx.queue（handler 内 add）
+ *
+ * app.post('/api/jobs', async (req, ctx) => {
+ *   await ctx.queue.add('llm.batch', { prompt: '...' }, { attempts: 3 })
+ *   return accepted()
+ * })
+ *
+ * const worker = q.worker('llm.batch', async (job) => {
+ *   await runLLM(job.data)   // 失败 → 自动重试 → 用尽进 DLQ
+ * }, { concurrency: 5, visibilityTimeout: 30_000 })
+ * await worker.start()
+ * ```
+ */
+import type { Context, Middleware } from '../types.ts';
+export interface QueueOptions {
+    /** Redis 连接串（默认 REDIS_URL） */
+    url?: string;
+    /** stream 名前缀。默认 'q:'。 */
+    prefix?: string;
+    poolSize?: number;
+}
+export interface AddOptions {
+    /** 最大尝试次数（含首次）。默认 3。 */
+    attempts?: number;
+}
+export interface Job<T = unknown> {
+    /** stream entry id */
+    id: string;
+    data: T;
+    /** 已尝试次数 */
+    attempts: number;
+    name: string;
+}
+export interface WorkerOptions {
+    /** 每次 XREADGROUP 批量拉取数（≈并发度）。默认 1。 */
+    concurrency?: number;
+    /** 失败后重新投递间隔（ms）。默认 30_000。 */
+    visibilityTimeout?: number;
+    /** 消费组 consumer 名（多实例自动 hostname-pid，可覆盖） */
+    consumer?: string;
+}
+export interface QueueWorker {
+    /** 启动消费循环（阻塞直到 stop） */
+    start: () => Promise<void>;
+    /** 优雅停止：停止拉取，等待 in-flight 完成 */
+    stop: () => Promise<void>;
+}
+export interface QueueClient {
+    /** 入队（生产者） */
+    add: (name: string, data: unknown, opts?: AddOptions) => Promise<{
+        id: string;
+    }>;
+    /** 创建 worker（消费者）。worker 独立于请求生命周期，启动时创建。 */
+    worker: <T = unknown>(name: string, handler: (job: Job<T>) => Promise<void>, opts?: WorkerOptions) => QueueWorker;
+    /** 队列当前累积长度（XLEN）。注意：XACK 不删除 stream entry，
+     *  消费后 length 不归零；待处理/进行中数量用 XPENDING（ctx.redis.command）。 */
+    length: (name: string) => Promise<number>;
+}
+export interface QueueInjected {
+    queue: QueueClient;
+}
+declare module '../types.ts' {
+    interface Context {
+        queue?: QueueClient;
+    }
+}
+export interface QueueClientModule extends Middleware<Context, Context & QueueInjected> {
+    queue: QueueClient;
+    close: () => Promise<void>;
+}
+export declare function queue(options?: QueueOptions): QueueClientModule;

package/dist/types.d.ts

@@ -28,8 +28,8 @@ export interface Context {
     params: Record<string, string>;
     query: Record<string, string>;
     mountPath?: string;
-    /** Currently authenticated user (set by user() or custom auth middleware). */
-    user?: unknown;
+    /** Currently authenticated user (set by user() or userSystem()). */
+    user?: User | null;
     loaderData?: Record<string, unknown>;
     /** Public environment variables. */
     env?: Record<string, string>;

package/dist/user/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * weifuwu/userSystem — 用户系统中间件
+ *
+ * 注入 ctx.user（从 Authorization: Bearer 解码 + 查库）+ ctx.auth（方法面）。
+ * users.routes(app) 注册 /api/auth/* 路由；users.migrate() 幂等建表。
+ *
+ * 安全基线：
+ *   - scrypt 密码哈希（per-user salt + timing-safe compare，异步不阻塞）
+ *   - access token：HMAC-SHA256 JWT（无状态，与 client auth() 兼容）
+ *   - refresh token：不透明随机串，DB 只存哈希，logout/轮换即撤销
+ *   - 登录失败统一 401（不泄露"邮箱是否存在"——防枚举）
+ *
+ * 诚实裁剪：
+ *   ✅ register/login/logout/me/refresh / setPassword / createToken / tenant claim
+ *   ❌ OAuth、邮箱验证邮件（给 createToken + setPassword 底层 API 自接）、
+ *      多因素、RBAC 权限引擎（只提供 role 字段）、多租户语义（tenant-ready）
+ *
+ * ```ts
+ * const db = postgres()
+ * await db.migrate()
+ * const users = userSystem({ sql: db.sql, secret: process.env.AUTH_SECRET! })
+ * await users.migrate()
+ * app.use(db)
+ * app.use(users)
+ * users.routes(app)
+ *
+ * app.get('/me', (req, ctx) => ok(ctx.user))           // ctx.user 已注入
+ * app.post('/secure', (req, ctx) => {
+ *   ctx.auth.requireAuth()                              // 未登录抛 401
+ * })
+ * ```
+ */
+import type { Context, Middleware } from '../types.ts';
+import { type User } from '../types.ts';
+import type { Router } from '../core/router.ts';
+import type { SqlClient } from '../postgres/types.ts';
+export interface UserSystemOptions {
+    /** PostgreSQL SqlClient（postgres() 中间件的 .sql） */
+    sql: SqlClient;
+    /** HMAC 签名密钥（至少 32 字符；默认读 AUTH_SECRET） */
+    secret?: string;
+    /** access token 有效期（秒）。默认 3600（1h）。 */
+    accessTtlSeconds?: number;
+    /** refresh token 有效期（天）。默认 30。 */
+    refreshTtlDays?: number;
+    /** 路由前缀。默认 '/api/auth'。 */
+    prefix?: string;
+}
+export interface RegisterInput {
+    email: string;
+    password: string;
+    name?: string;
+    role?: string;
+    tenant?: string;
+}
+/** ctx.auth 方法面 */
+export interface AuthApi {
+    register(input: RegisterInput): Promise<{
+        token: string;
+        refreshToken: string;
+        user: User;
+    }>;
+    login(email: string, password: string): Promise<{
+        token: string;
+        refreshToken: string;
+        user: User;
+    }>;
+    /** 撤销 refresh token（logout） */
+    logout(refreshToken: string): Promise<void>;
+    /** 未登录抛 HttpError(401)，否则返回当前用户 */
+    requireAuth(): User;
+    /** 修改密码（登录态；旧密码失效） */
+    setPassword(userId: string, newPassword: string): Promise<void>;
+    /** 生成业务 token（邮箱验证/密码重置自接——应用层用它发邮件） */
+    createToken(type: string, payload: Record<string, unknown>, opts: {
+        ttlSeconds: number;
+    }): string;
+}
+export interface UserInjected {
+    /** 当前用户（未登录 = null）。每次请求从 token 解码 + 查库（删号/角色变更即时生效） */
+    user: User | null;
+    auth: AuthApi;
+}
+declare module '../types.ts' {
+    interface Context {
+        auth?: AuthApi;
+    }
+}
+export interface UserSystemClient extends Middleware<Context, Context & UserInjected> {
+    /** 幂等建表（users + sessions） */
+    migrate: () => Promise<void>;
+    /** 注册 /api/auth/* 路由（register/login/logout/me/refresh） */
+    routes: (app: Router, opts?: {
+        prefix?: string;
+    }) => void;
+}
+export declare function userSystem(options: UserSystemOptions): UserSystemClient;

package/dist/user/password.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 密码哈希（node:crypto scrypt，异步版不阻塞事件循环）
+ *
+ * 格式：`scrypt$N$r$p$salt$hash`（参数进哈希串 → 未来可升级参数，旧哈希可验证）
+ * per-user 随机 salt + timingSafeEqual 比较（防 timing 攻击）
+ */
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, stored: string): Promise<boolean>;

package/dist/user/token.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 会话令牌（零依赖，node:crypto）
+ *
+ * access token：HMAC-SHA256 签名的 JWT 形态（base64url），
+ *   与 weifuwu/client 的 auth() 兼容（客户端解码 payload 检查 exp）。
+ * refresh token：不透明随机串（256-bit），DB 只存 SHA-256 哈希（可撤销）。
+ */
+/** 签发 JWT access token（HS256） */
+export declare function signToken(payload: Record<string, unknown>, secret: string, ttlSeconds: number): string;
+/** 验证 JWT（签名 + 过期）。失败返回 null（不是抛错——未登录是正常状态） */
+export declare function verifyToken(token: string, secret: string): Record<string, unknown> | null;
+/** 不透明 refresh token（256-bit 随机） */
+export declare function generateRefreshToken(): string;
+/** DB 只存哈希（泄露库也不泄露 refresh token） */
+export declare function hashRefreshToken(token: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {