@taicode/common-server 4.0.0-beta.2 → 4.0.0-beta.4

package/output/app/index.d.ts

@@ -1,16 +1,14 @@
-import './type-augment.js';
-export { defineServer, isServer, SERVER_BRAND, startServer, generateOpenApi } from './entries.js';
-export { loadEnvFiles, loadRuntimeEnvFiles, resolveConfigEnv, ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } from './env.js';
-export type { ConfigEnv } from './env.js';
-export { UserError, SystemError } from './errors.js';
-export { createRedis, createCache, DEFAULT_REDIS_CACHE_TTL_SECONDS } from './redis.js';
-export { createCorsMiddleware, createContextMiddleware, createAuthMiddleware, createRateLimitMiddleware, defaultMiddlewares, defaultAuthSkip } from './middleware/index.js';
-export { REQUEST_ID_HEADER } from './core/request-id.js';
-export { DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './core/openapi.js';
-export { extractPermissionOperations } from './permission-operations.js';
-export type { AppIdentity, AppInstance, LoggerLike, MaybePromise, RedisHandle, Live, ResourcesView, AssertNoDependencies, ServicesShape, ErrorClassifier, ResourcesContext, ResourcesFactory, ConfigContext, ConfigFactory, ServiceUnit, ServiceContext, ServicesFactory, MiddlewareUnit, MiddlewareContext, MiddlewaresFactory, RouterContext, RoutersFactory, ServerConfig, Server, StartServerOptions, ShutdownContext, OpenApiDocument, } from './types.js';
-export type { CacheSetupParams } from './redis.js';
-export type { PermissionOperation } from './permission-operations.js';
-export type { CorsMiddlewareOptions, ContextMiddlewareOptions, AuthMiddlewareOptions, AuthSkip, AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult, AccountIntegrationConfig, RateLimitMiddlewareOptions } from './middleware/index.js';
-export type { AccessControl, RateLimitRule } from './type-augment.js';
+import '../core/type-augment.js';
+export { defineServer, startServer, generateOpenApi } from '../core/entries.js';
+export { createTestServer } from '../core/test-support/test-server.js';
+export { loadRuntimeEnvironment } from '../core/test-support/environment.js';
+export { createCorsMiddleware } from '../cors/index.js';
+export { createAuthMiddleware } from '../auth/index.js';
+export { createRateLimitMiddleware } from '../rate-limit/index.js';
+export { createRedis, createCache } from '../redis/index.js';
+export type { AppInstance, ClientsContext, ClientsFactory, ClientsView, ConfigContext, LoggerLike, Middleware, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext, } from '../core/types.js';
+export type { AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult } from '../auth/index.js';
+export type { AuthMiddlewareOptions } from '../auth/index.js';
+export type { AuthClient, AuthVerifyPayload, RegisterPermissionOperationsPayload, } from '../core/modules/auth-provider/index.js';
+export type { RateLimitMiddlewareOptions } from '../rate-limit/index.js';
 //# sourceMappingURL=index.d.ts.map

package/output/app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAEA,OAAO,mBAAmB,CAAA;AAG1B,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAGjG,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACvI,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGzC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAA;AAGtF,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAG3K,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAA;AAGxE,YAAY,EAEV,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EAEX,IAAI,EACJ,aAAa,EACb,oBAAoB,EACpB,aAAa,EAEb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,cAAc,EAEd,YAAY,EACZ,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAA;AAC1O,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAsHA,OAAO,yBAAyB,CAAA;AAGhC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAiE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAyBtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AA6B5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAiBlE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAG5D,YAAY,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC7D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,mCAAmC,GACpC,MAAM,wCAAwC,CAAA;AAC/C,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA"}

package/output/app/index.js

@@ -1,18 +1,256 @@
-// 提供 `request.user` / `request.token` / `request.ctx` 与 `routeOptions.config.accessControls`
-// 的统一类型增强。
-import './type-augment.js';
-// ── 入口 API（N1 §1 / N2 §2.8 / §2.10 / §2.11）───────────────────
-export { defineServer, isServer, SERVER_BRAND, startServer, generateOpenApi } from './entries.js';
-// ── 配置层（env 固定加载）────────────────────────────────────────
-export { loadEnvFiles, loadRuntimeEnvFiles, resolveConfigEnv, ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } from './env.js';
-// ── 错误类型（N2 §2.12）──────────────────────────────────────────
-export { UserError, SystemError } from './errors.js';
-// ── 引导期 helper（`resources(ctx)` 里按需调用）─────────────────
-export { createRedis, createCache, DEFAULT_REDIS_CACHE_TTL_SECONDS } from './redis.js';
-// ── 标准中间件单元 ───────────────────────────────────────────────
-export { createCorsMiddleware, createContextMiddleware, createAuthMiddleware, createRateLimitMiddleware, defaultMiddlewares, defaultAuthSkip } from './middleware/index.js';
-// ── 公共路由 / header 常量 ───────────────────────────────────────
-export { REQUEST_ID_HEADER } from './core/request-id.js';
-export { DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './core/openapi.js';
-// ── 权限操作目录（框架内置；各仓用它替代自写实现）───────────────
-export { extractPermissionOperations } from './permission-operations.js';
+// 服务入口 barrel（`@taicode/common-server/app`）：**业务仓唯一需要 import 的路径**。
+//
+// 这里只有两样东西：**入口 API**（定义 / 启动 / 出文档 / 测试）与**可替换的能力工厂**
+// （中间件、Redis）。框架自己决定得了一律不进这里——core 装配、`request.ctx`、系统路由、
+// 响应信封全部在内部固定完成。
+//
+// ─────────────────────────────────────────────────────────────
+// ## 三十秒上手：一个服务写两个文件（出 spec 是构建期的第三个）
+// ─────────────────────────────────────────────────────────────
+//
+// ```ts
+// // source/server.ts —— **只定义，不启动**：不建连、不 listen、不读库
+// import { defineServer } from '@taicode/common-server/app'
+//
+// export const server = defineServer({
+//   app: { service: 'release', title: 'Release Service', version: packageJson.version },
+//
+//   // 我们拥有的基础设施：**只读 env**，构造时不建连
+//   resources: ({ env, disposer }) => ({ database: createDatabase(env.DATABASE_URL) }),
+//
+//   // 启动期的配置快照：可以读库，一次读完、进程内不再变
+//   config: ({ resources }) => loadConfig(resources),
+//
+//   // 我们调用的外部服务：地址 / 凭证来自 config，故排在 config 之后
+//   clients: ({ config }) => ({ webhook: createWebhookClient(config.webhook) }),
+//
+//   // 业务单元：**服务之间禁止互依**，要共享的东西放 clients
+//   services: ({ resources, config, clients }) => ({ user: createUserService({ resources, config, clients }) }),
+//
+//   // 中间件：对象 **键即名字、键序即注册序**；`client` 是本仓自己的 `AuthClient` 实现
+//   middlewares: (ctx) => ({ cors: createCorsMiddleware(ctx), auth: createAuthMiddleware(ctx, { client }) }),
+//
+//   // 业务路由：**只能拿 app / services / clients**（绕不过 service 直连数据层）
+//   routers: ({ app, services }) => {
+//     app.register(createUserRouter(services.user))
+//   },
+// })
+// ```
+//
+// ```ts
+// // source/index.ts —— 启动（listen + 信号处理都在这里面）
+// import { startServer } from '@taicode/common-server/app'
+// import { server } from './server'
+//
+// await startServer(server)
+// ```
+//
+// ```ts
+// // build/openapi-gen.ts —— 出 spec（不连库、不建连、不要求配置有效）
+// import { generateOpenApi } from '@taicode/common-server/app'
+// import { server } from '../source/server'
+//
+// await writeFile('openapi.json', JSON.stringify(await generateOpenApi(server), null, 2))
+// ```
+//
+// ─────────────────────────────────────────────────────────────
+// ## 每个槽位能拿什么（拿不到的就是**故意**拿不到）
+// ─────────────────────────────────────────────────────────────
+//
+// | 槽位 | ctx 里有 | 刻意没有 | 为什么 |
+// |---|---|---|---|
+// | `resources` | `env` / `log` / `disposer` / `registerClassifyError` | `config` / `services` / `app` | 资源只依赖 env，从结构上消灭「资源依赖配置」的循环 |
+// | `config` | `env` / `log` / `disposer` / `resources` | `services` / `app` | 此时服务还没构造 |
+// | `clients` | `log` / `disposer` / `resources` / `config` | `env` / `services` / `app` | 运行期不许回头读 env；客户端地址来自 config |
+// | `services` | `log` / `disposer` / `resources` / `config` / `clients` | `env` / `services` / `app` | 服务层属运行期；禁 service 互依 |
+// | `middlewares` | `app` / `log` / `disposer` / `services` / `config` / `clients` | `resources` / `env` | 中间件碰数据必须穿过 service |
+// | `routers` | `app` / `log` / `disposer` / `services` / `clients` | `resources` / `env` / `config` | 路由只能穿过 service |
+//
+// 资源释放**在创建处登记**：`ctx.disposer.add(() => closeXxx())`，关闭时框架按阶段逆序 flush，
+// 调用方不需要在任何地方再写一遍 close 逻辑。
+//
+// ─────────────────────────────────────────────────────────────
+// ## 路由怎么写（`operationId` 必须有）
+// ─────────────────────────────────────────────────────────────
+//
+// 每个路由都要给 schema，`operationId` / `summary` / `description` / `tags` 缺一即报错。
+// `operationId` 不是文档装饰：**权限目录就是从它采集的**（启动时 `auth` 上报给 account），
+// 没有它这个接口在权限系统里就是「未知操作」。
+//
+// ```ts
+// app.post('/user', {
+//   schema: routerSchema({
+//     operationId: 'createUser',
+//     summary: '创建用户',
+//     description: '管理员创建用户，返回创建后的实体',
+//     tags: ['user'],
+//     body: z.object({ username: z.string() }),
+//     response: { 200: userSchema },
+//   }),
+//   config: {
+//     accessControls: ['IgnorePermission'],        // 免登录写 'NoLoginRequired'
+//     rateLimit: { limit: 100, window: 60 },       // 可选：需装 rateLimit 中间件
+//   },
+// }, handler)
+// ```
+//
+// 返回体会被框架包成 `{ status, message, data }`，你只管返回业务数据；错误就
+// `throw new UserError(...)` / `throw new SystemError(...)`（从 `@taicode/common-base` 引，
+// 不是从本包）——状态码映射与信封由框架统一处理，**不要在路由里手拼响应体**。
+//
+// ─────────────────────────────────────────────────────────────
+// ## 目录布局（见 `common/product/designs/create-server/design.md` §7.1）
+// ─────────────────────────────────────────────────────────────
+// ```
+// source/
+// ├── core/            核心设计（锁定：不可替换、不可修改，**不对外导出装配**）
+// │   └── test-support/  测试支持（`createTestServer` / `loadRuntimeEnvironment`）
+// ├── app/             服务入口 barrel（本文件，不含实现）
+// ├── auth/            可选：鉴权中间件
+// ├── cors/            可选：CORS 中间件
+// ├── rate-limit/      可选：限流中间件 + 限流实现
+// ├── redis/           请求期 Redis / 缓存 helper
+// └── redis-queue/     可选：Redis 队列（含自己的 `test` 辅助）
+// ```
+//
+// 测试工具**与正式工具同一个导出面**（不多开 `test-support` subpath）：入口的测试同构体
+// 就是入口，分两个出口只会让调用方多记一个路径。归属按「谁提供功能，谁提供配套测试工具」：
+// 队列的测试辅助在 `redis-queue` 里，服务装配的测试入口在 `core/test-support/` 里。
+import '../core/type-augment.js';
+// ── 入口 API（定义 / 启动 / 出文档 / 测试）─────────────────────────
+export { defineServer, startServer, generateOpenApi } from '../core/entries.js';
+// 测试对象的**唯一**构造方式：同一份 `defineServer` 定义、同一套装配，不给槽位覆盖入口。
+//
+// env 加载、测试库结算、闸门、`process.env.DATABASE_URL` 改写都是它的**内部步骤**，
+// 不单独导出。导出那一步就等于把「什么时候该跑闸门」交给调用方——顺序本身就是安全前提，
+// 历史上有仓把环境闸门排在 env 加载之前（判的是空的 `ENV`），守卫于是变成装饰。
+//
+// ── 测试怎么写 ──────────────────────────────────────────────
+//
+// ```ts
+// import { createTestServer } from '@taicode/common-server/app'
+// import { server } from '../server'
+//
+// describe('UserRouter', () => {
+//   let testServer: Awaited<ReturnType<typeof createTestServer>>
+//   let db: PrismaClient
+//
+//   beforeAll(async () => {
+//     testServer = await createTestServer(server)   // 唯一构造方式
+//     db = testServer.resources.database            // 生产用的那个客户端，不是新建的
+//   })
+//
+//   afterAll(async () => {
+//     await testServer.app.close()                  // 七步关闭，与生产同一条路径
+//   })
+//
+//   beforeEach(async () => {
+//     await db.user.deleteMany()                    // 真实数据库，不 mock
+//   })
+//
+//   it('创建用户', async () => {
+//     const res = await testServer.app.inject({
+//       method: 'POST',
+//       url: '/user',
+//       payload: { username: 'alice' },
+//     })
+//
+//     expect(res.statusCode).toBe(200)
+//     expect(await db.user.count()).toBe(1)         // 断言落库，不只断言响应
+//   })
+//
+//   it('service 行为', async () => {
+//     // 也可以完全不走 HTTP：直接调装配好的业务单元
+//     await testServer.services.user.create({ username: 'bob' })
+//   })
+// })
+// ```
+//
+// **三条规矩**：
+// 1. **不要 mock 数据库 / Redis / 外部依赖**。它们由 `resources` / `clients` 真实构造，
+//    测试连的是 `*_test` schema 上的真库。要替换某个外部服务，改组合（见下），不改装配。
+// 2. **不要另造构造器**（`createTestApp` / `createTestDb` / `new PrismaClient()`）。
+//    另造一份就等于测试里有第二套接线，绿了也不能说明生产是对的。
+// 3. **只测一个模块**时组合定义，不要覆盖槽位：
+//    ```ts
+//    const onlyUser = defineServer({
+//      ...server,
+//      routers: ({ app, services }) => app.register(createUserRouter(services.user)),
+//    })
+//    const testServer = await createTestServer(onlyUser)
+//    ```
+//
+// 返回值 `TestServer` 就是测试需要的一切：`app`（原生 Fastify，用 `inject()`）/
+// `env`（`env.DATABASE_URL` 就是本次实际连的测试连接串）/ `resources` / `config` /
+// `clients` / `services` / `log`。没有 `close()` 之类同义包装——关闭就是 `app.close()`。
+export { createTestServer } from '../core/test-support/test-server.js';
+// ── 工具进程的 env 出口（**不在任何入口里跑**的进程）──────────────
+//
+// `prisma.config.ts` / `scripts/*.ts` / 被它们静态 import 的配置模块：ES 模块顶层求值早于
+// 入口函数执行，所以「入口里加载 env」救不了这些文件。这个函数就是它们唯一的开口，只加载
+// 运行期分层、不带任何测试闸门。
+//
+// **什么时候需要它**：你的文件**不是** `startServer` / `createTestServer` 启动的，
+// 却要读 `process.env`（数据库连接串、Redis 地址、脚本参数）。
+//
+// ```ts
+// // prisma.config.ts —— 必须在任何读取 env 的 import 之前调用
+// import { loadRuntimeEnvironment } from '@taicode/common-server/app'
+// loadRuntimeEnvironment()
+//
+// // scripts/seed.ts
+// import { loadRuntimeEnvironment } from '@taicode/common-server/app'
+// const env = loadRuntimeEnvironment()
+// console.log(env.DATABASE_URL)
+// ```
+//
+// **什么时候不要用它**：`source/server.ts` / `source/index.ts` / 测试文件。前者由
+// `startServer` 负责，后者由 `createTestServer` 负责——在那些地方再调一次只是重复读 dotenv，
+// 还会让人误以为 env 需要自己加载。
+export { loadRuntimeEnvironment } from '../core/test-support/environment.js';
+// ── 可替换的标准中间件工厂 ────────────────────────────────────────
+//
+// 只在**要改默认行为**时才出现；不写就是框架默认。三者都接收 `middlewares` 槽位的 `ctx`：
+//
+// ```ts
+// middlewares: (ctx) => ({
+//   cors: createCorsMiddleware(ctx),                 // 允许的源来自 config 的 `cors` 键（请求期现读）
+//   auth: createAuthMiddleware(ctx, { client }),     // client 必填：鉴权提供方实现
+//   rateLimit: createRateLimitMiddleware(ctx, { store }), // store 可选，缺省进程内 memory
+// })
+// ```
+//
+// `cors` / `rateLimit` 都**没有行为开关**，配置面只有输入参数：
+// - `cors`：允许的源来自 `config.cors`（`{ enabled, origins }`）；未配置 → 放行任意源并 warn 一次。
+// - `rateLimit`：**限流规则写在路由上**，不在中间件里：
+//   ```ts
+//   app.get('/user', {
+//     schema: ...,
+//     config: { rateLimit: { limit: 100, window: 60, keys: ['ip'] } },  // 未声明的路由不空转
+//   }, handler)
+//   ```
+//   需要 Redis 存储时，在 `services` 里构造 `RedisRateLimitStore` 再注入 `store`
+//   （中间件拿不到 `resources`，这是刻意的）。
+//
+// `auth` 的两件事由框架固定、**不可关闭**：① 跳过判定（`OPTIONS` / 未匹配路由 /
+// 路由声明 `NoLoginRequired`）；② 启动时从 `app.swagger()` 采集权限目录并上报。
+// 你只需要实现 `AuthClient` 的 `verify` / `registerPermissionOperations` 两个方法。
+export { createCorsMiddleware } from '../cors/index.js';
+export { createAuthMiddleware } from '../auth/index.js';
+export { createRateLimitMiddleware } from '../rate-limit/index.js';
+// ── 请求期 Redis / 缓存 helper（资源包里自行构造）─────────────────
+//
+// 框架**不替你建 Redis**；在 `resources` 里按需构造，并在创建处登记释放：
+//
+// ```ts
+// resources: ({ env, log, disposer }) => {
+//   const redis = createRedis(env, log)          // 无 REDIS_URL → undefined
+//   if (redis) disposer.add(() => redis.dispose())
+//   return { redis, cache: createCache({ env, prefix: 'release', redis }) }
+// }
+// ```
+//
+// 两者都是**惰性包装**：构造时不建连、不 ping，首次真正使用才连——「出 spec 不连库 / 不连
+// Redis」因此是结构性的，而不是靠调用方自觉。`createCache` 不传 `redis` 也能用（自建客户端，
+// 或在没有 `REDIS_URL` 时退化成纯进程内一级缓存）。
+export { createRedis, createCache } from '../redis/index.js';

package/output/auth/index.d.ts

@@ -0,0 +1,72 @@
+import type { AuthClient, AuthVerifyPayload } from '../core/modules/auth-provider/index.js';
+import type { Middleware, MiddlewareContext } from '../core/types.js';
+/**
+ * 标准中间件单元 `auth`（可替换）。
+ *
+ * 本单元只做「**框架语义**」，不碰任何鉴权提供方的 HTTP：
+ *
+ * 1. 跳过判定（**固定**：`OPTIONS` → 未匹配路由 → 路由声明 `NoLoginRequired`）；
+ * 2. 取凭证（`Authorization: Bearer` / `Authorization: apikey-*` / `cookieNames` 声明的 cookie）；
+ * 3. 调 `client.verify`，把结果写回 `request.user` / `request.token`；
+ * 4. `onReady` 时调 `client.registerPermissionOperations`（**强制**，失败不致命）。
+ *
+ * 权限目录**只从 OpenAPI 文档派生**（`app.swagger()`）：core 保证「所有路由必须声明 schema」
+ * （缺失直接启动失败），所以文档里出现什么，权限系统里就有什么，不存在两套来源漂移的可能。
+ *
+ * **提供方是业务注入的，且可替换**（本文件的 `client`，类型见
+ * `core/modules/auth-provider`）：account 只是当前的主要实现，不是框架的预设——
+ * 自建 IAM、OIDC 网关、进程内静态校验都可以填进来。客户端构造需要地址、凭证、
+ * 协议与 HTTP 栈，这些只有业务侧才知道怎么配，框架不提供实现（设计 §5.2.2）。
+ *
+ * ## 为什么配置面只有两个字段
+ *
+ * `skip` / `mapError` / `registerPermissions` 曾经也是选项，现全部删除：
+ *
+ * - **跳过逻辑不可自定义**：放行是安全决策，一旦可按服务改写，「这条路由到底要不要
+ *   登录」就不再能从路由声明上读出来。约定只剩一条——**需要公开就声明
+ *   `config.accessControls: ['NoLoginRequired']`**。
+ * - **错误映射不可自定义**：错误分类是响应契约的一部分（401/403 还是 500），让调用方
+ *   替换就等于允许各仓自造状态码。标准做法是提供方**自己抛** `UserError` /
+ *   `SystemError`，框架原样透出；其它一切（网络 / 超时 / 非 JSON）统一
+ *   `SystemError('EXTERNAL_SERVICE_ERROR')`。
+ * - **权限自注册不可关闭**：权限目录是 account 侧判权的前提，关掉它等于让本服务的
+ *   全部接口在权限系统里变成「未知操作」，只有坏处。
+ *
+ * 剩下两个字段都是**输入参数**（不是行为开关）：提供方客户端 + 凭证在哪个 cookie 里。
+ */
+/** `verify` 的入参：框架校验入参 + 服务名 */
+export type AuthVerifyInput = AuthVerifyPayload;
+/** 请求元信息 / 校验结果（形状定义在 auth-provider 契约里） */
+export type { AuthVerifyMetadata, AuthVerifyResult } from '../core/modules/auth-provider/index.js';
+/**
+ * `auth` 中间件的配置面：**只接受输入参数**，不提供行为开关。
+ *
+ * 标准行为（跳过判定 / 错误归类 / 权限自注册）由框架固定，不开放覆盖——
+ * 见文件头的「为什么配置面只有两个字段」。
+ */
+export interface AuthMiddlewareOptions {
+    /**
+     * 鉴权提供方客户端（**必填**，业务服务实现；框架只定义契约，**允许任意实现替换**）。
+     *
+     * 由业务在自己的 `middlewares` 槽位里构造（可读 `ctx.config` / `ctx.services`），
+     * 职责：校验凭证 + 上报权限目录。account 只是其中一种实现——自带校验逻辑的服务
+     * （如 account 自己）实现同一个接口走进程内调用即可，不必绕 HTTP 回自己。
+     * 契约见 `core/modules/auth-provider`。
+     */
+    client: AuthClient;
+    /**
+     * 读取 token 的 cookie 名（**显式声明优先**）。
+     *
+     * 未传或传空数组时，请求期现读配置的 `server.cookieNames`（各仓的 cookie 名由运维改配置，
+     * 不能在注册期就定下）；仍为空则回落 `['token']`。
+     */
+    cookieNames?: readonly string[];
+}
+/**
+ * 构造标准 `auth` 中间件。
+ *
+ * `client` **必填**（类型上）且必须有运行期实现：装了鉴权却没有校验实现是配置错误，
+ * 构造期直接抛错——不留「请求期才 fail-closed」的窗口，也不允许静默放行。
+ */
+export declare function createAuthMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>, options: AuthMiddlewareOptions): Middleware;
+//# sourceMappingURL=index.d.ts.map

package/output/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/auth/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAG3F,OAAO,KAAK,EAA2B,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAG9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,gCAAgC;AAChC,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAE/C,4CAA4C;AAC5C,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAA;AAElG;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAqID;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAkEvI"}

package/output/auth/index.js

@@ -0,0 +1,176 @@
+import { catchIt, SystemError, UserError } from '@taicode/common-base';
+import { readConfigKey } from '../core/boot/context.js';
+import { readServerIdentity } from '../core/modules/identity/index.js';
+import { extractPermissionOperations } from '../core/modules/permission-operations/index.js';
+/** cookie 名缺省值（既未显式传入、配置也没给时使用） */
+const DEFAULT_COOKIE_NAMES = ['token'];
+/**
+ * 解析 cookie 名：显式参数 → 配置 `server.cookieNames` → 缺省值。
+ *
+ * **必须请求期调用**：出 spec 路径不跑 `config` 槽位，`ctx.config` 读到即抛 `CONFIG_UNAVAILABLE`。
+ */
+function resolveCookieNames(config, declared) {
+    if (declared !== undefined && declared.length > 0) {
+        return declared;
+    }
+    const server = readConfigKey(config, 'server');
+    return Array.isArray(server?.cookieNames) && server.cookieNames.length > 0 ? server.cookieNames : DEFAULT_COOKIE_NAMES;
+}
+function extractAuth(request, cookieNames) {
+    const authorization = request.headers.authorization;
+    if (typeof authorization === 'string' && authorization.startsWith('Bearer ')) {
+        return { token: authorization.slice('Bearer '.length).trim() };
+    }
+    if (typeof authorization === 'string' && authorization.startsWith('apikey-')) {
+        return { apiKey: authorization.slice('apikey-'.length).trim() };
+    }
+    for (const name of cookieNames) {
+        const value = request.cookies?.[name];
+        if (typeof value === 'string' && value) {
+            return { token: value };
+        }
+    }
+    return {};
+}
+/**
+ * 固定跳过判定（**不可覆盖**）：`OPTIONS` → 未匹配路由 → 路由声明 `NoLoginRequired`。
+ *
+ * 不按路径前缀特判文档出口：`GET /system/openapi` 自己声明 `NoLoginRequired`，
+ * **路由是唯一事实来源**——这样「哪些接口免登录」永远能从路由声明上读出来。
+ */
+function shouldSkip(request) {
+    if (request.method === 'OPTIONS') {
+        return true;
+    }
+    if (!request.routeOptions?.url) {
+        return true;
+    }
+    return request.routeOptions.config?.accessControls?.includes('NoLoginRequired') === true;
+}
+/**
+ * 固定错误归类（**不可覆盖**）：`UserError` / `SystemError` 原样透出，其余 → `EXTERNAL_SERVICE_ERROR`。
+ *
+ * 提供方若想表达「凭证无效 / 权限不足」，必须自己抛标准错误——这正是「按标准设计实现」的落点。
+ */
+function toStandardAuthError(error) {
+    if (UserError.is(error) || SystemError.is(error)) {
+        return error;
+    }
+    return new SystemError('EXTERNAL_SERVICE_ERROR', { cause: error });
+}
+/**
+ * 从 OpenAPI 文档收集权限目录（**去重 + 稳定排序**）。
+ *
+ * 唯一来源就是 `app.swagger()`：不再同时维护一份 `onRoute` 注册表。两套来源必然漂移
+ * （`HEAD` / 前缀 / 插件路由只要有一处处理不同就对不上），而文档既能保证与对外契约一致，
+ * 也让「文档里有什么、权限系统里就有什么」成为可验证的事实。
+ *
+ * 同一 `operationId` 出现两次是路由声明问题（core 的 schema 守卫只保证字段存在，不保证唯一），
+ * 按首次出现保留并告警。稳定排序让目录内容不随注册顺序抖动，方便提供方 diff 与缓存。
+ */
+function collectPermissionOperations(app, log) {
+    const swagger = app.swagger;
+    if (typeof swagger !== 'function') {
+        log.warn('[PermissionOperation][auth] 未启用 OpenAPI 文档，跳过权限目录自注册');
+        return [];
+    }
+    const collected = extractPermissionOperations(swagger.call(app));
+    const seen = new Set();
+    const operations = [];
+    const duplicates = [];
+    for (const operation of collected) {
+        if (seen.has(operation.operation)) {
+            duplicates.push(operation.operation);
+            continue;
+        }
+        seen.add(operation.operation);
+        operations.push(operation);
+    }
+    if (duplicates.length > 0) {
+        log.warn({ operations: duplicates }, '[PermissionOperation][auth] 检测到重复 operationId，已按首次声明去重（请修正路由声明）');
+    }
+    operations.sort((a, b) => (a.operation < b.operation ? -1 : a.operation > b.operation ? 1 : 0));
+    return operations;
+}
+/** 提交权限目录（失败**不致命**：只记日志，不中断启动） */
+async function submitPermissionOperations(client, log, identity, operations) {
+    const { service, version } = identity;
+    if (!version) {
+        log.warn({ service }, '[PermissionOperation][auth] 身份块 version 为空：权限目录将无法按版本归组');
+    }
+    if (operations.length === 0) {
+        log.warn({ service, version }, '[PermissionOperation][auth] 未采集到任何带 operationId 的路由，跳过权限目录自注册（请检查路由 schema）');
+        return;
+    }
+    const result = await catchIt(client.registerPermissionOperations({ service, version, operations }));
+    if (result.isError()) {
+        log.error({ error: result.error, service, version, count: operations.length }, '[PermissionOperation][auth] 权限目录自注册失败（不阻断启动）');
+        return;
+    }
+    log.info({ service, version, count: operations.length }, '[PermissionOperation][auth] 权限目录自注册完成');
+}
+/**
+ * 构造标准 `auth` 中间件。
+ *
+ * `client` **必填**（类型上）且必须有运行期实现：装了鉴权却没有校验实现是配置错误，
+ * 构造期直接抛错——不留「请求期才 fail-closed」的窗口，也不允许静默放行。
+ */
+export function createAuthMiddleware(ctx, options) {
+    const client = options?.client;
+    if (!client || typeof client.verify !== 'function') {
+        throw new Error('[auth] auth 中间件缺少校验实现：请通过 `createAuthMiddleware(ctx, { client })` 注入鉴权提供方');
+    }
+    return (app) => {
+        const identity = readServerIdentity(app);
+        if (!identity) {
+            throw new Error('[auth] 读不到身份块：`createAuthMiddleware` 必须挂在 `startServer` / `generateOpenApi` 的 app 上');
+        }
+        app.addHook('preValidation', async (request) => {
+            if (shouldSkip(request)) {
+                return;
+            }
+            // cookie 名**请求期**解析：显式参数优先，其次现读配置（配置可被运维改动）
+            const { token, apiKey } = extractAuth(request, resolveCookieNames(ctx.config, options.cookieNames));
+            if (!token && !apiKey) {
+                throw new UserError('INVALID_TOKEN', undefined, '缺少访问凭证');
+            }
+            const verifyInput = {
+                token,
+                apiKey,
+                service: identity.service,
+                // 权限目录同源、与 url 解耦：优先路由 `schema.operationId`，未声明时回落 url
+                operation: request.routeOptions?.schema?.operationId ?? request.routeOptions?.url,
+                resource: request.params,
+                accessControls: request.routeOptions?.config?.accessControls,
+                metadata: {
+                    requestId: request.id,
+                    method: request.method,
+                    url: request.url,
+                    ip: request.ip,
+                    ips: request.ips,
+                    userAgent: request.headers['user-agent'],
+                    referrer: request.headers.referer,
+                },
+            };
+            try {
+                const result = await client.verify(verifyInput);
+                request.user = result.user;
+                request.token = result.token ?? token;
+            }
+            catch (error) {
+                throw toStandardAuthError(error);
+            }
+        });
+        // 权限目录自注册：**运行期无条件执行**（唯一前提是有 client，而 client 是必填的）。
+        //
+        // 时点必须在 `onReady`：`app.swagger()` 只有在 `ready()` 之后才可用（swagger 自身也挂
+        // `onReady`，且它在 core 阶段先注册，故本钩子执行时文档已就绪）。
+        //
+        // **为什么不需要区分入口**：`generateOpenApi` 根本不注册中间件（它只装路由与 schema
+        // 契约），所以本单元在出文档路径里压根不会被构造，不存在「构建期误写权限系统」的可能。
+        // 这也是「出文档不装配运行期能力」的直接收益：副作用随能力一起消失，不需要额外标记。
+        app.addHook('onReady', async () => {
+            await submitPermissionOperations(client, ctx.log, identity, collectPermissionOperations(app, ctx.log));
+        });
+    };
+}

package/output/core/assemble.d.ts

@@ -0,0 +1,64 @@
+import type { ErrorClassifier } from './modules/response/index.js';
+import type { ConfigEnv } from './env.js';
+import type { AppIdentity } from './types.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * core 步骤 `createFastify`（`prepare`）。
+ *
+ * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
+ * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
+ *
+ * 固定装配，**不从包对外导出**：对外入口只有 `defineServer` / `startServer` / `generateOpenApi`。
+ */
+export declare function createFastify(env: ConfigEnv): FastifyInstance;
+/**
+ * 出文档用的**最小实例**（`generateOpenApi` 专用）。
+ *
+ * 没有 logger、没有 `requestId`、没有 `trustProxy`——这些只在**有请求**时才有意义，
+ * 而构建期一条请求都不会发。`logger: false` 下 `app.log` 仍是 `abstract-logging` 的
+ * 空实现，满足 `LoggerLike`，因此下游单元拿到的 `ctx.log` 调用不会炸，也不会产生输出。
+ */
+export declare function createDocumentFastify(): FastifyInstance;
+/** core 装配入参 */
+export interface CoreRegistrationOptions {
+    /** 身份块（`service` / `title` / `version`）：openapi + 内置单元从这里读 */
+    identity: AppIdentity;
+    env: ConfigEnv;
+    /** 资源错误分类（各资源经 `ctx.registerClassifyError` 注册；缺省 = 落 `UNKNOWN_ERROR`） */
+    classifyResourceError?: ErrorClassifier;
+    /** 取**已加载**配置中某个键的访问器（cookie domain 等**惰性**取值；不得在构造期调用） */
+    readConfig: (key: string) => unknown;
+}
+/**
+ * **schema 契约**（固定序，不可替换）：`identity` → `schema`（zod compiler）→ 路由契约守卫。
+ *
+ * 两个入口都必须有它：
+ * - `startServer` 要让 zod 真的校验/序列化请求，并让「路由缺 `schema`」在注册处就失败；
+ * - `generateOpenApi` 要把 zod 转成 JSON Schema 出文档，也要同一个守卫——**文档就是权限目录**，
+ *   构建期放过的路由会在线上变成「接口永远判不过」。
+ *
+ * 单独成函数是为了让「运行期 core」与「文档 core」两条装配路径共用同一段契约，
+ * 而不用把整段运行期能力拖进出文档路径。
+ */
+export declare function registerSchemaContract(app: FastifyInstance, options: Pick<CoreRegistrationOptions, 'identity'>): void;
+/**
+ * **文档 core**（`generateOpenApi` 专用）：schema 契约 + swagger。
+ *
+ * 只有这三件事与「把 zod schema 转成 OpenAPI 文档」有关：身份（`info.title` /
+ * `info.version`）、zod compiler（转换前得能读懂 zod）、守卫（不让文档缺条目）、swagger（转换器）。
+ * `requestContext` / `cookie` / `response` / `requestId` 全部**不装**——它们只影响
+ * 请求怎么被处理，而构建期一条请求都不会发。
+ */
+export declare function registerDocumentCore(app: FastifyInstance, options: Pick<CoreRegistrationOptions, 'identity'>): Promise<void>;
+/**
+ * core 装配（固定序，不可替换）：`identity` → `schema`（+ 路由契约守卫）→ `requestContext`
+ * → `cookie` → `response` → `openapi` → `requestId` 回吐。
+ *
+ * 全部为框架内置能力，**不暴露选项面**；`request.ctx` 的装配也在这一步完成（`type-augment` 的
+ * 类型承诺因此总有运行期对应物）。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
+ * 故出 spec 路径（`readConfig` 不可用）不会触发。
+ *
+ * 这里**不建路由注册表**：权限目录直接由 `app.swagger()` 生成的文档派生（OpenAPI 是唯一来源）。
+ */
+export declare function registerCore(app: FastifyInstance, options: CoreRegistrationOptions): Promise<void>;
+//# sourceMappingURL=assemble.d.ts.map