create-windy 0.3.18 → 0.4.0

package/template/apps/server/src/module-host/search-provider-registration.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { validateSearchProviderRegistration } from "./search-provider-registration.js";
+
+describe("SearchProvider Host 注册", () => {
+  test("Provider 版本必须与 Manifest 一致", () => {
+    expect(() =>
+      validateSearchProviderRegistration(manifest("1", "1.0.0"), {
+        key: "known.search",
+        providerVersion: "2.0.0",
+      }),
+    ).toThrow("版本与 Manifest 不一致");
+  });
+
+  test("只接受当前支持的搜索协议", () => {
+    expect(() =>
+      validateSearchProviderRegistration(manifest("2", "1.0.0"), {
+        key: "known.search",
+        providerVersion: "1.0.0",
+      }),
+    ).toThrow("协议版本不受支持");
+  });
+});
+
+function manifest(
+  contractVersion: string,
+  providerVersion: string,
+): ModuleManifest {
+  return {
+    name: "known",
+    version: "1.0.0",
+    label: "已知模块",
+    description: "测试模块",
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [providerDefinition(contractVersion, providerVersion)],
+    auditActions: [],
+  };
+}
+
+function providerDefinition(contractVersion: string, providerVersion: string) {
+  return {
+    key: "known.search",
+    kind: "search",
+    contractVersion,
+    providerVersion,
+    label: "搜索",
+    enabledByDefault: true,
+    permissionKey: "known.item.read",
+    featureKey: "known.item",
+    deepLink: {
+      surface: "business",
+      routeTemplate: "/known/:id",
+      idParameter: "id",
+    },
+  } as unknown as ModuleManifest["providers"][number];
+}

package/template/apps/server/src/module-host/search-provider-registration.ts

@@ -0,0 +1,35 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  SEARCH_PROVIDER_CONTRACT_VERSION,
+  type SearchProviderManifestDefinition,
+} from "@southwind-ai/shared";
+
+interface SearchProviderRegistration {
+  readonly key: string;
+  readonly providerVersion: string;
+}
+
+export function validateSearchProviderRegistration(
+  manifest: ModuleManifest,
+  provider: SearchProviderRegistration,
+): void {
+  const definition = manifest.providers.find(({ key }) => key === provider.key);
+  if (!definition) {
+    throw new Error(`搜索 Provider 未在 Manifest 声明：${provider.key}`);
+  }
+  if (
+    !isSearchProviderDefinition(definition) ||
+    definition.contractVersion !== SEARCH_PROVIDER_CONTRACT_VERSION
+  ) {
+    throw new Error(`SearchProvider ${provider.key} 协议版本不受支持`);
+  }
+  if (definition.providerVersion !== provider.providerVersion) {
+    throw new Error(`SearchProvider ${provider.key} 版本与 Manifest 不一致`);
+  }
+}
+
+function isSearchProviderDefinition(
+  value: ModuleManifest["providers"][number],
+): value is SearchProviderManifestDefinition {
+  return value.kind === "search" && "providerVersion" in value;
+}

