create-windy 0.2.33 → 0.3.0

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

@@ -0,0 +1,305 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import {
+  FileService,
+  InMemoryUploadRepository,
+  MemoryBlobStore,
+  UploadService,
+} from "@southwind-ai/storage";
+import { buildActorScopeContexts } from "../data-access/context.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { initializeModuleHosts } from "./initialize.js";
+import type { ModuleStorageServices } from "./storage-port.js";
+import { createModuleToolHandlerMap } from "./tool-handlers.js";
+
+describe("业务 Tool Storage Port 组合", () => {
+  test("每次执行使用当前 Actor/Scope 重验资源绑定并允许跨上传者读取", async () => {
+    const declared = toolManifest();
+    const evidence = evidenceManifest();
+    const hosts = await initializeModuleHosts({
+      modules: [evidence, declared],
+      installations: [
+        {
+          manifest: evidence,
+          setup(host) {
+            host.registerUploadPolicy(uploadPolicy());
+          },
+        },
+        {
+          manifest: declared,
+          setup(host) {
+            host.registerResourceFileAccessPolicies([
+              {
+                purpose: "evidence.original",
+                resourceType: "media.evidence-file",
+                featureKey: "media.catalog",
+                permissionKey: "media.read",
+                auditAction: "media.file.read",
+                authorize: ({ fileId, resourceId }, context) =>
+                  fileId === linkedFileId &&
+                  resourceId === "evidence_file_1" &&
+                  context.actor.id === "user_reader",
+              },
+            ]);
+            host.registerToolHandlers([
+              {
+                toolKey: "media.metadata.catalog",
+                scopeMode: "request",
+                async execute(input, context) {
+                  const file = await context.storage.openResourceFile({
+                    fileId: String(input.fileId),
+                    purpose: "evidence.original",
+                    resourceType: "media.evidence-file",
+                    resourceId: String(input.resourceId),
+                  });
+                  return { fileId: file.id, sha256: file.sha256 };
+                },
+              },
+            ]);
+          },
+        },
+      ],
+    });
+    const storage = createTestStorage(hosts.uploadPolicies);
+    const seeded = await seed(storage);
+    linkedFileId = seeded.id;
+    const runtime = createServerRuntime();
+    const handlers = createModuleToolHandlerMap(hosts, {
+      runtime,
+      features: declared.features,
+      storage,
+    });
+    const handler = handlers.get("media.metadata.catalog");
+    if (!handler) throw new Error("缺少 Tool Handler");
+
+    await expect(
+      handler.execute(
+        { fileId: seeded.id, resourceId: "evidence_file_1" },
+        executionContext(actor("user_reader")),
+      ),
+    ).resolves.toEqual({
+      fileId: seeded.id,
+      sha256: seeded.contentHash.value,
+    });
+    expect(runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "media.file.read",
+        outcome: "success",
+        target: {
+          type: "media.evidence-file",
+          id: "evidence_file_1",
+        },
+        metadata: {
+          fileId: seeded.id,
+          purpose: "evidence.original",
+        },
+      }),
+    );
+
+    await expect(
+      handler.execute(
+        { fileId: seeded.id, resourceId: "evidence_file_1" },
+        executionContext(actor("user_other")),
+      ),
+    ).rejects.toThrow("资源文件访问未授权");
+
+    const invalidScopeActor = actor("user_reader");
+    delete invalidScopeActor.scopeContext;
+    await expect(
+      handler.execute(
+        { fileId: seeded.id, resourceId: "evidence_file_1" },
+        executionContext(invalidScopeActor),
+      ),
+    ).rejects.toThrow("资源文件访问未授权");
+  });
+
+  test("未挂载 Storage 时 Tool Port 明确 fail-closed", async () => {
+    const declared = toolManifest();
+    const hosts = await initializeModuleHosts({
+      modules: [declared],
+      installations: [
+        {
+          manifest: declared,
+          setup(host) {
+            host.registerToolHandlers([
+              {
+                toolKey: "media.metadata.catalog",
+                scopeMode: "request",
+                async execute(_input, context) {
+                  await context.storage.openResourceFile({} as never);
+                  return {};
+                },
+              },
+            ]);
+          },
+        },
+      ],
+    });
+    const handler = createModuleToolHandlerMap(hosts, {
+      runtime: createServerRuntime(),
+      features: declared.features,
+    }).get("media.metadata.catalog");
+    if (!handler) throw new Error("缺少 Tool Handler");
+
+    await expect(
+      handler.execute({}, executionContext(actor("user_reader"))),
+    ).rejects.toThrow("模块 media 的存储 Port 未挂载");
+  });
+});
+
+let linkedFileId = "";
+
+function actor(id: string): RequestActor {
+  return {
+    id,
+    type: "user",
+    name: id,
+    roleCodes: ["analyst"],
+    permissionKeys: ["media.read"],
+    ...buildActorScopeContexts(id, undefined, [
+      {
+        id: "role_analyst",
+        code: "analyst",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function executionContext(currentActor: RequestActor) {
+  const guardContext: RequestGuardContext = {
+    actor: currentActor,
+    requestId: `request_${currentActor.id}`,
+    startedAt: new Date().toISOString(),
+  };
+  return { guardContext, signal: new AbortController().signal };
+}
+
+function toolManifest(): ModuleManifest {
+  return {
+    name: "media",
+    version: "0.1.0",
+    label: "媒体",
+    description: "媒体测试模块",
+    dependencies: ["evidence"],
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "media.read",
+        label: "读取媒体",
+        module: "media",
+        moduleLabel: "媒体",
+        resource: "file",
+        resourceLabel: "文件",
+        action: "read",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("media.catalog"),
+        label: "媒体目录",
+        module: "media",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [
+      {
+        key: "media.metadata.catalog",
+        label: "媒体元数据",
+        description: "读取案件范围内媒体元数据",
+        inputSchemaKey: "media.metadata.input",
+        outputSchemaKey: "media.metadata.output",
+        operation: "background",
+        permissionKey: "media.read",
+        featureKey: "media.catalog",
+        auditAction: "media.file.read",
+        scopeMode: "request",
+        dataClassification: "sensitive",
+        idempotency: "supported",
+        approval: "none",
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 1024,
+          maxOutputBytes: 1024,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: ["media.file.read"],
+  };
+}
+
+function evidenceManifest(): ModuleManifest {
+  return {
+    name: "evidence",
+    version: "0.1.0",
+    label: "物证",
+    description: "物证原件模块",
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+  };
+}
+
+function uploadPolicy() {
+  return {
+    purpose: "evidence.original",
+    maxByteSize: 1024,
+    maxPartByteSize: 512,
+    sessionTtlMs: 60_000,
+    allowedTypes: { "image/jpeg": ["jpg"] },
+    signature: "none" as const,
+  };
+}
+
+function createTestStorage(
+  policies: ConstructorParameters<typeof UploadService>[0]["policies"],
+): ModuleStorageServices {
+  const repository = new InMemoryUploadRepository();
+  const blobStore = new MemoryBlobStore();
+  return {
+    uploads: new UploadService({ repository, blobStore, policies }),
+    files: new FileService(repository, blobStore),
+  };
+}
+
+async function seed(storage: ModuleStorageServices) {
+  const data = new TextEncoder().encode("abc");
+  const sha256 = new Bun.CryptoHasher("sha256").update(data).digest("hex");
+  const session = await storage.uploads.create({
+    ownerId: "user_uploader",
+    purpose: "evidence.original",
+    filename: "photo.jpg",
+    mimeType: "image/jpeg",
+    expectedByteSize: data.byteLength,
+    expectedSha256: sha256,
+  });
+  await storage.uploads.appendPart({
+    sessionId: session.id,
+    ownerId: "user_uploader",
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: data.byteLength,
+    sha256,
+    body: new Blob([data]).stream(),
+  });
+  return storage.uploads.complete(session.id, "user_uploader");
+}

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

@@ -1,6 +1,22 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import type { ModuleToolHandlers } from "../agent/tool-registry.js";
+import type { createServerRuntime } from "../runtime.js";
 import type { InitializedModuleHosts } from "./initialize.js";
 import { toModuleActor } from "./request-context.js";
+import {
+  createModuleStoragePort,
+  type ModuleStorageServices,
+  unavailableModuleStoragePort,
+} from "./storage-port.js";
+import { createModuleStorageScope } from "./storage-scope.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface ModuleToolHandlerMapContext {
+  readonly runtime: ServerRuntime;
+  readonly features: readonly FeatureFlagDefinition[];
+  readonly storage?: ModuleStorageServices;
+}
 
 /**
  * 把模块经 Host 注册的 Agent Tool Handler 适配为 Agent 路由层的
@@ -8,18 +24,36 @@ import { toModuleActor } from "./request-context.js";
  */
 export function createModuleToolHandlerMap(
   hosts: InitializedModuleHosts,
+  hostContext: ModuleToolHandlerMapContext,
 ): ModuleToolHandlers {
   return new Map(
-    hosts.toolHandlers.map(({ registration }) => [
+    hosts.toolHandlers.map(({ moduleName, registration }) => [
       registration.toolKey,
       {
         scopeMode: registration.scopeMode,
-        execute: (input, context) =>
-          registration.execute(input, {
+        execute: (input, context) => {
+          const storage = hostContext.storage
+            ? createModuleStoragePort(
+                hostContext.storage,
+                createModuleStorageScope({
+                  moduleName,
+                  purposes: hosts.uploadPurposesOf(moduleName),
+                  resourceFileAccessPolicies:
+                    hosts.resourceFileAccessPoliciesOf(moduleName),
+                  guardContext: context.guardContext,
+                  runtime: hostContext.runtime,
+                  features: hostContext.features,
+                  signal: context.signal,
+                }),
+              )
+            : unavailableModuleStoragePort(moduleName);
+          return registration.execute(input, {
             actor: toModuleActor(context.guardContext.actor),
             requestId: context.guardContext.requestId,
             signal: context.signal,
-          }),
+            storage,
+          });
+        },
       },
     ]),
   );

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

@@ -0,0 +1,126 @@
+import { expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { createSystemRepositories } from "../system/seed.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { installModuleRoutes } from "./route-installer.js";
+
+test("Composition Root 向业务 Handler 注入用户目录 Port", async () => {
+  const manifest = businessManifest();
+  const foundation = createFoundationSnapshot();
+  const repositories = createSystemRepositories(foundation);
+  const hosts = await initializeModuleHosts({
+    modules: [manifest],
+    installations: [
+      {
+        manifest,
+        setup(host) {
+          host.registerRoutes([
+            {
+              method: "GET",
+              path: "/api/case/members",
+              permissionKey: "case.member.read",
+              handler: (context) => context.userDirectory.list(),
+            },
+          ]);
+        },
+      },
+    ],
+  });
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: [...manifest.features, ...foundation.features],
+      featureResolver: {
+        resolve: (key) => ({ key, enabled: true, visible: "visible" }),
+      },
+    },
+  );
+  const app = new FakeRouteApp();
+  installModuleRoutes(hosts, app, {
+    runtime,
+    features: [...manifest.features, ...foundation.features],
+    userDirectory: { repositories },
+  });
+
+  const result = await app.invoke("GET", "/case/members", {
+    guardContext: {
+      requestId: "request-composition",
+      actor: {
+        id: "case_admin",
+        type: "user",
+        name: "案件管理员",
+        roleCodes: ["case-admin"],
+        permissionKeys: ["case.member.read", "system.user-directory.read"],
+        scopeContext: buildScopeContext("case_admin", "dept_platform", [
+          {
+            id: "role-case-admin",
+            code: "case-admin",
+            dataScope: "all",
+            departmentIds: [],
+          },
+        ]),
+      },
+      startedAt: "2026-07-25T00:00:00.000Z",
+    },
+    params: {},
+    query: {},
+  });
+
+  expect(result).toEqual({
+    items: [{ id: "user_dev_admin", displayName: "开发管理员" }],
+    total: 1,
+    page: 1,
+    pageSize: 20,
+  });
+});
+
+function businessManifest(): ModuleManifest {
+  return {
+    name: "case",
+    version: "0.1.0",
+    label: "案件",
+    description: "用户目录组合测试",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "case.member.read",
+        label: "查看成员",
+        module: "case",
+        moduleLabel: "案件",
+        resource: "member",
+        resourceLabel: "案件成员",
+        action: "read",
+      },
+    ],
+    apiPermissions: [
+      {
+        method: "GET",
+        path: "/api/case/members",
+        permissionKey: "case.member.read",
+        featureKey: "case.member",
+      },
+    ],
+    features: [
+      {
+        key: featureKey("case.member"),
+        label: "案件成员",
+        module: "case",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+  };
+}