create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,344 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey, type PermissionDefinition } from "@southwind-ai/shared";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleGovernedResourceRegistration } from "@southwind-ai/server-sdk";
+import { buildActorScopeContexts } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { installModuleGovernedResourceRoutes } from "./governed-resource-routes.js";
+import { initializeModuleHosts } from "./initialize.js";
+
+describe("业务模块数据治理 Port", () => {
+  test("普通读取只返回掩码，明文要求独立权限、理由与再认证", async () => {
+    const fixture = await setup();
+    const masked = (await fixture.invoke("GET")) as {
+      governedFields: {
+        phone: { kind: string; classification: string; display: string };
+      };
+    };
+    expect(masked.governedFields.phone).toEqual({
+      kind: "masked",
+      classification: "sensitive",
+      display: "138****8071",
+    });
+    expect(JSON.stringify(masked)).not.toContain("13812348071");
+
+    const denied = (await fixture.invoke("POST", {
+      reason: "案件复核需要核对联系方式",
+      password: "wrong",
+      fieldKeys: ["phone"],
+    })) as Response;
+    expect(denied.status).toBe(403);
+    expect(fixture.reads()).toBe(1);
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "people.phone.reveal",
+        outcome: "denied",
+      }),
+    );
+
+    const revealed = (await fixture.invoke("POST", {
+      reason: "案件复核需要核对联系方式",
+      password: "correct",
+      fieldKeys: ["phone"],
+    })) as {
+      governedFields: {
+        phone: { kind: string; value: string; grantId: string };
+      };
+    };
+    expect(revealed.governedFields.phone).toMatchObject({
+      kind: "plaintext",
+      value: "13812348071",
+      grantId: expect.any(String),
+    });
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "people.phone.reveal",
+        outcome: "success",
+        metadata: expect.objectContaining({
+          reason: "案件复核需要核对联系方式",
+          fieldKeys: ["phone"],
+        }),
+      }),
+    );
+  });
+
+  test("对象授权、权限与投影字段漂移均 fail-closed", async () => {
+    const unauthorized = await setup({ objectAllowed: false });
+    const missing = (await unauthorized.invoke("GET")) as Response;
+    expect(missing.status).toBe(404);
+    expect(unauthorized.reads()).toBe(0);
+
+    const noPermission = await setup({ permissionKeys: [] });
+    const forbidden = (await noPermission.invoke("GET")) as Response;
+    expect(forbidden.status).toBe(403);
+    expect(noPermission.authorizations()).toBe(0);
+
+    const drift = await setup({ projectionDrift: true });
+    await expect(drift.invoke("GET")).rejects.toThrow(
+      "业务治理投影与 Manifest 不一致",
+    );
+  });
+
+  test("注册拒绝未知策略、错误 API 绑定与重复策略", async () => {
+    const declared = peopleManifest();
+    await expect(
+      initializeModuleHosts({
+        modules: [declared],
+        installations: [
+          {
+            manifest: declared,
+            setup(host) {
+              host.registerGovernedResources([
+                { ...registration(), policyKey: "people.unknown" },
+              ]);
+            },
+          },
+        ],
+      }),
+    ).rejects.toThrow("业务治理资源未在 Manifest 声明");
+
+    const wrongRoute = peopleManifest();
+    wrongRoute.apiPermissions[1] = {
+      ...wrongRoute.apiPermissions[1]!,
+      permissionKey: "people.person.read",
+    };
+    await expect(createHosts(wrongRoute)).rejects.toThrow(
+      "业务治理路由与 Manifest 绑定不一致",
+    );
+
+    await expect(
+      initializeModuleHosts({
+        modules: [declared],
+        installations: [
+          {
+            manifest: declared,
+            setup(host) {
+              host.registerGovernedResources([registration(), registration()]);
+            },
+          },
+        ],
+      }),
+    ).rejects.toThrow("业务治理资源重复注册");
+  });
+
+});
+
+interface SetupOptions {
+  permissionKeys?: string[];
+  objectAllowed?: boolean;
+  projectionDrift?: boolean;
+}
+
+async function setup(options: SetupOptions = {}) {
+  let authorizationCalls = 0;
+  let readCalls = 0;
+  const registrationValue = registration({
+    authorize() {
+      authorizationCalls += 1;
+      return options.objectAllowed ?? true;
+    },
+    read() {
+      readCalls += 1;
+      return {
+        id: "person-1",
+        publicFields: options.projectionDrift
+          ? { name: "张三", phone: "leak" }
+          : { name: "张三" },
+        governedFields: { phone: "13812348071" },
+      };
+    },
+  });
+  const declared = peopleManifest();
+  const hosts = await initializeModuleHosts({
+    modules: [declared],
+    installations: [
+      {
+        manifest: declared,
+        setup(host) {
+          host.registerGovernedResources([registrationValue]);
+        },
+      },
+    ],
+  });
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: {
+        resolve: () => actor(options.permissionKeys),
+      },
+      featureCatalog: declared.features,
+    },
+  );
+  const app = new FakeRouteApp();
+  installModuleGovernedResourceRoutes(hosts, app, {
+    runtime,
+    features: declared.features,
+    reauthenticate: (_actorId, password) =>
+      Promise.resolve(password === "correct"),
+  });
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/people/persons/person-1"),
+  );
+  return {
+    runtime,
+    authorizations: () => authorizationCalls,
+    reads: () => readCalls,
+    invoke(method: "GET" | "POST", body?: unknown) {
+      const path =
+        method === "GET"
+          ? "/people/persons/:id"
+          : "/people/persons/:id/plaintext";
+      return app.invoke(method, path, {
+        guardContext,
+        params: { id: "person-1" },
+        query: {},
+        body,
+      });
+    },
+  };
+}
+
+function createHosts(manifest: ModuleManifest) {
+  return initializeModuleHosts({
+    modules: [manifest],
+    installations: [
+      {
+        manifest,
+        setup(host) {
+          host.registerGovernedResources([registration()]);
+        },
+      },
+    ],
+  });
+}
+
+function registration(
+  overrides: Partial<ModuleGovernedResourceRegistration> = {},
+): ModuleGovernedResourceRegistration {
+  return {
+    policyKey: "people.person.fields",
+    readPath: "/api/people/persons/:id",
+    revealPath: "/api/people/persons/:id/plaintext",
+    revealAuditAction: "people.phone.reveal",
+    authorize: () => true,
+    read: () => ({
+      id: "person-1",
+      publicFields: { name: "张三" },
+      governedFields: { phone: "13812348071" },
+    }),
+    ...overrides,
+  };
+}
+
+function peopleManifest(): ModuleManifest {
+  const policyFeature = featureKey("people.person");
+  return {
+    name: "people",
+    version: "0.1.0",
+    label: "人员",
+    description: "人员主档",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      permission("people.person.read", "read"),
+      permission("people.person.reveal", "reveal", "sensitive-disclosure"),
+      permission("people.person.export", "export", "governed-export"),
+    ],
+    apiPermissions: [
+      {
+        method: "GET",
+        path: "/api/people/persons/:id",
+        permissionKey: "people.person.read",
+        featureKey: policyFeature,
+      },
+      {
+        method: "POST",
+        path: "/api/people/persons/:id/plaintext",
+        permissionKey: "people.person.reveal",
+        featureKey: policyFeature,
+      },
+    ],
+    features: [
+      {
+        key: policyFeature,
+        label: "人员主档",
+        module: "people",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    dataPolicies: [
+      {
+        key: "people.person.fields",
+        resourceType: "people.person",
+        version: "1",
+        featureKey: policyFeature,
+        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: ["people.phone.reveal"],
+  };
+}
+
+function permission(
+  key: string,
+  action: PermissionDefinition["action"],
+  accessRisk?: PermissionDefinition["accessRisk"],
+): PermissionDefinition {
+  return {
+    key,
+    label: key,
+    module: "people",
+    moduleLabel: "人员",
+    resource: "person",
+    resourceLabel: "人员",
+    action,
+    accessRisk,
+  };
+}
+
+function actor(
+  permissionKeys = [
+    "people.person.read",
+    "people.person.reveal",
+    "people.person.export",
+  ],
+): RequestActor {
+  return {
+    id: "user-reviewer",
+    type: "user",
+    name: "复核员",
+    roleCodes: ["reviewer"],
+    permissionKeys,
+    ...buildActorScopeContexts("user-reviewer", "dept-case", [
+      {
+        id: "role-reviewer",
+        code: "reviewer",
+        dataScope: "department",
+        departmentIds: [],
+      },
+    ]),
+  };
+}

package/template/apps/server/src/module-host/governed-resources.ts

@@ -0,0 +1,203 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  requireModuleNamespace,
+  type ModuleGovernedResourceRegistration,
+} from "@southwind-ai/server-sdk";
+import type { RegisteredModuleGovernedResource } from "./initialize-contracts.js";
+
+export interface GovernedResourceRegistrationState {
+  readonly governedResources: RegisteredModuleGovernedResource[];
+  readonly governedResourceKeys: Set<string>;
+  readonly routeKeys: Set<string>;
+}
+
+export function registerGovernedResources(
+  manifest: ModuleManifest,
+  state: GovernedResourceRegistrationState,
+  registrations: readonly ModuleGovernedResourceRegistration[],
+) {
+  for (const registration of registrations) {
+    requireModuleNamespace(
+      "数据治理策略",
+      registration.policyKey,
+      manifest.name,
+    );
+    const policy = manifest.dataPolicies?.find(
+      ({ key }) => key === registration.policyKey,
+    );
+    if (!policy) {
+      throw new Error(
+        `业务治理资源未在 Manifest 声明：${registration.policyKey}`,
+      );
+    }
+    if (state.governedResourceKeys.has(registration.policyKey)) {
+      throw new Error(`业务治理资源重复注册：${registration.policyKey}`);
+    }
+    validateRoute(
+      manifest,
+      state,
+      "GET",
+      registration.readPath,
+      policy.readPermissionKey,
+      policy.featureKey,
+    );
+    if (registration.export) {
+      validateExportRegistration(manifest, state, registration);
+    }
+    validateRoute(
+      manifest,
+      state,
+      "POST",
+      registration.revealPath,
+      policy.revealPermissionKey,
+      policy.featureKey,
+    );
+    const audits = new Set(
+      manifest.auditActions.map((action) =>
+        typeof action === "string" ? action : action.key,
+      ),
+    );
+    if (!audits.has(registration.revealAuditAction)) {
+      throw new Error(
+        `业务治理明文审计未在 Manifest 声明：${registration.revealAuditAction}`,
+      );
+    }
+    state.governedResourceKeys.add(registration.policyKey);
+    state.governedResources.push({
+      moduleName: manifest.name,
+      registration,
+    });
+  }
+}
+
+function validateExportRegistration(
+  manifest: ModuleManifest,
+  state: GovernedResourceRegistrationState,
+  registration: ModuleGovernedResourceRegistration,
+) {
+  const policy = manifest.dataPolicies?.find(
+    ({ key }) => key === registration.policyKey,
+  );
+  if (!policy || !registration.export) return;
+  const basePath = registration.export.basePath;
+  if (
+    !basePath.startsWith(`/api/${manifest.name}/`) ||
+    basePath.includes(":id") ||
+    basePath.endsWith("/")
+  ) {
+    throw new Error(`业务治理导出基路径无效：${basePath}`);
+  }
+  if (
+    registration.export.retentionSeconds !== undefined &&
+    (!Number.isInteger(registration.export.retentionSeconds) ||
+      registration.export.retentionSeconds < 60)
+  ) {
+    throw new Error(`业务治理导出保留时间无效：${registration.policyKey}`);
+  }
+  validateRenderers(manifest, registration);
+  for (const [method, suffix] of [
+    ["POST", ""],
+    ["GET", "/:id"],
+    ["POST", "/:id/cancel"],
+    ["GET", "/:id/download"],
+  ] as const) {
+    validateRoute(
+      manifest,
+      state,
+      method,
+      `${basePath}${suffix}`,
+      policy.exportPermissionKey,
+      policy.featureKey,
+      false,
+    );
+  }
+}
+
+function validateRenderers(
+  manifest: ModuleManifest,
+  registration: ModuleGovernedResourceRegistration,
+) {
+  const renderers = registration.export?.renderers;
+  if (!renderers) return;
+  if (renderers.length === 0) {
+    throw new Error(`业务治理导出 Renderer 列表不能为空：${registration.policyKey}`);
+  }
+  const formatKeys = new Set<string>();
+  const schemas = new Set(
+    (manifest.jsonSchemas ?? []).map(({ key }) => key),
+  );
+  for (const renderer of renderers) {
+    if (
+      !/^[a-z0-9][a-z0-9._-]{0,79}$/.test(renderer.formatKey) ||
+      formatKeys.has(renderer.formatKey)
+    ) {
+      throw new Error(
+        `业务治理导出 formatKey 无效或重复：${renderer.formatKey}`,
+      );
+    }
+    formatKeys.add(renderer.formatKey);
+    requireModuleNamespace("治理导出模板", renderer.templateKey, manifest.name);
+    if (!schemas.has(renderer.inputSchemaKey)) {
+      throw new Error(
+        `业务治理导出引用了未注册 JSON Schema：${renderer.inputSchemaKey}`,
+      );
+    }
+    if (
+      !renderer.templateVersion.trim() ||
+      renderer.templateVersion.length > 80 ||
+      !/^[a-z0-9][a-z0-9.+-]{0,79}$/i.test(renderer.templateVersion) ||
+      renderer.contentType.length > 120 ||
+      !/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i.test(
+        renderer.contentType,
+      ) ||
+      !/^[a-z0-9]{1,16}$/.test(renderer.filenameExtension) ||
+      !Number.isInteger(renderer.limits.maxRecords) ||
+      renderer.limits.maxRecords < 1 ||
+      renderer.limits.maxRecords > 1_000_000 ||
+      !Number.isInteger(renderer.limits.maxOutputBytes) ||
+      renderer.limits.maxOutputBytes < 1 ||
+      renderer.limits.maxOutputBytes > 1024 * 1024 * 1024 ||
+      !Number.isInteger(renderer.limits.timeoutSeconds) ||
+      renderer.limits.timeoutSeconds < 1 ||
+      renderer.limits.timeoutSeconds > 900
+    ) {
+      throw new Error(
+        `业务治理导出 Renderer 元数据或上限无效：${renderer.formatKey}`,
+      );
+    }
+  }
+}
+
+function validateRoute(
+  manifest: ModuleManifest,
+  state: GovernedResourceRegistrationState,
+  method: "GET" | "POST",
+  path: string,
+  permissionKey: string,
+  featureKey: string,
+  requireResourceId = true,
+) {
+  if (
+    !path.startsWith("/api/") ||
+    (requireResourceId && !path.includes(":id"))
+  ) {
+    throw new Error(
+      `业务治理路由必须是${requireResourceId ? "含 :id 的 " : ""}/api 路径：${path}`,
+    );
+  }
+  const binding = manifest.apiPermissions.find(
+    (item) => item.method === method && item.path === path,
+  );
+  if (
+    !binding ||
+    binding.permissionKey !== permissionKey ||
+    binding.featureKey !== featureKey
+  ) {
+    throw new Error(`业务治理路由与 Manifest 绑定不一致：${method} ${path}`);
+  }
+  const key = `${method} ${path}`;
+  if (state.routeKeys.has(key)) {
+    throw new Error(`模块路由重复注册：${key}`);
+  }
+  state.routeKeys.add(key);
+}

package/template/apps/server/src/module-host/http-runtime.ts

@@ -0,0 +1,95 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+// @windy-module system.scheduler begin
+import type { DurableJobService } from "../jobs/service.js";
+import type { DurableJobWorker } from "../jobs/worker.js";
+// @windy-module system.scheduler end
+import type { createServerRuntime } from "../runtime.js";
+// @windy-module system.storage begin
+import type { createStorageRuntime } from "../storage/runtime.js";
+// @windy-module system.storage end
+import type { RouteApp } from "../system/route-types.js";
+import type { SystemRepositories } from "../system/seed.js";
+// @windy-module system.agent begin
+import type { RequestGuardContext } from "../guards.js";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import type { ModuleAiOperationPort } from "@southwind-ai/server-sdk";
+// @windy-module system.agent end
+import { installModuleRoutes } from "./route-installer.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+// @windy-module system.data-governance begin
+import type { GovernedExportService } from "../data-governance/export/service.js";
+import { installModuleGovernedExportRoutes } from "./governed-export-routes.js";
+import { installModuleGovernedResourceRoutes } from "./governed-resource-routes.js";
+// @windy-module system.data-governance end
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function installModuleHttpRuntime(
+  hosts: InitializedModuleHosts,
+  app: RouteApp,
+  context: {
+    runtime: ServerRuntime;
+    features: readonly FeatureFlagDefinition[];
+    // @windy-module system.scheduler begin
+    jobs: DurableJobService;
+    jobWorker: DurableJobWorker;
+    // @windy-module system.scheduler end
+    // @windy-module system.storage begin
+    storage: ReturnType<typeof createStorageRuntime>;
+    // @windy-module system.storage end
+    systemRepositories: SystemRepositories;
+    // @windy-module system.agent begin
+    aiArtifacts?: AiArtifactRuntime;
+    aiOperations?: (
+      moduleName: string,
+      guardContext: RequestGuardContext,
+      signal: AbortSignal,
+    ) => ModuleAiOperationPort;
+    // @windy-module system.agent end
+    // @windy-module system.data-governance begin
+    reauthenticate(actorId: string, password: string): Promise<boolean>;
+    governedExportService: GovernedExportService;
+    // @windy-module system.data-governance end
+  },
+) {
+  installModuleRoutes(hosts, app, {
+    runtime: context.runtime,
+    features: context.features,
+    // @windy-module system.scheduler begin
+    jobs: context.jobs,
+    jobControl: { worker: context.jobWorker },
+    // @windy-module system.scheduler end
+    // @windy-module system.storage begin
+    storage: {
+      uploads: context.storage.uploads,
+      files: context.storage.files,
+    },
+    // @windy-module system.storage end
+    userDirectory: {
+      repositories: context.systemRepositories,
+    },
+    // @windy-module system.agent begin
+    aiArtifacts: context.aiArtifacts
+      ? (moduleName, guardContext, signal) =>
+          context.aiArtifacts!.createModulePort(
+            moduleName,
+            guardContext,
+            signal,
+          )
+      : undefined,
+    aiOperations: context.aiOperations,
+    // @windy-module system.agent end
+  });
+  // @windy-module system.data-governance begin
+  installModuleGovernedResourceRoutes(hosts, app, {
+    runtime: context.runtime,
+    features: context.features,
+    reauthenticate: context.reauthenticate,
+  });
+  installModuleGovernedExportRoutes(hosts, app, {
+    runtime: context.runtime,
+    features: context.features,
+    service: context.governedExportService,
+  });
+  // @windy-module system.data-governance end
+}

package/template/apps/server/src/module-host/initialize-contracts.ts

@@ -4,10 +4,12 @@ import type {
   InstallableServerModule,
   ModuleAiOperationHandlerRegistration,
   ModuleInitializer,
+  ModuleGovernedResourceRegistration,
   ModuleRolePreset,
   ModuleResourceFileAccessPolicy,
   ModuleRouteDefinition,
   ModuleSearchProvider,
+  ModuleSandboxToolHandlerRegistration,
   ModuleTaskHandlerRegistration,
   ModuleToolHandlerRegistration,
   ModuleUploadPolicy,
@@ -28,11 +30,21 @@ export interface RegisteredModuleToolHandler {
   readonly registration: ModuleToolHandlerRegistration;
 }
 
+export interface RegisteredModuleSandboxToolHandler {
+  readonly moduleName: string;
+  readonly registration: ModuleSandboxToolHandlerRegistration;
+}
+
 export interface RegisteredModuleAiOperationHandler {
   readonly moduleName: string;
   readonly registration: ModuleAiOperationHandlerRegistration;
 }
 
+export interface RegisteredModuleGovernedResource {
+  readonly moduleName: string;
+  readonly registration: ModuleGovernedResourceRegistration;
+}
+
 export interface RegisteredModuleRolePreset {
   readonly moduleName: string;
   readonly preset: ModuleRolePreset;
@@ -59,7 +71,9 @@ export interface InitializedModuleHosts {
   readonly routes: readonly RegisteredModuleRoute[];
   readonly taskHandlers: readonly RegisteredModuleTaskHandler[];
   readonly toolHandlers: readonly RegisteredModuleToolHandler[];
+  readonly sandboxToolHandlers: readonly RegisteredModuleSandboxToolHandler[];
   readonly aiOperationHandlers: readonly RegisteredModuleAiOperationHandler[];
+  readonly governedResources: readonly RegisteredModuleGovernedResource[];
   readonly rolePresets: readonly RegisteredModuleRolePreset[];
   readonly searchProviders: readonly RegisteredModuleSearchProvider[];
   manifestOf(moduleName: string): ModuleManifest;