create-windy 0.2.19 → 0.2.21

package/template/apps/server/src/module-host/role-presets.ts

@@ -0,0 +1,76 @@
+import type { FoundationSnapshot } from "../foundation.js";
+import type { RequestActor } from "../guards.js";
+import { menuKeysForPermissions } from "../system/built-in-roles.js";
+import type { SystemRepositories } from "../system/seed.js";
+import type { RegisteredModuleRolePreset } from "./initialize.js";
+
+export function moduleRolePresetId(key: string): string {
+  return `role_${key.replace(/[^a-z0-9]+/gi, "_")}`;
+}
+
+/**
+ * 把模块角色预设并入内置角色同步：不存在则创建，已存在则按内置角色的
+ * 非破坏性语义合并权限与菜单（保留管理员手工追加的授权），
+ * 不改变 4 个内置角色本身。
+ */
+export async function synchronizeModuleRolePresets(
+  repositories: Pick<SystemRepositories, "roles">,
+  snapshot: FoundationSnapshot,
+  presets: readonly RegisteredModuleRolePreset[],
+): Promise<void> {
+  const existingByCode = new Map(
+    (await repositories.roles.all()).map((role) => [role.code, role]),
+  );
+  for (const { preset } of presets) {
+    const id = moduleRolePresetId(preset.key);
+    const codeOwner = existingByCode.get(preset.key);
+    if (codeOwner && codeOwner.id !== id) {
+      throw new Error(`角色预设与既有角色冲突：${preset.key}`);
+    }
+    const permissionKeys = unique(preset.permissionKeys);
+    const menuKeys = menuKeysForPermissions(snapshot, permissionKeys);
+    const role = await repositories.roles.get(id);
+    if (!role) {
+      await repositories.roles.create(
+        {
+          id,
+          code: preset.key,
+          name: preset.label,
+          dataScope: preset.dataScope ?? "self",
+          permissionKeys,
+          menuKeys,
+          status: "active",
+        },
+        moduleRoleSyncActor,
+      );
+      continue;
+    }
+    const mergedPermissions = unique([
+      ...role.permissionKeys,
+      ...permissionKeys,
+    ]);
+    const mergedMenus = unique([...role.menuKeys, ...menuKeys]);
+    if (
+      mergedPermissions.length !== role.permissionKeys.length ||
+      mergedMenus.length !== role.menuKeys.length
+    ) {
+      await repositories.roles.update(
+        role.id,
+        { permissionKeys: mergedPermissions, menuKeys: mergedMenus },
+        moduleRoleSyncActor,
+      );
+    }
+  }
+}
+
+const moduleRoleSyncActor: RequestActor = {
+  id: "system_bootstrap",
+  type: "service",
+  name: "平台初始化",
+  roleCodes: ["system"],
+  permissionKeys: ["system.role.manage"],
+};
+
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}

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

