@weifuwujs/auth 0.9.0

package/README.md

@@ -0,0 +1,172 @@
+# 用户系统（`@weifuwujs/auth`）
+
+零配置、安全默认的用户系统：scrypt、服务端不透明 session、cookie 属性、登录轮换、防枚举、
+限流、Origin 校验、单次短 TTL 重置 token。不进主入口，不 import 不背依赖。
+
+## 五分钟闭环
+
+```bash
+npx @weifuwujs/weifuwu init my-app
+cd my-app
+cp -r "$(npm root)/@weifuwujs/auth/templates/react-router-auth/." .
+npx @weifuwujs/auth migrate   # 生成 data/auth.db
+npm run dev                   # http://localhost:3000/login
+```
+
+页面为 React Router 无 JS 表单（渐进增强）：注册 / 登录 / 忘记密码 / 账户（改密、登出）。
+叠加层（`templates/react-router-auth`）内容：
+
+| 文件 | 作用 |
+| --- | --- |
+| `app/auth.ts` | `createAuth()` 单例（默认 `sqliteAuthStore('data/auth.db')`） |
+| `app/server.ts` | `use(auth.middleware).mount(auth)` + `use('/account', auth.require())` + 注入 `authUser` |
+| `app/routes/{login,register,reset-password,account}.tsx` | 无 JS 表单页（PRG：失败 303 回页带 `?error=`） |
+
+## 端点
+
+挂载：`app.mount(auth)`（JSON）；同一端点同时接受 `application/x-www-form-urlencoded`
+（表单 → 303 + `Location`，页面回显错误）。
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| POST | `/auth/register` | 注册（201；表单 303） |
+| POST | `/auth/login` | 登录，轮换旧会话（防 session fixation） |
+| POST | `/auth/logout` | 登出并清 cookie |
+| GET | `/auth/me` | 当前用户（`ctx.auth.user` 每请求现查） |
+| PATCH | `/auth/me` | 改邮箱（需当前密码） |
+| POST | `/auth/password/change` | 改密（保留当前会话，踢其他） |
+| POST | `/auth/password/forgot` | 恒 200（防枚举）；未配置 hook 时 dev 打印链接、生产静默 |
+| POST | `/auth/password/reset` | 单次 token；过期/复用一律无效 |
+
+## 配置
+
+```ts
+// app/auth.ts
+import { createAuth } from '@weifuwujs/auth'
+import { sqliteAuthStore } from '@weifuwujs/auth/sqlite'
+
+export const auth = createAuth({
+  store: sqliteAuthStore('data/auth.db'),
+  session: { cookieName: 'ww_session', maxAge: 30 * 24 * 3600 }, // secure 默认随生产环境开启
+  rateLimit: { max: 10, windowMs: 60_000 },   // 默认每 IP 每分钟 10 次
+  origin: false,                               // 默认同源校验；反代跨域时显式列白名单
+})
+
+// app/server.ts
+const app = createApp().use(auth.middleware).mount(auth)
+app.get('/orders', auth.require(), listOrders)
+app.get('/billing', auth.require((user) => user.role === 'admin'), billing)
+```
+
+- `ctx.auth = { user, login(user), logout(), verifyPassword(plain) }`；
+- `auth.require()`：HTTP 未登录 → 页面 302 `/login?next=…`、API 401；角色/谓词不过 → 403；
+  WS 升级未登录 → 401 拒绝；
+- 只有一个中间件实例：HTTP 用 `app.use(auth.middleware)`，WS 同时用 `auth.install(app)`（`use` + `wsUse`）。
+
+## 换 store
+
+```ts
+import { postgresAuthStore } from '@weifuwujs/auth/postgres'
+const auth = createAuth({ store: postgresAuthStore(process.env.DATABASE_URL!) })
+```
+
+自定义 store 用契约套件自证（memory / sqlite / postgres 跑的是同一套）：
+
+```ts
+import { authStoreContract } from '@weifuwujs/auth/testing'
+authStoreContract('my-store', () => myAuthStore())
+```
+
+`AuthStore` 可拆（`UserStore` / `SessionStore` / `ResetTokenStore`），`listUsers?()` 为可选管理能力。
+
+## 换 hasher（存量 bcrypt 惰性迁移）
+
+```ts
+import { scryptHasher } from '@weifuwujs/auth'
+import { createAuth } from '@weifuwujs/auth'
+
+const bcryptHasher = {
+  async hash(plain: string) {
+    return doBcryptHash(plain) // 你的实现
+  },
+  verify(plain: string, stored: string) {
+    if (stored.startsWith('$2')) return doBcryptCompare(plain, stored)
+    return scryptHasher.verify(plain, stored)
+  },
+  needsRehash: (stored: string) => stored.startsWith('$2'),
+}
+
+createAuth({ store, passwordHasher: bcryptHasher })
+```
+
+登录成功后 `needsRehash` 为真时自动用 `hash()` 重算并落库；`hash/verify` 允许同步或异步。
+
+## hooks
+
+```ts
+createAuth({
+  store,
+  hooks: {
+    onRegister: (user) => analytics.track('signup', user.id),
+    onLogin: (user) => audit.log('login', user.id),
+    onPasswordChange: (user) => mailer.notify(user.email),
+  },
+})
+```
+
+hooks 被 awaited；抛错只记日志，**不改变请求成败**（外发邮件、统计不得拖垮登录）。
+`sendResetToken(user, url)` 单独配置：未配置时 dev 打印链接、生产静默不发（防枚举）。
+
+## 侧表 profile（业务字段不进 users）
+
+```ts
+// 业务字段放自己的表/服务，用示例中间件按需加载
+const loadProfile: Middleware<Context, Context & { profile?: Profile }> = async (
+  req, ctx, next,
+) => next(req, { ...ctx, profile: await profiles.byUserId(ctx.auth?.user?.id) })
+
+const app = createApp()
+  .use(auth.middleware)
+  .use(loadProfile)
+  .mount(auth)
+```
+
+`users` 只存身份字段；`ctx.auth.user`（`PublicUser`）永不携带业务字段与 `passwordHash`。
+
+## CLI（不加载用户代码）
+
+```bash
+weifuwu-auth migrate [--store sqlite:data/auth.db|postgres://…]
+weifuwu-auth user:list
+weifuwu-auth user:disable ada@example.com
+weifuwu-auth user:reset-password ada@example.com [--password <plain>]
+```
+
+`user:reset-password` 未指定明文时生成 24 字节随机密码并只打印一次。
+
+## 测试辅助（`/testing`）
+
+自定义 `AuthStore` 驱动与内置驱动（memory / sqlite / postgres）共跑同一套契约：
+
+```ts
+import { authStoreContract } from '@weifuwujs/auth/testing'
+
+authStoreContract('my-store', () => myAuthStore())
+// 第三个参数可选：{ skip: true } 或 { skip: '未实现清理' }
+```
+
+契约覆盖：user CRUD 与唯一 email、session 生命周期与过期清理、reset token 单次消费与过期。
+
+## 安全默认清单
+
+| 项 | 默认 |
+| --- | --- |
+| 密码 | scrypt（`scrypt$N$r$p$salt$hash`），可插拔 + 惰性重算 |
+| 会话 | 只存 token 哈希；登录轮换；改密踢其他；disable/过期即时失效 |
+| cookie | `HttpOnly` + `SameSite=Lax` + `Path=/` + `Max-Age`；`Secure` 按配置 |
+| 防枚举 | 错误凭据统一文案；forgot 恒 200；时序均衡（dummy hash） |
+| 限流 | 登录/注册/重置默认每 IP 每分钟 10 次（429 + retry-after） |
+| Origin | 默认同源；表单 POST 与 JSON 同校验 |
+| 重置 | token 单次、短 TTL（默认 15 分钟）、只存哈希 |
+
+边界：单租户；不做 OAuth / 2FA / 邮箱验证 / 审计事件（P2），不做支付与后台模板。

package/dist/auth.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@weifuwujs/weifuwu';
+import type { Auth, AuthOptions } from './types.ts';
+export declare function createAuth<C extends Context = Context>(options: AuthOptions): Auth;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAO,OAAO,EAA8B,MAAM,oBAAoB,CAAA;AAOlF,OAAO,KAAK,EACV,IAAI,EAIJ,WAAW,EAMZ,MAAM,YAAY,CAAA;AA0MnB,wBAAgB,UAAU,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAyclF"}