@taicode/common-server 3.7.13 → 4.0.0-beta.1

package/output/app/lifecycle.js

@@ -0,0 +1,99 @@
+/**
+ * 生命周期序（N1 §4 / N2 §2.5）。
+ *
+ * **只有 `services` 参与生命周期**：
+ * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
+ * - 顺序语义只有一条：按**对象声明序** `init`、**逆序** `dispose`；
+ * - `middlewares` 按数组序注册，**不参与生命周期**（要常驻资源就放 `services`）；
+ * - `resources` 只是惰性包装（构造不建连），框架不替它们做生命周期。
+ */
+export const SERVICES_STAGE = 'services';
+/** `middlewares` 的**注册期日志**阶段标签（中间件不参与生命周期，只用于注册日志） */
+export const MIDDLEWARES_LOG_STAGE = 'middlewares';
+/** 生命周期相位（逐单元日志字段 `phase`） */
+export const LIFECYCLE_PHASE_INIT = 'init';
+export const LIFECYCLE_PHASE_DISPOSE = 'dispose';
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * `services` 有效名字：**对象键即单元名**（N1 §4：没有 `name` 字段）。
+ */
+export function serviceUnitName(key) {
+    return key;
+}
+/**
+ * `middlewares` 日志名字：`unit.name ?? '<service>:middleware[<index>]'`（仅用于注册期日志）。
+ */
+export function middlewareUnitName(service, unit, index) {
+    if (isObject(unit) && typeof unit.name === 'string' && unit.name.length > 0) {
+        return unit.name;
+    }
+    return `${service}:middleware[${index}]`;
+}
+async function callInit(unit) {
+    if (isObject(unit) && typeof unit.init === 'function') {
+        await unit.init();
+    }
+}
+async function callDispose(unit) {
+    if (isObject(unit) && typeof unit.dispose === 'function') {
+        await unit.dispose();
+    }
+}
+/**
+ * 执行单个生命周期单元（init / dispose），并打逐单元日志。
+ *
+ * 失败时 `error` 后**重新抛出**：调用方（`startServer` 直接冒泡；关闭流程逐步骤聚合）自行决定后续。
+ */
+async function runLifecycleUnit(params, unit, value, phase) {
+    const fields = { service: params.service ?? '', unit, stage: SERVICES_STAGE, phase };
+    params.log?.debug(fields, `[lifecycle] ${phase} "${unit}" start`);
+    try {
+        if (phase === LIFECYCLE_PHASE_INIT) {
+            await callInit(value);
+        }
+        else {
+            await callDispose(value);
+        }
+        params.log?.debug(fields, `[lifecycle] ${phase} "${unit}" done`);
+    }
+    catch (error) {
+        params.log?.error({ ...fields, error }, `[lifecycle] ${phase} "${unit}" failed`);
+        throw error;
+    }
+}
+/**
+ * 启动序：`services` 按**对象声明序**逐项 `await init?.()`；逐项打日志。
+ */
+export async function initServiceUnits(params) {
+    for (const key of Object.keys(params.services ?? {})) {
+        await runLifecycleUnit(params, serviceUnitName(key), params.services?.[key], LIFECYCLE_PHASE_INIT);
+    }
+}
+/**
+ * 关闭序：`services` 按声明序**逆序**逐项 `dispose?.()`。
+ */
+export function buildDisposeOrder(params) {
+    const steps = [];
+    for (const key of Object.keys(params.services ?? {}).reverse()) {
+        steps.push(() => runLifecycleUnit(params, serviceUnitName(key), params.services?.[key], LIFECYCLE_PHASE_DISPOSE));
+    }
+    return steps;
+}
+/**
+ * 关闭步 `disposeServices`：`services` 声明序逆序释放。
+ *
+ * 单元级失败已在 `runLifecycleUnit` 内 `log.error`（带 service / unit / stage / phase）；
+ * 此处仅保证单步不阻断后续。
+ */
+export async function disposeServices(params) {
+    for (const step of buildDisposeOrder(params)) {
+        try {
+            await step();
+        }
+        catch {
+            // 单元级 `runLifecycleUnit` 已 log.error；此处仅保证不阻断后续
+        }
+    }
+}

