create-windy 0.2.19 → 0.2.20

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

@@ -0,0 +1,97 @@
+import type { DurableJobs } from "@southwind-ai/jobs";
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import { forbidden, routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+import { buildModuleRequestContext } from "./request-context.js";
+import {
+  createModuleStoragePort,
+  type ModuleStorageServices,
+} from "./storage-port.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+type RouteMethod = "get" | "post" | "put" | "delete";
+
+export interface ModuleRouteInstallContext {
+  runtime: ServerRuntime;
+  features: readonly FeatureFlagDefinition[];
+  jobs?: DurableJobs;
+  /** 平台存储服务；提供后模块获得受限 Upload/BlobRead Port。 */
+  storage?: ModuleStorageServices;
+}
+
+/**
+ * 把模块经 Host 注册的路由定义安装为走统一 Guard 的 API 路由。
+ * Guard（权限 / Feature / License）与 security.denied 审计由
+ * evaluateRouteGuards 统一执行，模块无需也不能绕开。
+ */
+export function installModuleRoutes(
+  hosts: InitializedModuleHosts,
+  app: RouteApp,
+  context: ModuleRouteInstallContext,
+): void {
+  for (const { moduleName, definition } of hosts.routes) {
+    const manifest = hosts.manifestOf(moduleName);
+    const binding = manifest.apiPermissions.find(
+      (item) =>
+        item.method === definition.method && item.path === definition.path,
+    );
+    if (!binding) {
+      throw new Error(
+        `模块路由未在 Manifest 声明：${definition.method} ${definition.path}`,
+      );
+    }
+    const featureKey = definition.featureKey ?? binding.featureKey;
+    const feature = featureKey
+      ? findFeature([...context.features], featureKey)
+      : undefined;
+    const path = stripApiPrefix(definition.path);
+    const method = definition.method.toLowerCase() as RouteMethod;
+    app[method](path, async (raw: unknown) => {
+      const route = routeContext(raw);
+      const decision = await evaluateRouteGuards(
+        context.runtime,
+        route.guardContext,
+        { permission: binding, feature },
+      );
+      if (!decision.allowed) return forbidden(decision.reason);
+      const requestContext = buildModuleRequestContext({
+        moduleName,
+        manifest,
+        guardContext: route.guardContext,
+        params: route.params,
+        query: route.query,
+        body: route.body,
+        runtime: context.runtime,
+        jobs: context.jobs,
+        storage: context.storage
+          ? createModuleStoragePort(context.storage, {
+              moduleName,
+              ownerId: route.guardContext.actor.id,
+              purposes: hosts.uploadPurposesOf(moduleName),
+            })
+          : undefined,
+      });
+      const result = await definition.handler(requestContext);
+      if (definition.auditAction) {
+        await requestContext.audit.emit(definition.auditAction, {
+          target: {
+            type: "module-route",
+            id: `${definition.method} ${definition.path}`,
+          },
+        });
+      }
+      return result;
+    });
+  }
+}
+
+function stripApiPrefix(path: string): string {
+  if (!path.startsWith("/api/")) {
+    throw new Error(`模块路由路径必须以 /api 开头：${path}`);
+  }
+  return path.slice("/api".length);
+}

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

@@ -0,0 +1,160 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey } from "@southwind-ai/shared";
+import type {
+  ModuleInitializer,
+  ModuleRouteDefinition,
+} from "@southwind-ai/server-sdk";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("模块路由注册", () => {
+  test("Feature 以 Manifest API binding 为唯一真相源", async () => {
+    const declaredFeature = featureKey("known.item");
+    const declared = manifest("known", {
+      apiPermissions: [
+        {
+          method: "GET",
+          path: "/api/known/items",
+          permissionKey: "known.item.read",
+          featureKey: declaredFeature,
+        },
+      ],
+      features: [
+        {
+          key: declaredFeature,
+          label: "事项",
+          module: "known",
+          visible: "visible",
+          enabled: true,
+          stage: "stable",
+        },
+      ],
+    });
+
+    const initialized = await initializeModuleHosts({
+      modules: [declared],
+      initializers: [
+        initializer((host) => {
+          host.registerRoutes([route()]);
+        }),
+      ],
+    });
+
+    expect(initialized.routes).toHaveLength(1);
+  });
+
+  test("拒绝实现侧额外声明或改写 Route Feature", async () => {
+    const withoutFeature = manifest("known", {
+      apiPermissions: [
+        {
+          method: "GET",
+          path: "/api/known/items",
+          permissionKey: "known.item.read",
+        },
+      ],
+    });
+
+    await expect(
+      initializeModuleHosts({
+        modules: [withoutFeature],
+        initializers: [
+          initializer((host) => {
+            host.registerRoutes([
+              { ...route(), featureKey: featureKey("known.item") },
+            ]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow(
+      "模块路由 Feature 与 Manifest 声明不一致：GET /api/known/items",
+    );
+  });
+
+  test("拒绝 API binding 引用 Manifest 未注册 Feature", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [
+          manifest("known", {
+            apiPermissions: [
+              {
+                method: "GET",
+                path: "/api/known/items",
+                permissionKey: "known.item.read",
+                featureKey: featureKey("known.item"),
+              },
+            ],
+          }),
+        ],
+        initializers: [
+          initializer((host) => {
+            host.registerRoutes([route()]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("模块路由 Feature 未在 Manifest 注册：known.item");
+  });
+
+  test("拒绝未声明、权限漂移、重复或未知审计动作的路由", async () => {
+    await expect(registerRoutes(manifest("known"), [route()])).rejects.toThrow(
+      "模块路由未在 Manifest 声明：GET /api/known/items",
+    );
+
+    const declared = manifest("known", {
+      apiPermissions: [
+        {
+          method: "GET",
+          path: "/api/known/items",
+          permissionKey: "known.item.manage",
+        },
+      ],
+    });
+    await expect(registerRoutes(declared, [route()])).rejects.toThrow(
+      "模块路由权限与 Manifest 声明不一致：GET /api/known/items",
+    );
+
+    const readable = manifest("known", {
+      apiPermissions: [
+        {
+          method: "GET",
+          path: "/api/known/items",
+          permissionKey: "known.item.read",
+        },
+      ],
+    });
+    await expect(registerRoutes(readable, [route(), route()])).rejects.toThrow(
+      "模块路由重复注册：GET /api/known/items",
+    );
+    await expect(
+      registerRoutes(readable, [{ ...route(), auditAction: "crud.create" }]),
+    ).rejects.toThrow("模块路由审计动作未在 Manifest 注册：crud.create");
+  });
+});
+
+function initializer(
+  initialize: ModuleInitializer["initialize"],
+): ModuleInitializer {
+  return { moduleName: "known", initialize };
+}
+
+function route(): ModuleRouteDefinition {
+  return {
+    method: "GET",
+    path: "/api/known/items",
+    permissionKey: "known.item.read",
+    handler: () => ({}),
+  };
+}
+
+function registerRoutes(
+  declared: ReturnType<typeof manifest>,
+  routes: readonly ModuleRouteDefinition[],
+) {
+  return initializeModuleHosts({
+    modules: [declared],
+    initializers: [
+      initializer((host) => {
+        host.registerRoutes(routes);
+      }),
+    ],
+  });
+}

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

@@ -0,0 +1,31 @@
+import type { ModuleSearchProvider } from "@southwind-ai/server-sdk";
+import type { SearchProvider } from "../search/contracts.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+import { toModuleActor } from "./request-context.js";
+
+/**
+ * 把模块搜索 Provider 适配为搜索 Host 的 Provider 协议。
+ * 模块只看到收窄的 Actor 视图与 RequestId；启用、授权与脱敏由搜索 Host 统一执行。
+ */
+export function adaptModuleSearchProvider(
+  provider: ModuleSearchProvider,
+): SearchProvider {
+  return {
+    key: provider.key,
+    providerVersion: provider.providerVersion,
+    search: (request, context) =>
+      provider.search(request, {
+        actor: toModuleActor(context.actor),
+        requestId: context.requestId,
+      }),
+    health: (signal) => provider.health(signal),
+  };
+}
+
+export function adaptModuleSearchProviders(
+  hosts: InitializedModuleHosts,
+): SearchProvider[] {
+  return hosts.searchProviders.map(({ provider }) =>
+    adaptModuleSearchProvider(provider),
+  );
+}

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

@@ -0,0 +1,165 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleInitializer } from "@southwind-ai/server-sdk";
+import type { FileMetadata, UploadPolicy } from "@southwind-ai/storage";
+import { createStorageRuntime } from "../storage/runtime.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { createModuleStoragePort } from "./storage-port.js";
+import { manifest } from "./test-fixtures.js";
+
+const SHOP_POLICY = policy("shop.attachment");
+const OTHER_POLICY = policy("other.attachment");
+
+describe("模块受限 Upload/BlobRead Port", () => {
+  test("本模块用途可以创建上传会话，Owner 由宿主补齐", async () => {
+    const { port } = setup();
+    const session = await port.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "现场照片.txt",
+      mimeType: "text/plain",
+      expectedByteSize: 3,
+    });
+
+    expect(session.ownerId).toBe("user_shop");
+    expect(session.purpose).toBe("shop.attachment");
+  });
+
+  test("跨模块与平台用途创建会话被拒绝", async () => {
+    const { port } = setup();
+
+    await expect(
+      port.createUploadSession({
+        purpose: "other.attachment",
+        filename: "a.txt",
+        mimeType: "text/plain",
+        expectedByteSize: 3,
+      }),
+    ).rejects.toThrow("上传用途不属于模块 shop：other.attachment");
+
+    await expect(
+      port.createUploadSession({
+        purpose: "bulk-data",
+        filename: "a.txt",
+        mimeType: "text/plain",
+        expectedByteSize: 3,
+      }),
+    ).rejects.toThrow("上传用途不属于模块 shop：bulk-data");
+  });
+
+  test("文件读取保持 Owner 约束", async () => {
+    const { storage, port } = setup();
+    const file = await seedFile(storage, "user_other", "shop.attachment");
+
+    await expect(port.openFile(file.id)).rejects.toThrow("无权访问该文件");
+
+    const ownerPort = createModuleStoragePort(
+      { uploads: storage.uploads, files: storage.files },
+      {
+        moduleName: "shop",
+        ownerId: "user_other",
+        purposes: new Set(["shop.attachment"]),
+      },
+    );
+    const opened = await ownerPort.openFile(file.id);
+    expect(opened.id).toBe(file.id);
+  });
+
+  test("Own 文件但用途越界时读取被拒绝", async () => {
+    const { storage, port } = setup();
+    const file = await seedFile(storage, "user_shop", "other.attachment");
+
+    await expect(port.openFile(file.id)).rejects.toThrow(
+      "上传用途不属于模块 shop：other.attachment",
+    );
+  });
+
+  test("公开读取强制用途属于本模块", async () => {
+    const { storage, port } = setup();
+    const file = await seedFile(storage, "user_shop", "shop.attachment");
+
+    await expect(port.openPublicFile(file.id, "bulk-data")).rejects.toThrow(
+      "上传用途不属于模块 shop：bulk-data",
+    );
+    const opened = await port.openPublicFile(file.id, "shop.attachment");
+    expect(opened.id).toBe(file.id);
+  });
+
+  test("命名空间重叠模块注册同一用途在启动时失败", async () => {
+    const initializer = (
+      moduleName: string,
+      register: ModuleInitializer["initialize"],
+    ): ModuleInitializer => ({ moduleName, initialize: register });
+
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("shop"), manifest("shop.sub")],
+        initializers: [
+          initializer("shop", (host) => {
+            host.registerUploadPolicy(policy("shop.sub"));
+          }),
+          initializer("shop.sub", (host) => {
+            host.registerUploadPolicy(policy("shop.sub"));
+          }),
+        ],
+      }),
+    ).rejects.toThrow("上传用途重复注册：shop.sub");
+  });
+});
+
+function setup() {
+  const storage = createStorageRuntime({}, undefined, [
+    SHOP_POLICY,
+    OTHER_POLICY,
+  ]);
+  const port = createModuleStoragePort(
+    { uploads: storage.uploads, files: storage.files },
+    {
+      moduleName: "shop",
+      ownerId: "user_shop",
+      purposes: new Set(["shop.attachment"]),
+    },
+  );
+  return { storage, port };
+}
+
+function policy(purpose: string): UploadPolicy {
+  return {
+    purpose,
+    maxByteSize: 1024,
+    maxPartByteSize: 512,
+    sessionTtlMs: 60_000,
+    allowedTypes: { "text/plain": ["txt"] },
+    signature: "none",
+  };
+}
+
+async function seedFile(
+  storage: ReturnType<typeof createStorageRuntime>,
+  ownerId: string,
+  purpose: string,
+): Promise<FileMetadata> {
+  const data = new TextEncoder().encode("abc");
+  const sha256 = new Bun.CryptoHasher("sha256").update(data).digest("hex");
+  const session = await storage.uploads.create({
+    ownerId,
+    purpose,
+    filename: "a.txt",
+    mimeType: "text/plain",
+    expectedByteSize: data.length,
+    expectedSha256: sha256,
+  });
+  await storage.uploads.appendPart({
+    sessionId: session.id,
+    ownerId,
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: data.length,
+    sha256,
+    body: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(data);
+        controller.close();
+      },
+    }),
+  });
+  return storage.uploads.complete(session.id, ownerId);
+}

