create-windy 0.3.19 → 0.4.0

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,
   };

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

@@ -11,6 +11,7 @@ import type {
   ModuleDurableHandlerContext,
 } from "@southwind-ai/server-sdk";
 import { ModuleBackgroundAiError } from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
 import {
   captureAuthorizationScope,
   hashAuthorizationScope,
@@ -48,6 +49,7 @@ export function createModuleDurableContextualizer(
     claim: {
       job: {
         id: string;
+        handlerKey: string;
         requestedBy: string;
         authorizationScope?: AuthorizationScopeSnapshot;
       };
@@ -76,6 +78,39 @@ export function createModuleDurableContextualizer(
       request,
       actor,
     );
+    const binding = services.hosts.durableHandlerOf(
+      input.moduleName,
+      input.claim.job.handlerKey,
+    );
+    if (!binding) {
+      throw denied("MODULE_DURABLE_CAPABILITY_MISSING", {
+        handlerKey: input.claim.job.handlerKey,
+        moduleName: input.moduleName,
+      });
+    }
+    const feature = services.hosts
+      .manifestOf(input.moduleName)
+      .features.find(({ key }) => key === binding.featureKey);
+    if (!feature) {
+      throw denied("MODULE_DURABLE_CAPABILITY_MISSING", {
+        featureKey: binding.featureKey,
+        handlerKey: binding.key,
+        moduleName: input.moduleName,
+      });
+    }
+    const access = await evaluateAccessGuards(services.runtime, guardContext, {
+      permission: { permissionKey: binding.permissionKey },
+      feature,
+    });
+    if (!access.decision.allowed) {
+      throw denied("MODULE_DURABLE_GUARD_DENIED", {
+        auditAction: binding.auditAction,
+        featureKey: binding.featureKey,
+        handlerKey: binding.key,
+        permissionKey: binding.permissionKey,
+        reason: access.decision.reason,
+      });
+    }
     const storage = services.storage
       ? createModuleStoragePort(
           services.storage,
@@ -121,6 +156,11 @@ function unavailableBackgroundAi(moduleName: string): ModuleBackgroundAiPort {
   };
 }
 
-function denied(code: string) {
-  return new DurableHandlerError(code, "模块后台任务授权已失效", false);
+function denied(code: string, details?: Record<string, unknown>) {
+  return new DurableHandlerError(
+    code,
+    "模块后台任务授权已失效",
+    false,
+    details,
+  );
 }

package/template/apps/server/src/module-host/durable-handler-registration.ts

@@ -4,30 +4,39 @@ import {
   type DurableHandlerDefinition,
   type DurableHandlerRegistry,
 } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
 import type {
   ModuleDurableHandlerContext,
   ModuleDurableHandlerDefinition,
 } from "@southwind-ai/server-sdk";
 import { ModuleBackgroundAiError } from "@southwind-ai/server-sdk";
+import type { RegisteredModuleDurableHandler } from "./initialize-contracts.js";
 
 export interface DurableHandlerRegistrationState {
   readonly handlerKeys: Set<string>;
   readonly handlerInstallers: Array<(registry: DurableHandlerRegistry) => void>;
+  readonly durableHandlers: RegisteredModuleDurableHandler[];
 }
 
 export function registerModuleDurableHandler<T>(
-  moduleName: string,
+  manifest: ModuleManifest,
   state: DurableHandlerRegistrationState,
   definition: ModuleDurableHandlerDefinition<T>,
 ) {
-  if (state.handlerKeys.has(definition.key)) {
-    throw new Error(`任务 handler 重复注册：${definition.key}`);
+  const moduleName = manifest.name;
+  const binding = durableHandlerBinding(definition);
+  validateDurableHandlerCapability(manifest, binding);
+  if (state.handlerKeys.has(binding.key)) {
+    throw new Error(`任务 handler 重复注册：${binding.key}`);
   }
-  state.handlerKeys.add(definition.key);
+  state.handlerKeys.add(binding.key);
+  state.durableHandlers.push(
+    Object.freeze({ moduleName, definition: binding }),
+  );
   state.handlerInstallers.push((registry) => {
     registry.register(
       {
-        key: definition.key,
+        key: binding.key,
         payload: definition.payload,
         async execute(payload, context) {
           try {
@@ -52,6 +61,88 @@ export function registerModuleDurableHandler<T>(
   });
 }
 
+function validateDurableHandlerCapability(
+  manifest: ModuleManifest,
+  definition: DurableHandlerBinding,
+): void {
+  if (!manifest.features.some(({ key }) => key === definition.featureKey)) {
+    throw new Error(
+      `任务 handler Feature 未在 Manifest 注册：${definition.featureKey}`,
+    );
+  }
+  if (
+    !manifest.permissions.some(({ key }) => key === definition.permissionKey)
+  ) {
+    throw new Error(
+      `任务 handler Permission 未在 Manifest 注册：${definition.permissionKey}`,
+    );
+  }
+  if (
+    !manifest.auditActions.some((action) =>
+      typeof action === "string"
+        ? action === definition.auditAction
+        : action.key === definition.auditAction,
+    )
+  ) {
+    throw new Error(
+      `任务 handler Audit Action 未在 Manifest 注册：${definition.auditAction}`,
+    );
+  }
+  if (
+    !manifestCapabilities(manifest).some((capability) =>
+      sameCapability(capability, definition),
+    )
+  ) {
+    throw new Error(
+      `任务 handler 未绑定 Manifest 已声明能力：${definition.key}`,
+    );
+  }
+}
+
+interface ManifestCapability {
+  readonly featureKey?: string;
+  readonly permissionKey: string;
+  readonly auditAction?: string;
+}
+
+type DurableHandlerBinding = Pick<
+  ModuleDurableHandlerDefinition<unknown>,
+  "key" | "featureKey" | "permissionKey" | "auditAction"
+>;
+
+function durableHandlerBinding(
+  definition: DurableHandlerBinding,
+): DurableHandlerBinding {
+  return Object.freeze({
+    key: definition.key,
+    featureKey: definition.featureKey,
+    permissionKey: definition.permissionKey,
+    auditAction: definition.auditAction,
+  });
+}
+
+function manifestCapabilities(
+  manifest: ModuleManifest,
+): readonly ManifestCapability[] {
+  return [
+    ...manifest.apiPermissions,
+    ...manifest.tasks,
+    ...manifest.tools,
+    ...(manifest.aiOperations ?? []),
+  ];
+}
+
+function sameCapability(
+  registered: ManifestCapability,
+  definition: DurableHandlerBinding,
+): boolean {
+  return (
+    registered.featureKey === definition.featureKey &&
+    registered.permissionKey === definition.permissionKey &&
+    registered.auditAction === definition.auditAction
+  );
+}
+
 function requireModuleDurableContext(
   context: Parameters<DurableHandlerDefinition<unknown>["execute"]>[1],
   moduleName: string,