package/template/apps/server/src/module-host/static-route-authorization.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from "bun:test";
+import { systemModuleManifests } from "@southwind-ai/modules";
+import { createServerRuntime } from "../runtime.js";
+import {
+  createManifestAuthorizedRouteApp,
+  createStaticRouteAuthorizer,
+} from "./static-route-authorization.js";
+
+// @windy-module system.license begin
+test("平台静态 Route 使用 Manifest Feature 与 Permission Guard", async () => {
+  const modules = systemModuleManifests();
+  const runtime = createServerRuntime(
+    { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+    { disabledModuleNames: new Set(["system.license"]) },
+  );
+  const authorizer = createStaticRouteAuthorizer(runtime, modules);
+  const context = await runtime.createGuardContext(
+    new Request("http://localhost/api/license/runtime", {
+      headers: { authorization: "Bearer token_1" },
+    }),
+  );
+
+  const denied = await authorizer.authorize(
+    context,
+    "GET",
+    "/api/license/runtime",
+  );
+
+  expect(denied?.status).toBe(403);
+  await expect(denied?.json()).resolves.toMatchObject({
+    reason: "feature-disabled",
+  });
+  await expect(
+    authorizer.authorize(context, "GET", "/api/unknown"),
+  ).rejects.toThrow("平台静态 Route 缺少 Manifest 声明：GET /api/unknown");
+});
+// @windy-module system.license end
+
+test("静态 Route 包装器阻断已停用 Module，核心恢复入口显式豁免", async () => {
+  const modules = systemModuleManifests();
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: modules.flatMap(({ features }) => features),
+      disabledModuleNames: new Set(["system.identity", "system"]),
+    },
+  );
+  const authorizer = createStaticRouteAuthorizer(runtime, modules);
+  let handler: ((context: unknown) => unknown) | undefined;
+  let calls = 0;
+  const app = routeApp((registered) => {
+    handler = registered;
+  });
+  const guarded = createManifestAuthorizedRouteApp(app, authorizer);
+  guarded.get("/auth/sessions", () => {
+    calls += 1;
+    return Response.json({ ok: true });
+  });
+  const context = await runtime.createGuardContextForActor(
+    new Request("http://localhost/api/auth/sessions"),
+    actor("system.profile.read"),
+  );
+
+  const denied = await handler!({ guardContext: context });
+  expect((denied as Response).status).toBe(403);
+  expect(calls).toBe(0);
+
+  const core = createManifestAuthorizedRouteApp(app, authorizer, () => ({
+    immutableCoreAccess: true,
+  }));
+  core.get("/auth/session", () => {
+    calls += 1;
+    return Response.json({ ok: true });
+  });
+  const allowed = await handler!({ guardContext: context });
+  expect((allowed as Response).status).toBe(200);
+  expect(calls).toBe(1);
+});
+
+function routeApp(
+  capture: (handler: (context: unknown) => unknown) => void,
+): Parameters<typeof createManifestAuthorizedRouteApp>[0] {
+  return {
+    get: (_path, handler) => capture(handler),
+    post: (_path, handler) => capture(handler),
+    put: (_path, handler) => capture(handler),
+    delete: (_path, handler) => capture(handler),
+  };
+}
+
+function actor(permissionKey: string) {
+  return {
+    id: "user_1",
+    type: "user" as const,
+    name: "测试用户",
+    roleCodes: [],
+    permissionKeys: [permissionKey],
+  };
+}

package/template/apps/server/src/module-host/static-route-authorization.ts

@@ -0,0 +1,90 @@
+import { apiRouteKey, type ModuleManifest } from "@southwind-ai/modules";
+import type { RequestGuardContext } from "../guards.js";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { forbidden } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface StaticRouteAuthorizer {
+  authorize(
+    context: RequestGuardContext,
+    method: string,
+    path: string,
+    options?: {
+      readonly restrictedModeAccess?: "backup-export" | "admin-admission";
+      readonly immutableCoreAccess?: boolean;
+    },
+  ): Promise<Response | undefined>;
+}
+
+/**
+ * 平台静态 Route 与 Module Host Route 使用相同的 Manifest Guard 事实源。
+ */
+export function createStaticRouteAuthorizer(
+  runtime: ServerRuntime,
+  modules: readonly ModuleManifest[],
+): StaticRouteAuthorizer {
+  const bindings = new Map(
+    modules.flatMap((module) =>
+      module.apiPermissions.map(
+        (binding) => [apiRouteKey(binding), binding] as const,
+      ),
+    ),
+  );
+  const features = modules.flatMap((module) => module.features);
+  return {
+    async authorize(context, method, path, options) {
+      const key = apiRouteKey({ method, path });
+      const binding = bindings.get(key);
+      if (!binding) {
+        throw new Error(`平台静态 Route 缺少 Manifest 声明：${key}`);
+      }
+      if (options?.immutableCoreAccess) return undefined;
+      const feature = binding.featureKey
+        ? findFeature(features, binding.featureKey)
+        : undefined;
+      const decision = await evaluateRouteGuards(runtime, context, {
+        permission: binding,
+        feature,
+        restrictedModeAccess: options?.restrictedModeAccess,
+      });
+      return decision.allowed ? undefined : forbidden(decision.reason);
+    },
+  };
+}
+
+export function createManifestAuthorizedRouteApp(
+  app: RouteApp,
+  authorizer: StaticRouteAuthorizer,
+  options?: (
+    method: string,
+    path: string,
+  ) => Parameters<StaticRouteAuthorizer["authorize"]>[3],
+): RouteApp {
+  const wrap =
+    (method: string, path: string, handler: (context: unknown) => unknown) =>
+    async (raw: unknown) => {
+      const context = raw as { guardContext: RequestGuardContext };
+      const denied = await authorizer.authorize(
+        context.guardContext,
+        method,
+        apiPath(path),
+        options?.(method, path),
+      );
+      return denied ?? handler(raw);
+    };
+  return {
+    get: (path, handler) => app.get(path, wrap("GET", path, handler)),
+    post: (path, handler, options) =>
+      app.post(path, wrap("POST", path, handler), options),
+    put: (path, handler, options) =>
+      app.put(path, wrap("PUT", path, handler), options),
+    delete: (path, handler) => app.delete(path, wrap("DELETE", path, handler)),
+  };
+}
+
+function apiPath(path: string): string {
+  return path.startsWith("/api/") ? path : `/api${path}`;
+}