package/template/apps/server/src/module-host/storage-port.ts

@@ -0,0 +1,59 @@
+import type { ModuleStoragePort } from "@southwind-ai/server-sdk";
+import {
+  UploadError,
+  type FileService,
+  type UploadService,
+} from "@southwind-ai/storage";
+
+export interface ModuleStorageServices {
+  uploads: UploadService;
+  files: FileService;
+}
+
+export interface ModuleStorageScope {
+  moduleName: string;
+  ownerId: string;
+  /** 本模块经 Host 注册的上传用途集合；跨模块与平台用途一律拒绝。 */
+  purposes: ReadonlySet<string>;
+}
+
+/**
+ * 模块受限 Upload / BlobRead Port。
+ *
+ * - 上传会话强制 purpose ∈ 本模块已注册 Policy，Owner 由宿主以当前 Actor 补齐；
+ * - 文件读取走 FileService 的 Owner 约束，且文件用途必须属于本模块；
+ * - 公开读取走 FileService 的 Purpose 约束，用途同样必须属于本模块；
+ * - 模块不直接接触 BlobStore 或 Upload Repository。
+ */
+export function createModuleStoragePort(
+  services: ModuleStorageServices,
+  scope: ModuleStorageScope,
+): ModuleStoragePort {
+  return {
+    async createUploadSession(input) {
+      requireModulePurpose(scope, input.purpose);
+      return services.uploads.create({ ...input, ownerId: scope.ownerId });
+    },
+    async openFile(fileId) {
+      const file = await services.files.open(fileId, scope.ownerId);
+      requireModulePurpose(scope, file.purpose);
+      return file;
+    },
+    async openPublicFile(fileId, purpose) {
+      requireModulePurpose(scope, purpose);
+      return services.files.openPublic(fileId, purpose);
+    },
+  };
+}
+
+function requireModulePurpose(
+  scope: ModuleStorageScope,
+  purpose: string,
+): void {
+  if (!scope.purposes.has(purpose)) {
+    throw new UploadError(
+      "UPLOAD_FORBIDDEN",
+      `上传用途不属于模块 ${scope.moduleName}：${purpose}`,
+    );
+  }
+}

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