@@ -0,0 +1,317 @@
+import { describe, expect, test } from "bun:test";
+import type { DurableJobs, SubmitDurableJob } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  ModuleInitializer,
+  ModuleRequestContext,
+} from "@southwind-ai/server-sdk";
+import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { installModuleRoutes } from "./route-installer.js";
+
+describe("模块 Guarded Route 安装", () => {
+  test("无权限拒绝并写入 security.denied 审计", async () => {
+    const fixture = await createFixture({ permissionKeys: [] });
+    const response = (await fixture.invoke("GET", "/shop/items")) as Response;
+
+    expect(response.status).toBe(403);
+    await expect(response.json()).resolves.toMatchObject({
+      reason: "missing-permission",
+    });
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "security.denied",
+        outcome: "denied",
+      }),
+    );
+    expect(fixture.handled).toBe(false);
+  });
+
+  test("Feature 停用时拒绝且不进入 Handler", async () => {
+    const fixture = await createFixture({ featureEnabled: false });
+    const response = (await fixture.invoke("GET", "/shop/items")) as Response;
+
+    expect(response.status).toBe(403);
+    await expect(response.json()).resolves.toMatchObject({
+      reason: "feature-disabled",
+    });
+    expect(fixture.handled).toBe(false);
+  });
+
+  test("授权请求进入 Handler 并自动写入路由审计动作", async () => {
+    const fixture = await createFixture();
+    const result = (await fixture.invoke("POST", "/shop/items", {}, {})) as {
+      ok: boolean;
+    };
+
+    expect(result).toEqual({ ok: true });
+    expect(fixture.handled).toBe(true);
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "crud.create",
+        target: expect.objectContaining({
+          type: "module-route",
+          id: "POST /api/shop/items",
+        }),
+      }),
+    );
+  });
+
+  test("Handler 只能获得受限上下文：审计白名单、Jobs 命名空间与未挂载存储", async () => {
+    const fixture = await createFixture({ withJobs: true });
+    await fixture.invoke("GET", "/shop/items");
+    const context = fixture.context;
+    if (!context) throw new Error("缺少请求上下文");
+
+    await expect(context.audit.emit("data.search")).rejects.toThrow(
+      "审计动作未在模块 shop Manifest 注册：data.search",
+    );
+    await expect(
+      context.jobs.submit({
+        handlerKey: "other.export",
+        idempotencyKey: "x",
+        payload: {},
+      }),
+    ).rejects.toThrow("任务 handler不属于模块 shop：other.export");
+
+    const submitted = await context.jobs.submit({
+      handlerKey: "shop.export",
+      idempotencyKey: "idem-1",
+      payload: { id: 1 },
+    });
+    expect(submitted).toEqual({ jobId: "job_1", created: true });
+    expect(fixture.submittedJob).toMatchObject({
+      handlerKey: "shop.export",
+      queue: "shop",
+      requestedBy: "user_admin",
+    });
+
+    expect(() => context.storage.createUploadSession({} as never)).toThrow(
+      "模块 shop 的存储 Port 未挂载",
+    );
+  });
+
+  test("未挂载 Durable Jobs 时提交以明确错误失败", async () => {
+    const fixture = await createFixture();
+    await fixture.invoke("GET", "/shop/items");
+    await expect(
+      fixture.context?.jobs.submit({
+        handlerKey: "shop.export",
+        idempotencyKey: "x",
+        payload: {},
+      }),
+    ).rejects.toThrow("Durable Jobs 运行时未挂载");
+  });
+
+  test("挂载存储后 Handler 经受限 Port 创建会话且用途受限", async () => {
+    const fixture = await createFixture({ withStorage: true });
+    await fixture.invoke("GET", "/shop/items");
+    const context = fixture.context;
+    if (!context) throw new Error("缺少请求上下文");
+
+    const session = await context.storage.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: 3,
+    });
+    expect(session.ownerId).toBe("user_admin");
+
+    await expect(
+      context.storage.createUploadSession({
+        purpose: "bulk-data",
+        filename: "a.txt",
+        mimeType: "text/plain",
+        expectedByteSize: 3,
+      }),
+    ).rejects.toThrow("上传用途不属于模块 shop：bulk-data");
+  });
+});
+
+interface FixtureOptions {
+  permissionKeys?: string[];
+  featureEnabled?: boolean;
+  withJobs?: boolean;
+  withStorage?: boolean;
+}
+
+async function createFixture(options: FixtureOptions = {}) {
+  const state: {
+    handled: boolean;
+    context?: ModuleRequestContext;
+    submittedJob?: SubmitDurableJob;
+  } = { handled: false };
+  const initializer: ModuleInitializer = {
+    moduleName: "shop",
+    initialize(host) {
+      host.registerUploadPolicy({
+        purpose: "shop.attachment",
+        maxByteSize: 1024,
+        maxPartByteSize: 512,
+        sessionTtlMs: 60_000,
+        allowedTypes: { "text/plain": ["txt"] },
+        signature: "none",
+      });
+      host.registerRoutes([
+        {
+          method: "GET",
+          path: "/api/shop/items",
+          permissionKey: "shop.item.read",
+          handler: (context) => {
+            state.handled = true;
+            state.context = context;
+            return { items: [] };
+          },
+        },
+        {
+          method: "POST",
+          path: "/api/shop/items",
+          permissionKey: "shop.item.manage",
+          auditAction: "crud.create",
+          handler: () => {
+            state.handled = true;
+            state.context = undefined;
+            return { ok: true };
+          },
+        },
+      ]);
+    },
+  };
+  const hosts = await initializeModuleHosts({
+    modules: [shopManifest()],
+    initializers: [initializer],
+  });
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: { resolve: () => actor(options.permissionKeys) },
+      licenseResolver: {
+        resolve: () => ({ versionKey: licenseVersionKey("standard") }),
+      },
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: options.featureEnabled ?? true,
+          visible: "visible",
+        }),
+      },
+    },
+  );
+  const jobs = options.withJobs
+    ? ({
+        submit: (input: SubmitDurableJob) => {
+          state.submittedJob = input;
+          return Promise.resolve({
+            job: { id: "job_1" },
+            created: true,
+          });
+        },
+      } as unknown as DurableJobs)
+    : undefined;
+  const app = new FakeRouteApp();
+  const storage = options.withStorage
+    ? createStorageRuntime({}, undefined, hosts.uploadPolicies)
+    : undefined;
+  installModuleRoutes(hosts, app, {
+    runtime,
+    features: shopManifest().features,
+    jobs,
+    storage: storage
+      ? { uploads: storage.uploads, files: storage.files }
+      : undefined,
+  });
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/shop/items"),
+  );
+  return {
+    runtime,
+    get handled() {
+      return state.handled;
+    },
+    get context() {
+      return state.context;
+    },
+    get submittedJob() {
+      return state.submittedJob;
+    },
+    invoke(method: string, path: string, params = {}, body?: unknown) {
+      return app.invoke(method, path, {
+        guardContext,
+        params,
+        query: {},
+        body,
+      });
+    },
+  };
+}
+
+function actor(
+  permissionKeys = ["shop.item.read", "shop.item.manage"],
+): RequestActor {
+  return {
+    id: "user_admin",
+    type: "user",
+    name: "测试管理员",
+    roleCodes: ["developer"],
+    permissionKeys,
+  };
+}
+
+function shopManifest(): ModuleManifest {
+  return {
+    name: "shop",
+    version: "0.1.0",
+    label: "商店",
+    description: "测试模块",
+    menus: [],
+    adminRoutes: [],
+    permissions: [permission("shop.item.read"), permission("shop.item.manage")],
+    apiPermissions: [
+      {
+        method: "GET",
+        path: "/api/shop/items",
+        permissionKey: "shop.item.read",
+        featureKey: "shop.feature",
+      },
+      {
+        method: "POST",
+        path: "/api/shop/items",
+        permissionKey: "shop.item.manage",
+        featureKey: "shop.feature",
+      },
+    ],
+    features: [
+      {
+        key: featureKey("shop.feature"),
+        label: "商店",
+        module: "shop",
+        description: "测试 Feature",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: ["crud.create"],
+  };
+}
+
+function permission(key: string) {
+  return {
+    key,
+    label: key,
+    module: "shop",
+    moduleLabel: "商店",
+    resource: "item",
+    resourceLabel: "商品",
+    action: key.endsWith("read") ? ("read" as const) : ("manage" as const),
+  };
+}

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