create-windy 0.3.18 → 0.4.0

package/template/apps/server/src/license/routes-offline-code.test.ts

@@ -42,7 +42,7 @@ describe("客户 License 离线激活码路由", () => {
         requestId: "request_1",
       },
     }));
-    registerPlatformLicenseRoutes(app, runtime);
+    registerPlatformLicenseRoutes(app, runtime, allowRoutes);
 
     const accepted = await app.handle(post({ activationCode }));
     expect(accepted.status).toBe(200);
@@ -150,10 +150,14 @@ function createApp(runtime: PlatformLicenseRuntime) {
       requestId: "request_1",
     },
   }));
-  registerPlatformLicenseRoutes(app, runtime);
+  registerPlatformLicenseRoutes(app, runtime, allowRoutes);
   return app;
 }
 
+const allowRoutes = {
+  authorize: async () => undefined,
+};
+
 function fixedLicense(): SignedLicenseV1 {
   return {
     formatVersion: 1,

package/template/apps/server/src/license/routes.ts

@@ -1,6 +1,7 @@
 import type { RequestGuardContext } from "../guards.js";
 import type { RouteApp } from "../system/routes.js";
 import type { PlatformLicenseRuntime } from "./runtime-service.js";
+import type { StaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
 import {
   boundedJsonBodyErrorResponse,
   decodeOfflineActivationCode,
@@ -17,10 +18,18 @@ interface LicenseRouteContext {
 export function registerPlatformLicenseRoutes(
   app: Pick<RouteApp, "get" | "post">,
   licenseRuntime: PlatformLicenseRuntime,
+  authorizer: StaticRouteAuthorizer,
 ) {
   app.get("/license/runtime", async (rawContext) => {
     const context = rawContext as LicenseRouteContext;
     if (context.guardContext.actor.type !== "user") return unauthorized();
+    const denied = await authorizer.authorize(
+      context.guardContext,
+      "GET",
+      "/api/license/runtime",
+      { restrictedModeAccess: "admin-admission" },
+    );
+    if (denied) return denied;
     return licenseRuntime.snapshotForActor(context.guardContext.actor);
   });
 
@@ -29,6 +38,13 @@ export function registerPlatformLicenseRoutes(
     async (rawContext) => {
       const context = rawContext as LicenseRouteContext;
       if (context.guardContext.actor.type !== "user") return unauthorized();
+      const denied = await authorizer.authorize(
+        context.guardContext,
+        "POST",
+        "/api/license/runtime/install",
+        { restrictedModeAccess: "admin-admission" },
+      );
+      if (denied) return denied;
       let rawLicense: string;
       try {
         rawLicense = readInstallCandidate(
@@ -82,6 +98,10 @@ export function registerPlatformLicenseRoutes(
   return app;
 }
 
+function unauthorized(): Response {
+  return Response.json({ error: "UNAUTHORIZED" }, { status: 401 });
+}
+
 function readInstallCandidate(body: unknown): string {
   if (!body || typeof body !== "object" || Array.isArray(body)) return "";
   const record = body as Record<string, unknown>;
@@ -95,7 +115,3 @@ function readInstallCandidate(body: unknown): string {
     ? record.license
     : "";
 }
-
-function unauthorized(): Response {
-  return Response.json({ error: "UNAUTHORIZED" }, { status: 401 });
-}

package/template/apps/server/src/license/runtime-service.test.ts

@@ -33,6 +33,7 @@ import {
   requestStatus as status,
 } from "./runtime-service-test-http.js";
 import { buildScopeContext } from "../data-access/context.js";
+import { createStaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
 
 const NOW = new Date("2026-08-01T00:00:00.000Z");
 
@@ -240,6 +241,7 @@ function createFixture(
     {
       actorResolver: { resolve: (current) => actorFrom(current) },
       licenseResolver: licenseRuntime,
+      featureCatalog: snapshot.features,
       featureResolver: {
         resolve: (key) => ({ key, enabled: true, visible: "visible" }),
       },
@@ -258,15 +260,18 @@ function createFixture(
       }
     })
     .get("/health", () => ({ status: "ok" }));
-  registerPlatformLicenseRoutes(app, licenseRuntime);
+  const modules = loadSystemModules();
+  const routeAuthorizer = createStaticRouteAuthorizer(runtime, modules);
+  registerPlatformLicenseRoutes(app, licenseRuntime, routeAuthorizer);
   registerSystemRoutes(app, repositories, runtime, snapshot.features);
   registerAgentRoutes(
     app,
     new GovernedToolRegistry(
-      loadSystemModules(),
+      modules,
       createSystemToolHandlers(repositories, runtime),
       runtime,
     ),
+    routeAuthorizer,
   );
   return { app, runtime, licenseRuntime };
 }
@@ -283,6 +288,9 @@ function actorFrom(current: Request) {
     permissionKeys: [
       "system.user.read",
       "system.audit.read",
+      "system.agent.read",
+      "system.license.read",
+      "system.license.manage",
       "system.menu.read",
     ],
     scopeContext: buildScopeContext("user_1", undefined, [

package/template/apps/server/src/module-bootstrap.ts

@@ -1,20 +1,13 @@
 import type { PlatformConfig } from "@southwind-ai/config";
+import type { ModuleUploadPolicy } from "@southwind-ai/server-sdk";
 // @windy-module system.configuration begin
 import { bootstrapModuleConfiguration } from "./configuration/bootstrap.js";
 // @windy-module system.configuration end
-import {
-  createFoundationSnapshot,
-  loadFoundationModules,
-} from "./foundation.js";
+import { createFoundationSnapshot } from "./foundation.js";
 import { runInstalledModuleMigrations } from "./module-migrations.js";
-import {
-  attachInstalledBusinessModules,
-  installedBusinessModules,
-} from "./installed-business-modules.js";
-import {
-  initializeModuleHosts,
-  synchronizeModuleRolePresets,
-} from "./module-host.js";
+import { attachRuntimeBusinessModules } from "./module-host/runtime-composition.js";
+import { synchronizeModuleRolePresets } from "./module-host.js";
+import { prepareInstalledServerModules } from "./module-preflight.js";
 import type { ServerPersistence } from "./persistence.js";
 // @windy-module system.storage begin
 import { createPlatformUploadPolicies } from "./storage/runtime.js";
@@ -27,8 +20,15 @@ import {
 export async function bootstrapServerModules(
   platformConfig: PlatformConfig,
   persistence: ServerPersistence | undefined,
+  prepared?: Awaited<ReturnType<typeof prepareInstalledServerModules>>,
 ) {
-  const foundationModules = loadFoundationModules();
+  const baseUploadPolicies: ModuleUploadPolicy[] = [
+    // @windy-module system.storage begin
+    ...createPlatformUploadPolicies(platformConfig),
+    // @windy-module system.storage end
+  ];
+  const { foundationModules, moduleHosts } =
+    prepared ?? (await prepareInstalledServerModules(baseUploadPolicies));
   const foundationSnapshot = createFoundationSnapshot(
     platformConfig,
     foundationModules,
@@ -46,15 +46,6 @@ export async function bootstrapServerModules(
   // @windy-module system.configuration begin
   configurationRuntime.bindFoundation(foundationSnapshot);
   // @windy-module system.configuration end
-  const moduleHosts = await initializeModuleHosts({
-    modules: foundationModules,
-    installations: installedBusinessModules,
-    baseUploadPolicies: [
-      // @windy-module system.storage begin
-      ...createPlatformUploadPolicies(platformConfig),
-      // @windy-module system.storage end
-    ],
-  });
   const systemRepositories = createSystemRepositories(foundationSnapshot, {
     db: persistence?.db,
   });
@@ -74,7 +65,7 @@ export async function bootstrapServerModules(
     foundationSnapshot,
     moduleHosts.rolePresets,
   );
-  attachInstalledBusinessModules({
+  await attachRuntimeBusinessModules({
     db: persistence?.db,
     departments: systemRepositories.departments,
   });

package/template/apps/server/src/module-composition.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
 import { Elysia } from "elysia";
 import { validateServerModuleComposition } from "./module-composition.js";
 
@@ -83,6 +84,35 @@ describe("Server Module Composition", () => {
       "AI Operation Handler已注册但未在 Manifest 声明：system.unknown-operation",
     );
   });
+
+  test("平台静态 HTTP Route 也必须在 Manifest 声明", () => {
+    expect(() =>
+      validateServerModuleComposition({
+        modules: [fixture()],
+        routes: [
+          {
+            method: "POST",
+            path: "/api/auth/users/:id/password",
+          },
+          { method: "GET", path: "/api/demo/ghost" },
+        ],
+      }),
+    ).toThrow("HTTP Route 已注册但未在 Manifest 声明：GET /api/demo/ghost");
+
+    expect(() =>
+      validateServerModuleComposition({
+        modules: [fixture()],
+        routes: [
+          {
+            method: "POST",
+            path: "/api/auth/users/:id/password",
+          },
+          { method: "GET", path: "/api/openapi.json" },
+        ],
+        frameworkRoutes: ["GET /api/openapi.json"],
+      }),
+    ).not.toThrow();
+  });
 });
 
 function fixture(): ModuleManifest {
@@ -110,14 +140,25 @@ function fixture(): ModuleManifest {
         method: "POST",
         path: "/api/auth/users/:id/password",
         permissionKey: "system.auth.manage",
+        featureKey: "system.auth",
+        auditAction: "auth.password.update",
+      },
+    ],
+    features: [
+      {
+        key: featureKey("system.auth"),
+        label: "账号认证",
+        module: "system",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
       },
     ],
-    features: [],
     migrations: [],
     schemaExports: [],
     tasks: [],
     tools: [],
     providers: [],
-    auditActions: [],
+    auditActions: ["auth.password.update"],
   };
 }

package/template/apps/server/src/module-composition.ts

@@ -23,6 +23,11 @@ export interface ModuleImplementationRegistrations {
 export interface ServerCompositionInput {
   modules: readonly ModuleManifest[];
   routes: readonly RegisteredHttpRoute[];
+  /**
+   * 仅用于框架生成且不属于产品 API 的路由，例如 OpenAPI 文档。
+   * 产品、运维、认证与恢复入口仍必须进入 Manifest。
+   */
+  frameworkRoutes?: readonly string[];
   tasks?: readonly { key: string }[];
   tools?: ReadonlyMap<string, unknown>;
   aiOperations?: readonly string[];
@@ -33,6 +38,11 @@ export interface ServerCompositionInput {
 export function validateServerModuleComposition(
   input: ServerCompositionInput,
 ): void {
+  validateHttpRouteRegistration(
+    input.modules,
+    input.routes.map(apiRouteKey),
+    input.frameworkRoutes ?? [],
+  );
   validateModuleComposition(input.modules, {
     apiRoutes: input.routes.map(apiRouteKey),
     tasks: (input.tasks || []).map(({ key }) => key),
@@ -45,6 +55,25 @@ export function validateServerModuleComposition(
   }
 }
 
+function validateHttpRouteRegistration(
+  modules: readonly ModuleManifest[],
+  registeredRoutes: readonly string[],
+  frameworkRoutes: readonly string[],
+): void {
+  const declared = new Set(
+    modules.flatMap((module) => module.apiPermissions.map(apiRouteKey)),
+  );
+  const exemptions = new Set(frameworkRoutes);
+  const unknown = registeredRoutes.filter(
+    (route) => !declared.has(route) && !exemptions.has(route),
+  );
+  if (unknown.length) {
+    throw new Error(
+      `HTTP Route 已注册但未在 Manifest 声明：${[...new Set(unknown)].join("、")}`,
+    );
+  }
+}
+
 function validateRegistrationConsistency(
   modules: readonly ModuleManifest[],
   registrations: ModuleImplementationRegistrations,

package/template/apps/server/src/module-host/durable-context-guard.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, test } from "bun:test";
+import type { DurableHandlerContext } from "@southwind-ai/jobs";
+import { featureKey } from "@southwind-ai/shared";
+import { buildActorScopeContexts } from "../data-access/context.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { createModuleDurableContextualizer } from "./durable-context.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+const feature = {
+  key: featureKey("evidence.catalog"),
+  label: "电子物证",
+  module: "evidence",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+const moduleManifest = manifest("evidence", {
+  features: [feature],
+  permissions: [
+    {
+      key: "evidence.read",
+      label: "读取物证",
+      module: "evidence",
+      moduleLabel: "物证",
+      resource: "file",
+      resourceLabel: "文件",
+      action: "read",
+    },
+  ],
+  tasks: [
+    {
+      key: "evidence.refresh",
+      label: "刷新物证",
+      description: "刷新物证目录。",
+      permissionKey: "evidence.read",
+      featureKey: "evidence.catalog",
+      auditAction: "evidence.file.read",
+      intervalSeconds: 60,
+      maxAttempts: 3,
+      retryDelaySeconds: 5,
+    },
+  ],
+  auditActions: ["evidence.file.read"],
+});
+
+describe("模块 Durable Handler 逐次 Guard", () => {
+  test("重试与恢复会重新读取当前 Feature 和 License 状态", async () => {
+    let featureEnabled = true;
+    const featureChanged = await fixture({
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: featureEnabled,
+          visible: "visible",
+        }),
+      },
+    });
+    const persistedJob = job(featureChanged.actor);
+    await featureChanged.contextualize({
+      claim: { job: persistedJob },
+      moduleName: "evidence",
+      context: baseContext(1),
+    });
+    featureEnabled = false;
+    await expect(
+      featureChanged.contextualize({
+        claim: { job: persistedJob },
+        moduleName: "evidence",
+        context: baseContext(2),
+      }),
+    ).rejects.toMatchObject({
+      code: "MODULE_DURABLE_GUARD_DENIED",
+      details: { reason: "feature-disabled" },
+    });
+
+    const restricted = await fixture({
+      licenseEnforced: true,
+      licenseResolver: {
+        resolve: () => ({ restricted: true, status: "invalid" }),
+      },
+    });
+    await expect(
+      restricted.contextualize({
+        claim: { job: job(restricted.actor) },
+        moduleName: "evidence",
+        context: baseContext(3),
+      }),
+    ).rejects.toMatchObject({
+      code: "MODULE_DURABLE_GUARD_DENIED",
+      details: { reason: "license-restricted" },
+    });
+  });
+});
+
+async function fixture(
+  runtimeOptions: NonNullable<Parameters<typeof createServerRuntime>[1]>,
+) {
+  const hosts = await initializeModuleHosts({
+    modules: [moduleManifest],
+    installations: [
+      {
+        manifest: moduleManifest,
+        setup(host) {
+          host.registerDurableHandler({
+            key: "evidence.refresh",
+            featureKey: "evidence.catalog",
+            permissionKey: "evidence.read",
+            auditAction: "evidence.file.read",
+            payload: { parse: () => ({}) },
+            execute: () => undefined,
+          });
+        },
+      },
+    ],
+  });
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    { ...runtimeOptions, featureCatalog: [feature] },
+  );
+  const actor = currentActor();
+  return {
+    actor,
+    contextualize: createModuleDurableContextualizer({
+      hosts,
+      runtime,
+      features: [feature],
+      resolveActor: async () => actor,
+    }),
+  };
+}
+
+function currentActor(): RequestActor {
+  return {
+    id: "user-reader",
+    type: "user",
+    name: "物证读取者",
+    roleCodes: ["investigator"],
+    permissionKeys: ["evidence.read"],
+    ...buildActorScopeContexts("user-reader", "dept-case", [
+      {
+        id: "role-investigator",
+        code: "investigator",
+        dataScope: "all",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function job(actor: RequestActor) {
+  return {
+    id: "job-evidence",
+    handlerKey: "evidence.refresh",
+    requestedBy: actor.id,
+    authorizationScope: captureAuthorizationScope(actor.scopeContext).snapshot,
+  };
+}
+
+function baseContext(attemptNumber: number): DurableHandlerContext {
+  return {
+    jobId: "job-evidence",
+    stageKey: "main",
+    attemptNumber,
+    signal: new AbortController().signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => undefined,
+  };
+}

package/template/apps/server/src/module-host/durable-context-unavailable.test.ts

@@ -6,6 +6,8 @@ import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
 import type { RequestActor } from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
 import { createModuleDurableContextualizer } from "./durable-context.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
 
 const feature = {
   key: featureKey("evidence.catalog"),
@@ -19,8 +21,54 @@ const feature = {
 describe("模块 Durable Handler 可选端口", () => {
   test("未挂载 Storage 时仍重建 Actor，并对文件读取 fail-closed", async () => {
     const actor = currentActor();
+    const moduleManifest = manifest("evidence", {
+      features: [feature],
+      permissions: [
+        {
+          key: "evidence.read",
+          label: "读取物证",
+          module: "evidence",
+          moduleLabel: "物证",
+          resource: "file",
+          resourceLabel: "文件",
+          action: "read",
+        },
+      ],
+      tasks: [
+        {
+          key: "evidence.refresh",
+          label: "刷新物证",
+          description: "刷新物证目录。",
+          permissionKey: "evidence.read",
+          featureKey: "evidence.catalog",
+          auditAction: "evidence.file.read",
+          intervalSeconds: 60,
+          maxAttempts: 3,
+          retryDelaySeconds: 5,
+        },
+      ],
+      auditActions: ["evidence.file.read"],
+    });
+    const hosts = await initializeModuleHosts({
+      modules: [moduleManifest],
+      installations: [
+        {
+          manifest: moduleManifest,
+          setup(host) {
+            host.registerDurableHandler({
+              key: "evidence.refresh",
+              featureKey: "evidence.catalog",
+              permissionKey: "evidence.read",
+              auditAction: "evidence.file.read",
+              payload: { parse: () => ({}) },
+              execute: () => undefined,
+            });
+          },
+        },
+      ],
+    });
     const contextualize = createModuleDurableContextualizer({
-      hosts: {} as never,
+      hosts,
       runtime: createServerRuntime(
         { NODE_ENV: "test" },
         { featureCatalog: [feature] },
@@ -66,6 +114,7 @@ function currentActor(): RequestActor {
 function job(actor: RequestActor) {
   return {
     id: "job-evidence",
+    handlerKey: "evidence.refresh",
     requestedBy: actor.id,
     authorizationScope: captureAuthorizationScope(actor.scopeContext).snapshot,
   };

package/template/apps/server/src/module-host/durable-context.test.ts

@@ -34,6 +34,19 @@ const evidenceManifest = manifest("evidence", {
     },
   ],
   auditActions: ["evidence.file.read"],
+  tasks: [
+    {
+      key: "evidence.refresh",
+      label: "刷新物证",
+      description: "刷新物证目录。",
+      permissionKey: "evidence.read",
+      featureKey: "evidence.catalog",
+      auditAction: "evidence.file.read",
+      intervalSeconds: 60,
+      maxAttempts: 3,
+      retryDelaySeconds: 5,
+    },
+  ],
 });
 
 describe("模块 Durable Handler 授权上下文", () => {
@@ -137,7 +150,7 @@ describe("模块 Durable Handler 授权上下文", () => {
   // @windy-module system.storage end
 
   // @windy-module system.storage begin
-  test("Scope 变化、权限撤销与资源绑定漂移均 fail-closed", async () => {
+  test("Scope 变化与权限撤销均在执行前 fail-closed", async () => {
     const stable = currentActor();
     const scopeChanged = currentActor("self");
     const setupScopeChanged = await setup(() => scopeChanged);
@@ -152,37 +165,32 @@ describe("模块 Durable Handler 授权上下文", () => {
       retryable: false,
     });
 
-    const permissionRevoked = { ...stable, permissionKeys: [] };
-    const revoked = await setup(() => permissionRevoked);
-    const file = await seedFile(revoked.storage);
-    const context = await revoked.contextualize({
-      claim: { job: job(stable) },
+    let permissionGranted = true;
+    const revoked = await setup(() => ({
+      ...stable,
+      permissionKeys: permissionGranted ? ["evidence.read"] : [],
+    }));
+    const persistedJob = job(stable);
+    await revoked.contextualize({
+      claim: { job: persistedJob },
       moduleName: "evidence",
       context: baseContext(1),
     });
-    const storage = (
-      context as typeof context & {
-        storage: {
-          openResourceFile(input: {
-            fileId: string;
-            purpose: string;
-            resourceType: string;
-            resourceId: string;
-          }): Promise<unknown>;
-        };
-      }
-    ).storage;
+    permissionGranted = false;
     await expect(
-      storage.openResourceFile({
-        fileId: file.id,
-        purpose: "evidence.raw",
-        resourceType: "evidence.evidence-file",
-        resourceId: "evidence-1",
+      revoked.contextualize({
+        claim: { job: persistedJob },
+        moduleName: "evidence",
+        context: baseContext(2),
       }),
-    ).rejects.toThrow("资源文件访问未授权");
+    ).rejects.toMatchObject({
+      code: "MODULE_DURABLE_GUARD_DENIED",
+      retryable: false,
+      details: { reason: "missing-permission" },
+    });
     expect(revoked.runtime.auditSink.list()).toContainEqual(
       expect.objectContaining({
-        action: "evidence.file.read",
+        action: "security.denied",
         outcome: "denied",
       }),
     );
@@ -222,6 +230,14 @@ async function setup(
                 context.actor.id === "user-reader",
             },
           ]);
+          host.registerDurableHandler({
+            key: "evidence.refresh",
+            featureKey: "evidence.catalog",
+            permissionKey: "evidence.read",
+            auditAction: "evidence.file.read",
+            payload: { parse: () => ({}) },
+            execute: () => undefined,
+          });
         },
       },
     ],
@@ -278,6 +294,7 @@ function currentActor(scope: "all" | "self" = "all"): RequestActor {
 function job(actor: RequestActor) {
   return {
     id: "job-evidence",
+    handlerKey: "evidence.refresh",
     requestedBy: actor.id,
     authorizationScope: captureAuthorizationScope(actor.scopeContext).snapshot,
   };