package/output/app/lifecycle.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lifecycle.test.d.ts.map

package/output/app/lifecycle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.test.d.ts","sourceRoot":"","sources":["../../source/app/lifecycle.test.ts"],"names":[],"mappings":""}

package/output/app/lifecycle.test.js

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { defineServer, startServer } from './entries.js';
+import { buildDisposeOrder, initServiceUnits, serviceUnitName } from './lifecycle.js';
+/**
+ * 生命周期（N1 §4）。
+ *
+ * - **只有 `services` 参与**：按**对象声明序** `init` / **逆序** `dispose`；
+ * - **没有 `dependsOn`**（`services` 的 ctx 没有 `services` 字段，编译期禁止互依）；
+ * - 单元名 = **对象键**；
+ * - `middlewares` 按数组序注册，**不参与生命周期**。
+ */
+describe('init / dispose 顺序：声明序 / 逆序（N1 §4 / §5）', () => {
+    it('init：services 按对象声明序', async () => {
+        const calls = [];
+        const services = {
+            ledger: {
+                init: () => {
+                    calls.push('init:ledger');
+                },
+            },
+            repository: {
+                init: () => {
+                    calls.push('init:repository');
+                },
+            },
+            mailer: {
+                init: () => {
+                    calls.push('init:mailer');
+                },
+            },
+        };
+        await initServiceUnits({ services });
+        expect(calls).toEqual(['init:ledger', 'init:repository', 'init:mailer']);
+    });
+    it('dispose：services 按声明序逆序', async () => {
+        const calls = [];
+        const services = {
+            ledger: {
+                dispose: () => {
+                    calls.push('dispose:ledger');
+                },
+            },
+            repository: {
+                dispose: () => {
+                    calls.push('dispose:repository');
+                },
+            },
+        };
+        for (const step of buildDisposeOrder({ services })) {
+            await step();
+        }
+        expect(calls).toEqual(['dispose:repository', 'dispose:ledger']);
+    });
+    it('不是 ServiceUnit 的值照样能放（框架只检测 init / dispose 是否为函数）', async () => {
+        const calls = [];
+        const services = {
+            plain: { hello: 'world' },
+            lifecycle: {
+                init: () => {
+                    calls.push('init:lifecycle');
+                },
+            },
+        };
+        await initServiceUnits({ services });
+        expect(calls).toEqual(['init:lifecycle']);
+    });
+    it('单元名 = 对象键', () => {
+        expect(serviceUnitName('ledger')).toBe('ledger');
+        expect(serviceUnitName('repository')).toBe('repository');
+    });
+});
+describe('startServer 集成：声明序 init / 逆序 dispose', () => {
+    it('services 声明序 init；中间件按数组序注册但不参与生命周期；close 时 services 逆序 dispose', async () => {
+        const calls = [];
+        const server = defineServer({
+            app: { service: 'lifecycle-integration', title: 'Lifecycle Integration', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({
+                ledger: {
+                    init: () => {
+                        calls.push('init:ledger');
+                    },
+                    dispose: () => {
+                        calls.push('dispose:ledger');
+                    },
+                },
+                repository: {
+                    init: () => {
+                        calls.push('init:repository');
+                    },
+                    dispose: () => {
+                        calls.push('dispose:repository');
+                    },
+                },
+                mailer: {
+                    init: () => {
+                        calls.push('init:mailer');
+                    },
+                    dispose: () => {
+                        calls.push('dispose:mailer');
+                    },
+                },
+            }),
+            middlewares: () => [
+                {
+                    name: 'm1',
+                    register: () => {
+                        calls.push('register:m1');
+                    },
+                },
+                {
+                    name: 'm2',
+                    register: () => {
+                        calls.push('register:m2');
+                    },
+                },
+            ],
+            routers: () => undefined,
+        });
+        const app = await startServer(server, { listen: false });
+        expect(calls).toEqual(['init:ledger', 'init:repository', 'init:mailer', 'register:m1', 'register:m2']);
+        await app.close();
+        expect(calls).toEqual([
+            'init:ledger',
+            'init:repository',
+            'init:mailer',
+            'register:m1',
+            'register:m2',
+            'dispose:mailer',
+            'dispose:repository',
+            'dispose:ledger',
+        ]);
+    });
+    it('单元 init 抛错 → startServer 冒泡失败', async () => {
+        const server = defineServer({
+            app: { service: 'lifecycle-init-error', title: 'Lifecycle Init Error', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({
+                broken: {
+                    init: () => {
+                        throw new Error('init boom');
+                    },
+                },
+            }),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        await expect(startServer(server, { listen: false })).rejects.toThrow('init boom');
+    });
+});

package/output/app/middleware/auth.d.ts

@@ -0,0 +1,71 @@
+import type { MiddlewareContext, MiddlewareUnit } from '../types.js';
+import type { FastifyRequest } from 'fastify';
+/**
+ * 标准中间件单元 `auth`（可替换）。
+ *
+ * 校验下游 token（4/5 服务用）。默认 `skip`：`OPTIONS` → 未匹配路由 → `NoLoginRequired` → `docPath`。
+ * 默认 `verify` 为**框架内置 account HTTP 客户端**（`POST /gateway/verify` + 信封解析），可经
+ * `verify` 整体替换；account `serviceUrl` 门槛**仅作用于内置 verify**（自定义 `verify` 不受约束）。
+ *
+ * 另在 `onReady` 阶段默认（`registerPermissions !== false`）向 account **自注册权限操作目录**
+ * （`POST /permission/operation/register`）。
+ */
+export interface AuthVerifyMetadata {
+    requestId?: string;
+    method?: string;
+    url?: string;
+    ip?: string;
+    ips?: string[];
+    userAgent?: string;
+    referrer?: string;
+}
+export interface AuthVerifyInput {
+    token?: string;
+    apiKey?: string;
+    operation?: string;
+    /** 路由参数（`request.params`），如 `:id` 这类路径参数 */
+    resource?: Record<string, unknown>;
+    accessControls?: string[];
+    /** 请求元信息（仅供下游审计 / 日志；不参与鉴权判定） */
+    metadata?: AuthVerifyMetadata;
+}
+export interface AuthVerifyResult {
+    user?: unknown;
+    token?: unknown;
+}
+/** 跳过条件（返回 true 即放行）；缺省为框架默认 skip 集合 */
+export type AuthSkip<C = unknown, S = unknown> = (request: FastifyRequest, ctx: MiddlewareContext<C, S>) => boolean | undefined;
+export interface AccountIntegrationConfig {
+    enabled?: boolean;
+    serviceUrl?: string;
+    accessKey?: string;
+    secretKey?: string;
+}
+export interface AuthMiddlewareOptions<C = unknown, S = unknown> {
+    /**
+     * 整体替换校验实现（缺省走框架内置 account HTTP 客户端）。
+     *
+     * 提供本项时**不做** account `serviceUrl` 门槛：`serviceUrl` 只服务于内置 verify。
+     */
+    verify?: (input: AuthVerifyInput & {
+        service: string;
+    }, ctx: MiddlewareContext<C, S>) => Promise<AuthVerifyResult>;
+    /** 读取 token 的 cookie 名（缺省现读配置的 `server.cookieNames`） */
+    cookieNames?: string[];
+    /**
+     * 是否在 `startServer` 的 `onReady` 阶段向 account 自注册权限操作（默认 `true`）。
+     *
+     * 跳过条件：本项为 `false`；或配置的 `account` 无 `serviceUrl`（自然排除 account 自身）；
+     * 或出 spec 路径（`generateOpenApi` 不跑 `config` 槽位，配置不可用）。注册失败**不致命**：
+     * `log.error` 后继续启动，不中断 `startServer`。
+     */
+    registerPermissions?: boolean;
+    /** 跳过条件（返回 true 即放行）；缺省为框架默认 skip 集合 */
+    skip?: AuthSkip<C, S>;
+    /** 错误映射（缺省：非 `UserError` / `SystemError` 一律 → `SystemError('EXTERNAL_SERVICE_ERROR')`） */
+    mapError?: (error: unknown) => Error;
+}
+/** 框架默认 skip：OPTIONS → 未匹配路由 → NoLoginRequired → docPath */
+export declare function defaultAuthSkip(request: FastifyRequest, ctx: MiddlewareContext<unknown, unknown>): boolean;
+export declare function createAuthMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>, options?: AuthMiddlewareOptions<C, S>): MiddlewareUnit;
+//# sourceMappingURL=auth.d.ts.map

package/output/app/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../source/app/middleware/auth.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C;;;;;;;;;GASG;AAEH,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,wCAAwC;AACxC,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,CAC/C,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,KACzB,OAAO,GAAG,SAAS,CAAA;AAExB,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IAC7D;;;;OAIG;IACH,MAAM,CAAC,EAAE,CACP,KAAK,EAAE,eAAe,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAC5C,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,KACzB,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC9B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,wCAAwC;IACxC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACrB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAA;CACrC;AAmCD,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,OAAO,CAgB1G;AAgFD,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAM,GAAG,cAAc,CAoGtJ"}

package/output/app/middleware/auth.js

@@ -0,0 +1,190 @@
+import { readConfigKey } from '../context.js';
+import { readServerIdentity } from '../core/identity.js';
+import { DOC_ROUTE_PREFIX } from '../core/openapi.js';
+import { SystemError, UserError } from '../errors.js';
+import { readRegisteredOperations, toPermissionOperations } from '../permission-operations.js';
+function readAccount(config) {
+    return readConfigKey(config, 'account');
+}
+function readServer(config) {
+    return readConfigKey(config, 'server');
+}
+function readCookieNames(config, fallback) {
+    if (fallback && fallback.length > 0) {
+        return fallback;
+    }
+    const configured = readServer(config)?.cookieNames;
+    return Array.isArray(configured) && configured.length > 0 ? configured : ['token'];
+}
+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 {};
+}
+/** 框架默认 skip：OPTIONS → 未匹配路由 → NoLoginRequired → docPath */
+export function defaultAuthSkip(request, ctx) {
+    void ctx;
+    if (request.method === 'OPTIONS') {
+        return true;
+    }
+    const url = request.routeOptions?.url;
+    if (!url) {
+        return true;
+    }
+    if (url.startsWith(DOC_ROUTE_PREFIX)) {
+        return true;
+    }
+    if (request.routeOptions?.config?.accessControls?.includes('NoLoginRequired')) {
+        return true;
+    }
+    return false;
+}
+async function defaultVerify(input, account) {
+    const serviceUrl = account?.serviceUrl;
+    if (!serviceUrl) {
+        // 内置 verify 依赖 account `serviceUrl`；缺失时抛明确错误
+        // （不再 `new URL(path, undefined)` 抛 TypeError）
+        throw new SystemError('CONFIG_UNAVAILABLE', undefined, 'account 未配置 serviceUrl，无法使用内置 verify（可用 verify 选项整体替换校验实现）');
+    }
+    const target = new URL('/gateway/verify', serviceUrl);
+    const response = await fetch(target, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            token: input.token,
+            apiKey: input.apiKey,
+            service: input.service,
+            operation: input.operation,
+            resource: input.resource,
+            accessControls: input.accessControls,
+            metadata: input.metadata,
+        }),
+    });
+    const payload = (await response.json());
+    if (!response.ok || payload.status !== 'SUCCESS') {
+        throw new UserError(payload.status ?? 'AUTH_FAILED', undefined, payload.message ?? '');
+    }
+    return { user: payload.data?.user, token: payload.data?.token ?? input.token };
+}
+/** account 权限操作注册端点（固定路径） */
+const PERMISSION_OPERATION_REGISTER_PATH = '/permission/operation/register';
+/**
+ * 框架内置 account HTTP 客户端：`POST /permission/operation/register`。
+ *
+ * 成功判定与 `/gateway/verify` 同口径：HTTP ok **且** 信封 `status === 'SUCCESS'`。
+ */
+async function requestPermissionRegistration(account, body) {
+    const target = new URL(PERMISSION_OPERATION_REGISTER_PATH, account.serviceUrl);
+    const response = await fetch(target, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const payload = (await response.json().catch(() => undefined));
+    if (!response.ok || payload?.status !== 'SUCCESS') {
+        throw new SystemError('EXTERNAL_SERVICE_ERROR', { cause: response }, payload?.message ?? `权限操作注册失败（HTTP ${response.status}）`);
+    }
+}
+export function createAuthMiddleware(ctx, options = {}) {
+    const skip = options.skip ?? defaultAuthSkip;
+    const mapError = options.mapError ??
+        ((error) => UserError.is(error) || SystemError.is(error)
+            ? error
+            : new SystemError('EXTERNAL_SERVICE_ERROR', { cause: error }));
+    return {
+        name: 'auth',
+        register: (app) => {
+            const identity = readServerIdentity(app);
+            const service = identity?.service ?? '';
+            app.addHook('preValidation', async (request) => {
+                if (skip(request, ctx)) {
+                    return;
+                }
+                const account = readAccount(ctx.config);
+                // account `serviceUrl` 门槛仅作用于内置 verify：自定义 verify 不受约束，仍照常校验
+                if (!options.verify && !account?.serviceUrl) {
+                    return;
+                }
+                const { token, apiKey } = extractAuth(request, readCookieNames(ctx.config, options.cookieNames));
+                if (!token && !apiKey) {
+                    throw new UserError('INVALID_TOKEN', undefined, '缺少访问凭证');
+                }
+                const verifyInput = {
+                    token,
+                    apiKey,
+                    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 = options.verify
+                        ? await options.verify(verifyInput, ctx)
+                        : await defaultVerify(verifyInput, account);
+                    request.user = result.user;
+                    request.token = result.token;
+                }
+                catch (error) {
+                    throw mapError(error);
+                }
+            });
+            if (options.registerPermissions === false) {
+                return;
+            }
+            app.addHook('onReady', async () => {
+                let account;
+                try {
+                    account = readAccount(ctx.config);
+                }
+                catch (error) {
+                    if (SystemError.is(error) && error.type === 'CONFIG_UNAVAILABLE') {
+                        // 出 spec 路径（generateOpenApi 不跑 config 槽位）：配置不可用 → 跳过自注册
+                        return;
+                    }
+                    ctx.log.error({ error }, '[PermissionOperation][auth] read account config failed');
+                    return;
+                }
+                // 未配置 account `serviceUrl`（含 account 自身）→ 不注册
+                if (!account?.serviceUrl) {
+                    return;
+                }
+                try {
+                    const operations = toPermissionOperations(readRegisteredOperations(app));
+                    if (operations.length === 0) {
+                        return;
+                    }
+                    await requestPermissionRegistration(account, {
+                        service,
+                        version: identity?.version ?? '',
+                        operations,
+                    });
+                }
+                catch (error) {
+                    // 失败不致命：只记日志、继续启动（不得抛错中断）
+                    ctx.log.error({ error }, '[PermissionOperation][auth] self-registration failed');
+                }
+            });
+        },
+    };
+}

package/output/app/middleware/context.d.ts

@@ -0,0 +1,13 @@
+import type { MiddlewareUnit } from '../types.js';
+/**
+ * 标准中间件单元 `context`（可替换）。
+ *
+ * `decorateRequest(decorateAs, ...)`（默认 `'ctx'`），消费既有 `context/createContext`。
+ * 装饰必须在 `ready()` 之前注册（`register` 期完成）。
+ */
+export interface ContextMiddlewareOptions {
+    /** 默认 `'ctx'` */
+    decorateAs?: string;
+}
+export declare function createContextMiddleware(options?: ContextMiddlewareOptions): MiddlewareUnit;
+//# sourceMappingURL=context.d.ts.map

package/output/app/middleware/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../source/app/middleware/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;GAKG;AAEH,MAAM,WAAW,wBAAwB;IACvC,iBAAiB;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,cAAc,CAa9F"}

package/output/app/middleware/context.js

@@ -0,0 +1,15 @@
+import { createContext } from '../../context/index.js';
+export function createContextMiddleware(options = {}) {
+    const decorateAs = options.decorateAs ?? 'ctx';
+    return {
+        name: 'context',
+        register: (app) => {
+            app.decorateRequest(decorateAs, null);
+            app.addHook('onRequest', (request, _reply, done) => {
+                ;
+                request[decorateAs] = createContext(request);
+                done();
+            });
+        },
+    };
+}

package/output/app/middleware/cors.d.ts

@@ -0,0 +1,14 @@
+import type { MiddlewareContext, MiddlewareUnit } from '../types.js';
+/**
+ * 标准中间件单元 `cors`（可替换）。
+ *
+ * 不传 `origins` → **每次请求现读**配置的 `cors` 键（配置加载后即生效，不得缓存）；
+ * **未配置即放行任意源 + 首次请求 warn 一次**（对齐四家现状）。构造期**不读配置**，
+ * 故出 spec 路径（配置不可用）不受影响。
+ */
+export interface CorsMiddlewareOptions {
+    origins?: string[] | '*';
+    credentials?: boolean;
+}
+export declare function createCorsMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>, options?: CorsMiddlewareOptions): MiddlewareUnit;
+//# sourceMappingURL=cors.d.ts.map