package/template/apps/server/src/module-host/task-definitions.ts

@@ -31,6 +31,7 @@ export function createModuleTaskDefinitions(
           maxAttempts: task.maxAttempts,
           retryDelaySeconds: task.retryDelaySeconds,
           permissionKey: task.permissionKey,
+          auditAction: task.auditAction,
           feature,
           handler: registration.handler,
           isIdleResult: registration.isIdleResult,

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

@@ -24,6 +24,8 @@ test("Composition Root 向业务 Handler 注入用户目录 Port", async () => {
               method: "GET",
               path: "/api/case/members",
               permissionKey: "case.member.read",
+              featureKey: "case.member",
+              auditAction: "case.member.read",
               handler: (context) => context.userDirectory.list(),
             },
           ]);
@@ -104,6 +106,7 @@ function businessManifest(): ModuleManifest {
         path: "/api/case/members",
         permissionKey: "case.member.read",
         featureKey: "case.member",
+        auditAction: "case.member.read",
       },
     ],
     features: [
@@ -121,6 +124,6 @@ function businessManifest(): ModuleManifest {
     tasks: [],
     tools: [],
     providers: [],
-    auditActions: [],
+    auditActions: ["case.member.read"],
   };
 }

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

@@ -48,11 +48,13 @@ describe("模块 Host 初始化", () => {
           description: "",
           permissionKey: "known.item.read",
           featureKey: "known.feature",
+          auditAction: "task.execute",
           intervalSeconds: 60,
           maxAttempts: 3,
           retryDelaySeconds: 10,
         },
       ],