@@ -0,0 +1,41 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { ScheduledTaskDefinition } from "../scheduler/types.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+
+/**
+ * 把模块经 Host 注册的定时任务 Handler 与 Manifest 声明合并为调度定义。
+ * 调度元数据一律以 Manifest 为准；声明了任务但没注册 Handler 的模块
+ * 会在最终 Composition 校验时报错。
+ */
+export function createModuleTaskDefinitions(
+  hosts: InitializedModuleHosts,
+  features: readonly FeatureFlagDefinition[],
+): ScheduledTaskDefinition[] {
+  const handlerByKey = new Map(
+    hosts.taskHandlers.map(
+      ({ registration }) => [registration.taskKey, registration] as const,
+    ),
+  );
+  return hosts.manifests.flatMap((manifest) =>
+    manifest.tasks.flatMap((task) => {
+      const registration = handlerByKey.get(task.key);
+      if (!registration) return [];
+      const feature = features.find(({ key }) => key === task.featureKey);
+      if (!feature) throw new Error(`缺少 ${task.featureKey} Feature 定义`);
+      return [
+        {
+          key: task.key,
+          label: task.label,
+          description: task.description,
+          intervalSeconds: task.intervalSeconds,
+          maxAttempts: task.maxAttempts,
+          retryDelaySeconds: task.retryDelaySeconds,
+          permissionKey: task.permissionKey,
+          feature,
+          handler: registration.handler,
+          isIdleResult: registration.isIdleResult,
+        },
+      ];
+    }),
+  );
+}

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

@@ -0,0 +1,26 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+
+/** 模块 Host 测试共用的最小 Manifest 夹具。 */
+export function manifest(
+  name: string,
+  overrides: Partial<ModuleManifest> = {},
+): ModuleManifest {
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: `${name} 模块`,
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+    ...overrides,
+  };
+}

package/template/apps/server/src/module-host/tool-handlers.ts

@@ -0,0 +1,25 @@
+import type { ModuleToolHandlers } from "../agent/routes.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+import { toModuleActor } from "./request-context.js";
+
+/**
+ * 把模块经 Host 注册的 Agent Tool Handler 适配为 Agent 路由层的
+ * Handler Map；注册与 Manifest 声明的一致性由 validateToolHandlerContract 校验。
+ */
+export function createModuleToolHandlerMap(
+  hosts: InitializedModuleHosts,
+): ModuleToolHandlers {
+  return new Map(
+    hosts.toolHandlers.map(({ registration }) => [
+      registration.toolKey,
+      {
+        scopeMode: registration.scopeMode,
+        execute: (query, context) =>
+          registration.execute(query, {
+            actor: toModuleActor(context.actor),
+            requestId: context.requestId,
+          }),
+      },
+    ]),
+  );
+}