package/output/app/middleware/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../../source/app/middleware/cors.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEpE;;;;;;GAMG;AAEH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAOD,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,qBAA0B,GAAG,cAAc,CA6BhJ"}

package/output/app/middleware/cors.js

@@ -0,0 +1,30 @@
+import cors from '@fastify/cors';
+import { readConfigKey } from '../context.js';
+export function createCorsMiddleware(ctx, options = {}) {
+    return {
+        name: 'cors',
+        register: async (app) => {
+            let warned = false;
+            // 请求期现读：`cors` 配置变化立即生效；构造期不读
+            const resolveOrigins = () => {
+                const configured = readConfigKey(ctx.config, 'cors');
+                return options.origins ?? (configured?.enabled ? configured.origins : undefined);
+            };
+            await app.register(cors, {
+                origin: (origin, callback) => {
+                    const origins = resolveOrigins();
+                    if (origins === undefined || origins === '*') {
+                        if (!warned) {
+                            warned = true;
+                            ctx.log.warn({}, '[middleware] cors origins not configured; allowing any origin');
+                        }
+                        callback(null, true);
+                        return;
+                    }
+                    callback(null, origins.includes(origin ?? ''));
+                },
+                credentials: options.credentials ?? true,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { MiddlewareContext, MiddlewareUnit } from '../types.js';
+export { createCorsMiddleware } from './cors.js';
+export { createContextMiddleware } from './context.js';
+export { createAuthMiddleware, defaultAuthSkip } from './auth.js';
+export { createRateLimitMiddleware } from './rate-limit.js';
+export type { CorsMiddlewareOptions } from './cors.js';
+export type { ContextMiddlewareOptions } from './context.js';
+export type { AccountIntegrationConfig, AuthMiddlewareOptions, AuthSkip, AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult, } from './auth.js';
+export type { RateLimitMiddlewareOptions } from './rate-limit.js';
+/**
+ * 默认中间件预设：`[cors, context, auth]`。
+ *
+ * 顺序 `cors → context → auth` 只是**预设内容**，不是框架常量：可 `...defaultMiddlewares(ctx)`
+ * 后替换 / 插入 / 删除任意项。`rateLimit` **不在**预设内（唯一一个默认不装的项）。
+ */
+export declare function defaultMiddlewares<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>): MiddlewareUnit[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../source/app/middleware/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAE3D,YAAY,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AACtD,YAAY,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AAC5D,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,QAAQ,EACR,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AAEjE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACzD,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC3B,cAAc,EAAE,CAElB"}

package/output/app/middleware/index.js

@@ -0,0 +1,16 @@
+import { createAuthMiddleware } from './auth.js';
+import { createContextMiddleware } from './context.js';
+import { createCorsMiddleware } from './cors.js';
+export { createCorsMiddleware } from './cors.js';
+export { createContextMiddleware } from './context.js';
+export { createAuthMiddleware, defaultAuthSkip } from './auth.js';
+export { createRateLimitMiddleware } from './rate-limit.js';
+/**
+ * 默认中间件预设：`[cors, context, auth]`。
+ *
+ * 顺序 `cors → context → auth` 只是**预设内容**，不是框架常量：可 `...defaultMiddlewares(ctx)`
+ * 后替换 / 插入 / 删除任意项。`rateLimit` **不在**预设内（唯一一个默认不装的项）。
+ */
+export function defaultMiddlewares(ctx) {
+    return [createCorsMiddleware(ctx), createContextMiddleware(), createAuthMiddleware(ctx)];
+}