create-windy 0.2.18 → 0.2.20

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

@@ -0,0 +1,156 @@
+import { randomUUIDv7 } from "bun";
+import type { DurableJobs } from "@southwind-ai/jobs";
+import type {
+  ModuleActor,
+  ModuleAuditEmitInput,
+  ModuleAuditEmitter,
+  ModuleJobSubmitter,
+  ModuleRequestContext,
+  ModuleStoragePort,
+} from "@southwind-ai/server-sdk";
+import { requireModuleNamespace } from "@southwind-ai/server-sdk";
+import type { AuditEvent } from "@southwind-ai/shared";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+const requestActorByModuleView = new WeakMap<object, RequestActor>();
+
+/**
+ * 收窄为模块 Actor 只读视图。只复制 SDK 明确公开的字段，避免凭据状态、
+ * 联系方式与数据范围令牌在运行时通过属性枚举泄漏给业务模块。
+ */
+export function toModuleActor(actor: RequestActor): ModuleActor {
+  const view: ModuleActor = Object.freeze({
+    id: actor.id,
+    type: actor.type,
+    name: actor.name,
+    ...(actor.username ? { username: actor.username } : {}),
+    ...(actor.displayName ? { displayName: actor.displayName } : {}),
+    roleCodes: Object.freeze([...actor.roleCodes]),
+    permissionKeys: Object.freeze([...actor.permissionKeys]),
+  });
+  requestActorByModuleView.set(view, actor);
+  return view;
+}
+
+/**
+ * Host 内部适配器通过对象身份恢复原始 Actor，使平台内置模块仍能复用宿主的数据
+ * 范围执行链；原始 Actor 不作为 SDK 字段下发，外部业务包也无法访问该映射。
+ */
+export function requestActorFromModule(actor: ModuleActor): RequestActor {
+  const requestActor = requestActorByModuleView.get(actor);
+  if (!requestActor) {
+    throw new Error("模块 Actor 不是由当前宿主颁发");
+  }
+  return requestActor;
+}
+
+export interface ModuleRequestContextInput {
+  moduleName: string;
+  manifest: ModuleManifest;
+  guardContext: RequestGuardContext;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+  body?: unknown;
+  runtime: ServerRuntime;
+  jobs?: DurableJobs;
+  storage?: ModuleStoragePort;
+}
+
+export function buildModuleRequestContext(
+  input: ModuleRequestContextInput,
+): ModuleRequestContext {
+  return {
+    requestId: input.guardContext.requestId,
+    actor: toModuleActor(input.guardContext.actor),
+    params: input.params,
+    query: input.query,
+    body: input.body,
+    audit: createModuleAuditEmitter(input),
+    jobs: createModuleJobSubmitter(input),
+    storage: input.storage ?? unavailableModuleStorage(input.moduleName),
+  };
+}
+
+function createModuleAuditEmitter(
+  input: ModuleRequestContextInput,
+): ModuleAuditEmitter {
+  const allowed = new Set(
+    input.manifest.auditActions.map((action) =>
+      typeof action === "string" ? action : action.key,
+    ),
+  );
+  return {
+    async emit(action: string, event: ModuleAuditEmitInput = {}) {
+      if (!allowed.has(action)) {
+        throw new Error(
+          `审计动作未在模块 ${input.moduleName} Manifest 注册：${action}`,
+        );
+      }
+      const auditEvent = buildAuditEvent(input.guardContext, action, event);
+      if (event.critical) {
+        await input.runtime.auditSink.recordCriticalEvent(auditEvent);
+        return;
+      }
+      input.runtime.auditSink.recordEvent(auditEvent);
+    },
+  };
+}
+
+function buildAuditEvent(
+  context: RequestGuardContext,
+  action: string,
+  input: ModuleAuditEmitInput,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action,
+    outcome: "success",
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+      name: context.actor.name,
+    },
+    target: input.target,
+    requestId: context.requestId,
+    metadata: input.metadata,
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+function createModuleJobSubmitter(
+  input: ModuleRequestContextInput,
+): ModuleJobSubmitter {
+  return {
+    async submit(job) {
+      requireModuleNamespace("任务 handler", job.handlerKey, input.moduleName);
+      if (!input.jobs) {
+        throw new Error("Durable Jobs 运行时未挂载");
+      }
+      const result = await input.jobs.submit({
+        ...job,
+        queue: input.moduleName,
+        requestedBy: input.guardContext.actor.id,
+      });
+      return { jobId: result.job.id, created: result.created };
+    },
+  };
+}
+
+/**
+ * 存储 Port 未挂载时的防御性实现：任何访问都以明确错误失败，
+ * 而不是让模块悄悄绕过 purpose / owner 约束。
+ */
+function unavailableModuleStorage(moduleName: string): ModuleStoragePort {
+  const fail = (): never => {
+    throw new Error(`模块 ${moduleName} 的存储 Port 未挂载`);
+  };
+  return {
+    createUploadSession: () => fail(),
+    openFile: () => fail(),
+    openPublicFile: () => fail(),
+  };
+}

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

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import type { ManagedRole } from "../system/entities.js";
+import { InMemoryEntityRepository } from "../system/repository.js";
+import type { RegisteredModuleRolePreset } from "./initialize.js";
+import {
+  moduleRolePresetId,
+  synchronizeModuleRolePresets,
+} from "./role-presets.js";
+
+describe("模块角色预设同步", () => {
+  test("预设落库为独立角色且重复同步幂等", async () => {
+    const roles = new InMemoryEntityRepository<ManagedRole>([]);
+    const snapshot = createFoundationSnapshot();
+
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+    const created = await roles.get(moduleRolePresetId("shop.manager"));
+    expect(created).toMatchObject({
+      code: "shop.manager",
+      name: "店长",
+      dataScope: "department-and-children",
+      permissionKeys: ["shop.item.manage", "shop.item.read"],
+      status: "active",
+    });
+
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+    const again = await roles.get(moduleRolePresetId("shop.manager"));
+    expect(again?.permissionKeys).toEqual(created?.permissionKeys);
+  });
+
+  test("已存在角色保留管理员手工追加的授权", async () => {
+    const roles = new InMemoryEntityRepository<ManagedRole>([]);
+    const snapshot = createFoundationSnapshot();
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+
+    const id = moduleRolePresetId("shop.manager");
+    const existing = await roles.get(id);
+    if (!existing) throw new Error("角色预设未创建");
+    await roles.update(
+      id,
+      { permissionKeys: [...existing.permissionKeys, "system.menu.read"] },
+      actor,
+    );
+
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+    const merged = await roles.get(id);
+    expect(merged?.permissionKeys).toContain("system.menu.read");
+    expect(merged?.permissionKeys).toContain("shop.item.manage");
+  });
+
+  test("预设 Code 与既有角色冲突时启动失败", async () => {
+    const roles = new InMemoryEntityRepository<ManagedRole>([
+      {
+        id: "role_custom",
+        code: "shop.manager",
+        name: "手工角色",
+        dataScope: "self",
+        permissionKeys: [],
+        menuKeys: [],
+        status: "active",
+        createdAt: "2026-07-16T00:00:00.000Z",
+        createdBy: "system",
+        updatedAt: "2026-07-16T00:00:00.000Z",
+        updatedBy: "system",
+      },
+    ]);
+
+    await expect(
+      synchronizeModuleRolePresets({ roles }, createFoundationSnapshot(), [
+        preset(),
+      ]),
+    ).rejects.toThrow("角色预设与既有角色冲突：shop.manager");
+  });
+});
+
+function preset(): RegisteredModuleRolePreset {
+  return {
+    moduleName: "shop",
+    preset: {
+      key: "shop.manager",
+      label: "店长",
+      dataScope: "department-and-children",
+      permissionKeys: ["shop.item.read", "shop.item.manage"],
+    },
+  };
+}
+
+const actor = {
+  id: "system_bootstrap",
+  type: "service" as const,
+  name: "平台初始化",
+  roleCodes: ["system"],
+  permissionKeys: ["system.role.manage"],
+};

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