+      auditActions: ["task.execute"],
     });
     await expect(
       initializeModuleHosts({

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

@@ -0,0 +1,289 @@
+import { describe, expect, test } from "bun:test";
+import {
+  systemModuleManifests,
+  type ModuleManifest,
+} from "@southwind-ai/modules";
+import type {
+  ModuleGovernedResourceRegistration,
+  ModuleHost,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import { prepareServerModules } from "./module-preflight.js";
+
+describe("Server Module 构建与启动前门禁", () => {
+  test("Host 实现不完整时在持久化操作前 fail closed", async () => {
+    const module = routeModule();
+    await expect(
+      prepareServerModules({
+        modules: [...systemModuleManifests(), module.manifest],
+        installations: [{ manifest: module.manifest, setup() {} }],
+      }),
+    ).rejects.toThrow("API Route GET /api/catalog/items 缺少 Handler");
+  });
+
+  test("setup 不能在首次校验后原地变异 Manifest", async () => {
+    const module = routeModule();
+    const manifest = {
+      ...module.manifest,
+      features: [...module.manifest.features],
+    };
+    await expect(
+      prepareServerModules({
+        modules: [...systemModuleManifests(), manifest],
+        installations: [
+          {
+            manifest,
+            setup() {
+              manifest.features.push(manifest.features[0]!);
+            },
+          },
+        ],
+      }),
+    ).rejects.toThrow(
+      "Server Module 在 setup 期间修改了 canonical Manifest：catalog",
+    );
+  });
+
+  test("setup 不能替换安装单元的 canonical Manifest 引用", async () => {
+    const module = routeModule();
+    const mutable = module as {
+      manifest: ModuleManifest;
+      setup: typeof module.setup;
+    };
+    await expect(
+      prepareServerModules({
+        modules: [...systemModuleManifests(), module.manifest],
+        installations: [
+          {
+            get manifest() {
+              return mutable.manifest;
+            },
+            setup() {
+              mutable.manifest = {
+                ...module.manifest,
+                apiPermissions: [],
+              };
+            },
+          },
+        ],
+      }),
+    ).rejects.toThrow(
+      "Server Module 在 setup 期间替换了 canonical Manifest：catalog",
+    );
+  });
+
+  test("attachment 结构错误时不执行任何 Module setup", async () => {
+    const manifest = governedManifest();
+    let setupCalled = false;
+    await expect(
+      prepareServerModules({
+        modules: [manifest],
+        installations: [
+          {
+            manifest,
+            setup() {
+              setupCalled = true;
+            },
+          },
+        ],
+        adapters: [
+          {
+            name: "people",
+            hostRange: "^0.1.0",
+            runtimeMode: "self-contained",
+            create: () => ({ manifest, setup() {} }),
+          },
+        ],
+        attachments: [{ name: "people", attach() {} }],
+        enabledModuleNames: new Set(["people"]),
+      }),
+    ).rejects.toThrow("不能挂载 self-contained Adapter");
+    expect(setupCalled).toBe(false);
+  });
+
+  test("返回已经完成声明与实现校验的 Host", async () => {
+    const module = routeModule();
+    const result = await prepareServerModules({
+      modules: [...systemModuleManifests(), module.manifest],
+      installations: [module],
+    });
+
+    expect(result.moduleHosts.routes).toHaveLength(1);
+    expect(result.foundationModules).toContain(module.manifest);
+  });
+
+  test("合法治理资源注册满足派生路由实现门禁", async () => {
+    const manifest = governedManifest();
+    const result = await prepareServerModules({
+      modules: [manifest],
+      installations: [
+        {
+          manifest,
+          setup(host) {
+            host.registerGovernedResources([governedRegistration()]);
+          },
+        },
+      ],
+    });
+
+    expect(result.moduleHosts.governedResources).toHaveLength(1);
+  });
+});
+
+function routeModule() {
+  const capability = featureKey("catalog.item");
+  const manifest: ModuleManifest = {
+    name: "catalog",
+    version: "1.0.0",
+    label: "目录",
+    description: "目录测试模块",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "catalog.item.read",
+        label: "查看目录",
+        module: "catalog",
+        moduleLabel: "目录",
+        resource: "item",
+        resourceLabel: "目录项",
+        action: "read",
+      },
+    ],
+    apiPermissions: [
+      {
+        method: "GET",
+        path: "/api/catalog/items",
+        permissionKey: "catalog.item.read",
+        featureKey: capability,
+        auditAction: "data.read",
+      },
+    ],
+    features: [
+      {
+        key: capability,
+        module: "catalog",
+        label: "目录项",
+        enabled: true,
+        visible: "visible",
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: ["data.read"],
+  };
+  return {
+    manifest,
+    setup(host: ModuleHost) {
+      host.registerRoutes([
+        {
+          method: "GET",
+          path: "/api/catalog/items",
+          permissionKey: "catalog.item.read",
+          featureKey: capability,
+          handler: () => ({ items: [] }),
+        },
+      ]);
+    },
+  };
+}
+
+function governedRegistration(): ModuleGovernedResourceRegistration {
+  return {
+    policyKey: "people.person.fields",
+    readPath: "/api/people/persons/:id",
+    revealPath: "/api/people/persons/:id/plaintext",
+    revealAuditAction: "data.plaintext.read",
+    authorize: () => true,
+    read: () => ({
+      id: "person-1",
+      publicFields: { name: "张三" },
+      governedFields: { phone: "13812348071" },
+    }),
+  };
+}
+
+function governedManifest(): ModuleManifest {
+  const capability = featureKey("people.person");
+  return {
+    name: "people",
+    version: "1.0.0",
+    label: "人员",
+    description: "人员主档",
+    menus: [],
+    adminRoutes: [],
+    permissions: ["read", "reveal", "export"].map((action) => ({
+      key: `people.person.${action}`,
+      label: action,
+      module: "people",
+      moduleLabel: "人员",
+      resource: "person",
+      resourceLabel: "人员",
+      action: action as "read" | "reveal" | "export",
+      ...(action === "reveal"
+        ? { accessRisk: "sensitive-disclosure" as const }
+        : action === "export"
+          ? { accessRisk: "governed-export" as const }
+          : {}),
+    })),
+    apiPermissions: [
+      {
+        method: "GET",
+        path: "/api/people/persons/:id",
+        permissionKey: "people.person.read",
+        featureKey: capability,
+        auditAction: "data.read",
+      },
+      {
+        method: "POST",
+        path: "/api/people/persons/:id/plaintext",
+        permissionKey: "people.person.reveal",
+        featureKey: capability,
+        auditAction: "data.plaintext.read",
+      },
+    ],
+    features: [
+      {
+        key: capability,
+        module: "people",
+        label: "人员主档",
+        enabled: true,
+        visible: "visible",
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    dataPolicies: [
+      {
+        key: "people.person.fields",
+        resourceType: "people.person",
+        version: "1",
+        featureKey: capability,
+        readPermissionKey: "people.person.read",
+        revealPermissionKey: "people.person.reveal",
+        exportPermissionKey: "people.person.export",
+        display: {
+          read: "masked",
+          reveal: "plaintext",
+          unauthorized: "hidden",
+        },
+        fields: [
+          {
+            fieldKey: "phone",
+            classification: "sensitive",
+            mask: { kind: "partial", prefix: 3, suffix: 4 },
+          },
+        ],
+      },
+    ],
+    auditActions: ["data.read", "data.plaintext.read"],
+  };
+}