create-windy 0.3.18 → 0.4.0

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,

package/template/apps/server/src/module-host/implementation-completeness.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleHost } from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import { initializeModuleHosts } from "./initialize.js";
+import {
+  governedResourceRouteKeys,
+  validateHostedModuleImplementations,
+} from "./implementation-completeness.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("Server Module 实现完整性", () => {
+  test("Manifest 声明的 API、任务和 Provider 必须由同一安装单元实现", async () => {
+    const complete = completeRouteModule();
+    const completeHosts = await initializeModuleHosts({
+      modules: [complete.manifest],
+      installations: [complete],
+    });
+
+    expect(() =>
+      validateHostedModuleImplementations([complete], completeHosts),
+    ).not.toThrow();
+
+    const incomplete = {
+      manifest: complete.manifest,
+      setup() {},
+    };
+    const incompleteHosts = await initializeModuleHosts({
+      modules: [incomplete.manifest],
+      installations: [incomplete],
+    });
+
+    expect(() =>
+      validateHostedModuleImplementations([incomplete], incompleteHosts),
+    ).toThrow("API Route GET /api/catalog/items 缺少 Handler");
+  });
+
+  test("治理资源注册派生读取、明文和四个导出 Handler Key", () => {
+    expect(
+      governedResourceRouteKeys({
+        readPath: "/api/people/persons/:id",
+        revealPath: "/api/people/persons/:id/plaintext",
+        export: {
+          basePath: "/api/people/persons/exports",
+          validateQuery: () => ({}),
+          readPage: () => ({ records: [] }),
+        },
+      }),
+    ).toEqual([
+      "GET /api/people/persons/:id",
+      "POST /api/people/persons/:id/plaintext",
+      "POST /api/people/persons/exports",
+      "GET /api/people/persons/exports/:id",
+      "POST /api/people/persons/exports/:id/cancel",
+      "GET /api/people/persons/exports/:id/download",
+    ]);
+  });
+
+  test("Durable Handler 的 Host 声明与 Registry 安装必须双向一致", async () => {
+    const capabilityKey = "reports.refresh";
+    const permissionKey = "reports.refresh.execute";
+    const moduleManifest = manifest("reports", {
+      features: [
+        {
+          key: featureKey(capabilityKey),
+          label: "报表刷新",
+          module: "reports",
+          visible: "visible",
+          enabled: true,
+          stage: "stable",
+        },
+      ],
+      permissions: [
+        {
+          key: permissionKey,
+          label: "执行报表刷新",
+          module: "reports",
+          moduleLabel: "报表",
+          resource: "refresh",
+          resourceLabel: "刷新",
+          action: "execute",
+        },
+      ],
+      tasks: [
+        {
+          key: capabilityKey,
+          label: "报表刷新",
+          description: "刷新报表。",
+          featureKey: capabilityKey,
+          permissionKey,
+          auditAction: permissionKey,
+          intervalSeconds: 60,
+          maxAttempts: 3,
+          retryDelaySeconds: 5,
+        },
+      ],
+      auditActions: [permissionKey],
+    });
+    const installation = {
+      manifest: moduleManifest,
+      setup(host: ModuleHost) {
+        moduleSetup(host);
+      },
+    };
+    const hosts = await initializeModuleHosts({
+      modules: [moduleManifest],
+      installations: [installation],
+    });
+
+    expect(() =>
+      validateHostedModuleImplementations([installation], hosts),
+    ).not.toThrow();
+    expect(() =>
+      validateHostedModuleImplementations([installation], {
+        ...hosts,
+        installDurableHandlers() {},
+      }),
+    ).toThrow("Durable Handler reports:reports.refresh 缺少 Handler");
+
+    function moduleSetup(host: ModuleHost) {
+      host.registerTaskHandlers([
+        { taskKey: capabilityKey, handler: () => undefined },
+      ]);
+      host.registerDurableHandler({
+        key: capabilityKey,
+        featureKey: capabilityKey,
+        permissionKey,
+        auditAction: permissionKey,
+        payload: { parse: () => ({}) },
+        execute: () => undefined,
+      });
+    }
+  });
+});
+
+function completeRouteModule() {
+  const capabilityKey = "catalog.item";
+  const permissionKey = "catalog.item.read";
+  const moduleManifest = manifest("catalog", {
+    features: [
+      {
+        key: featureKey(capabilityKey),
+        label: "目录项",
+        module: "catalog",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    permissions: [
+      {
+        key: permissionKey,
+        label: "查看目录",
+        module: "catalog",
+        moduleLabel: "目录",
+        resource: "item",
+        resourceLabel: "目录项",
+        action: "read",
+      },
+    ],
+    apiPermissions: [
+      {
+        method: "GET",
+        path: "/api/catalog/items",
+        permissionKey,
+        featureKey: capabilityKey,
+        auditAction: "data.read",
+      },
+    ],
+    auditActions: ["data.read"],
+  });
+  return {
+    manifest: moduleManifest,
+    setup(host: ModuleHost) {
+      host.registerRoutes([
+        {
+          method: "GET",
+          path: "/api/catalog/items",
+          permissionKey,
+          featureKey: capabilityKey,
+          handler: () => ({ items: [] }),
+        },
+      ]);
+    },
+  };
+}

package/template/apps/server/src/module-host/implementation-completeness.ts

@@ -0,0 +1,132 @@
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  ModuleGovernedResourceRegistration,
+} from "@southwind-ai/server-sdk";
+import type { InitializedModuleHosts } from "./initialize-contracts.js";
+
+/**
+ * 校验经 Module Host 安装的业务模块是否实现了 Manifest 中所有 Server 能力。
+ *
+ * Admin Route 页面由 Web 构建门禁校验；这里覆盖 API、任务、Tool、AI Operation
+ * 与 Provider，且只检查 Host 安装单元，不把平台静态实现伪装成业务 Handler。
+ */
+export function validateHostedModuleImplementations(
+  installations: readonly InstallableServerModule<ModuleManifest>[],
+  hosts: InitializedModuleHosts,
+): void {
+  for (const installation of installations) {
+    const moduleName = installation.manifest.name;
+    assertComplete(
+      "API Route",
+      installation.manifest.apiPermissions.map(
+        ({ method, path }) => `${method.toUpperCase()} ${path}`,
+      ),
+      hosts.routes
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(
+          ({ definition }) =>
+            `${definition.method.toUpperCase()} ${definition.path}`,
+        )
+        .concat(
+          hosts.governedResources
+            .filter((entry) => entry.moduleName === moduleName)
+            .flatMap(({ registration }) =>
+              governedResourceRouteKeys(registration),
+            ),
+        ),
+    );
+    assertComplete(
+      "定时任务",
+      installation.manifest.tasks.map(({ key }) => key),
+      hosts.taskHandlers
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ registration }) => registration.taskKey),
+    );
+    assertComplete(
+      "Agent Tool",
+      installation.manifest.tools.map(({ key }) => key),
+      [...hosts.toolHandlers, ...hosts.sandboxToolHandlers]
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ registration }) => registration.toolKey),
+    );
+    assertComplete(
+      "AI Operation",
+      (installation.manifest.aiOperations ?? []).map(({ key }) => key),
+      hosts.aiOperationHandlers
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ registration }) => registration.operationKey),
+    );
+    assertComplete(
+      "Provider",
+      installation.manifest.providers.map(({ key }) => key),
+      hosts.searchProviders
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ provider }) => provider.key),
+    );
+  }
+  validateDurableHandlerInstallations(hosts);
+}
+
+export function governedResourceRouteKeys(
+  registration: Pick<
+    ModuleGovernedResourceRegistration,
+    "readPath" | "revealPath" | "export"
+  >,
+): string[] {
+  return [
+    `GET ${registration.readPath}`,
+    `POST ${registration.revealPath}`,
+    ...(registration.export
+      ? [
+          `POST ${registration.export.basePath}`,
+          `GET ${registration.export.basePath}/:id`,
+          `POST ${registration.export.basePath}/:id/cancel`,
+          `GET ${registration.export.basePath}/:id/download`,
+        ]
+      : []),
+  ];
+}
+
+function assertComplete(
+  label: string,
+  declared: readonly string[],
+  registered: readonly string[],
+): void {
+  const implementations = new Set(registered);
+  for (const key of declared) {
+    if (!implementations.has(key)) {
+      throw new Error(`${label} ${key} 缺少 Handler`);
+    }
+  }
+}
+
+function validateDurableHandlerInstallations(
+  hosts: InitializedModuleHosts,
+): void {
+  const registry = new DurableHandlerRegistry();
+  hosts.installDurableHandlers(registry);
+  const hosted = hosts.durableHandlers.map(
+    ({ moduleName, definition }) => `${moduleName}:${definition.key}`,
+  );
+  const installed = registry.keys().map((key) => {
+    const handler = registry.get(key);
+    return `${handler?.moduleName ?? ""}:${key}`;
+  });
+  assertSameRegistrations("Durable Handler", hosted, installed);
+}
+
+function assertSameRegistrations(
+  label: string,
+  hosted: readonly string[],
+  installed: readonly string[],
+): void {
+  assertComplete(label, hosted, installed);
+  const declarations = new Set(hosted);
+  for (const key of installed) {
+    if (!declarations.has(key)) {
+      throw new Error(`${label} ${key} 未在 Host 注册`);
+    }
+  }
+}

package/template/apps/server/src/module-host/initialize-contracts.ts

@@ -3,6 +3,7 @@ import type { ModuleManifest } from "@southwind-ai/modules";
 import type {
   InstallableServerModule,
   ModuleAiOperationHandlerRegistration,
+  ModuleDurableHandlerDefinition,
   ModuleInitializer,
   ModuleGovernedResourceRegistration,
   ModuleRolePreset,
@@ -40,6 +41,14 @@ export interface RegisteredModuleAiOperationHandler {
   readonly registration: ModuleAiOperationHandlerRegistration;
 }
 
+export interface RegisteredModuleDurableHandler {
+  readonly moduleName: string;
+  readonly definition: Pick<
+    ModuleDurableHandlerDefinition<unknown>,
+    "key" | "featureKey" | "permissionKey" | "auditAction"
+  >;
+}
+
 export interface RegisteredModuleGovernedResource {
   readonly moduleName: string;
   readonly registration: ModuleGovernedResourceRegistration;
@@ -73,6 +82,7 @@ export interface InitializedModuleHosts {
   readonly toolHandlers: readonly RegisteredModuleToolHandler[];
   readonly sandboxToolHandlers: readonly RegisteredModuleSandboxToolHandler[];
   readonly aiOperationHandlers: readonly RegisteredModuleAiOperationHandler[];
+  readonly durableHandlers: readonly RegisteredModuleDurableHandler[];
   readonly governedResources: readonly RegisteredModuleGovernedResource[];
   readonly rolePresets: readonly RegisteredModuleRolePreset[];
   readonly searchProviders: readonly RegisteredModuleSearchProvider[];
@@ -83,5 +93,9 @@ export interface InitializedModuleHosts {
   resourceFileAccessPoliciesOf(
     moduleName: string,
   ): readonly ModuleResourceFileAccessPolicy[];
+  durableHandlerOf(
+    moduleName: string,
+    handlerKey: string,
+  ): RegisteredModuleDurableHandler["definition"] | undefined;
   installDurableHandlers(registry: DurableHandlerRegistry): void;
 }

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

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import { featureKey } from "@southwind-ai/shared";
 import type {
   ModuleInitializer,
   ModuleSandboxToolHost,
@@ -15,6 +16,9 @@ describe("模块 Host 初始化", () => {
       await Promise.resolve();
       host.registerDurableHandler({
         key: "alpha.refresh",
+        featureKey: "alpha.refresh",
+        permissionKey: "alpha.refresh.execute",
+        auditAction: "alpha.refresh.execute",
         payload: { parse: () => ({}) },
         execute: () => undefined,
       });
@@ -25,7 +29,7 @@ describe("模块 Host 初始化", () => {
     });
 
     const initialized = await initializeModuleHosts({
-      modules: [manifest("alpha"), manifest("beta")],
+      modules: [durableManifest("alpha"), manifest("beta")],
       initializers: [first, second],
     });
     expect(events).toEqual(["alpha:start", "alpha:end", "beta"]);
@@ -33,6 +37,13 @@ describe("模块 Host 初始化", () => {
     const registry = new DurableHandlerRegistry();
     initialized.installDurableHandlers(registry);
     expect(registry.keys()).toEqual(["alpha.refresh"]);
+    expect(
+      initialized.durableHandlerOf("alpha", "alpha.refresh"),
+    ).toMatchObject({
+      featureKey: "alpha.refresh",
+      permissionKey: "alpha.refresh.execute",
+      auditAction: "alpha.refresh.execute",
+    });
   });
 
   test("未知模块、错误命名空间和重复注册立即失败", async () => {
@@ -76,11 +87,14 @@ describe("模块 Host 初始化", () => {
 
     await expect(
       initializeModuleHosts({
-        modules: [manifest("known")],
+        modules: [durableManifest("known")],
         initializers: [
           initializer("known", (host) => {
             const definition = {
               key: "known.refresh",
+              featureKey: "known.refresh",
+              permissionKey: "known.refresh.execute",
+              auditAction: "known.refresh.execute",
               payload: { parse: () => ({}) },
               execute: () => undefined,
             };
@@ -92,6 +106,26 @@ describe("模块 Host 初始化", () => {
     ).rejects.toThrow("任务 handler 重复注册：known.refresh");
   });
 
+  test("Durable Handler 必须绑定 Manifest 已声明能力", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [durableManifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerDurableHandler({
+              key: "known.refresh",
+              featureKey: "known.missing",
+              permissionKey: "known.refresh.execute",
+              auditAction: "known.refresh.execute",
+              payload: { parse: () => ({}) },
+              execute: () => undefined,
+            });
+          }),
+        ],
+      }),
+    ).rejects.toThrow("任务 handler Feature 未在 Manifest 注册：known.missing");
+  });
+
   test("安装单元的 Manifest 必须来自同一平台能力目录", async () => {
     await expect(
       initializeModuleHosts({
@@ -238,3 +272,45 @@ function policy(purpose: string) {
     signature: "none" as const,
   };
 }
+
+function durableManifest(name: string) {
+  const capabilityKey = `${name}.refresh`;
+  const permissionKey = `${capabilityKey}.execute`;
+  return manifest(name, {
+    features: [
+      {
+        key: featureKey(capabilityKey),
+        label: "刷新",
+        module: name,
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    permissions: [
+      {
+        key: permissionKey,
+        label: "执行刷新",
+        module: name,
+        moduleLabel: name,
+        resource: "refresh",
+        resourceLabel: "刷新",
+        action: "execute",
+      },
+    ],
+    tasks: [
+      {
+        key: capabilityKey,
+        label: "刷新",
+        description: "刷新模块数据。",
+        featureKey: capabilityKey,
+        permissionKey,
+        auditAction: permissionKey,
+        intervalSeconds: 60,
+        maxAttempts: 3,
+        retryDelaySeconds: 5,
+      },
+    ],
+    auditActions: [permissionKey],
+  });
+}