create-windy 0.2.33 → 0.3.0

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

@@ -6,7 +6,7 @@ import type { ModuleManifest } from "@southwind-ai/modules";
 import {
   requireModuleNamespace,
   type ModuleHost,
-  type ModuleRouteDefinition,
+  type ModuleResourceFileAccessPolicy,
   type ModuleUploadPolicy,
 } from "@southwind-ai/server-sdk";
 import type {
@@ -19,6 +19,11 @@ import type {
   RegisteredModuleTaskHandler,
   RegisteredModuleToolHandler,
 } from "./initialize-contracts.js";
+import {
+  registerResourceFileAccessPolicies,
+  validateResourceFileAccessPurposes,
+} from "./resource-file-policies.js";
+import { validateRouteDeclaration } from "./route-declaration.js";
 
 export type {
   InitializedModuleHosts,
@@ -53,6 +58,15 @@ export async function initializeModuleHosts(
     uploadPolicies,
     uploadPurposes,
     modulePurposes: new Map<string, Set<string>>(),
+    moduleDependencies: new Map(
+      input.modules.map((module) => [module.name, module.dependencies ?? []]),
+    ),
+    resourceFileAccessPolicies: [],
+    moduleResourceFileAccessPolicies: new Map<
+      string,
+      ModuleResourceFileAccessPolicy[]
+    >(),
+    resourceFileAccessPolicyKeys: new Set<string>(),
     handlerKeys: new Set<string>(),
     handlerInstallers: [],
     routes: [],
@@ -104,10 +118,12 @@ export async function initializeModuleHosts(
     }
     await installation.setup(createScopedHost(manifest, state));
   }
+  validateResourceFileAccessPurposes(state);
 
   return {
     manifests: input.modules,
     uploadPolicies: [...state.uploadPolicies],
+    resourceFileAccessPolicies: [...state.resourceFileAccessPolicies],
     routes: [...state.routes],
     taskHandlers: [...state.taskHandlers],
     toolHandlers: [...state.toolHandlers],
@@ -122,6 +138,9 @@ export async function initializeModuleHosts(
     uploadPurposesOf(moduleName) {
       return state.modulePurposes.get(moduleName) ?? new Set<string>();
     },
+    resourceFileAccessPoliciesOf(moduleName) {
+      return state.moduleResourceFileAccessPolicies.get(moduleName) ?? [];
+    },
     installDurableHandlers(registry) {
       for (const install of state.handlerInstallers) install(registry);
     },
@@ -132,6 +151,13 @@ interface HostCollections {
   uploadPolicies: ModuleUploadPolicy[];
   uploadPurposes: Set<string>;
   modulePurposes: Map<string, Set<string>>;
+  moduleDependencies: ReadonlyMap<string, readonly string[]>;
+  resourceFileAccessPolicies: ModuleResourceFileAccessPolicy[];
+  moduleResourceFileAccessPolicies: Map<
+    string,
+    ModuleResourceFileAccessPolicy[]
+  >;
+  resourceFileAccessPolicyKeys: Set<string>;
   handlerKeys: Set<string>;
   handlerInstallers: HandlerInstaller[];
   routes: RegisteredModuleRoute[];
@@ -167,6 +193,9 @@ function createScopedHost(
       purposes.add(policy.purpose);
       state.modulePurposes.set(moduleName, purposes);
     },
+    registerResourceFileAccessPolicies(policies) {
+      registerResourceFileAccessPolicies(manifest, state, policies);
+    },
     registerDurableHandler<T>(definition: DurableHandlerDefinition<T>) {
       requireModuleNamespace("任务 handler", definition.key, moduleName);
       if (state.handlerKeys.has(definition.key)) {
@@ -283,46 +312,3 @@ function createScopedHost(
     },
   };
 }
-
-function validateRouteDeclaration(
-  manifest: ModuleManifest,
-  definition: ModuleRouteDefinition,
-): void {
-  const binding = manifest.apiPermissions.find(
-    (item) =>
-      item.method === definition.method && item.path === definition.path,
-  );
-  const route = `${definition.method} ${definition.path}`;
-  if (!binding) {
-    throw new Error(`模块路由未在 Manifest 声明：${route}`);
-  }
-  if (binding.permissionKey !== definition.permissionKey) {
-    throw new Error(`模块路由权限与 Manifest 声明不一致：${route}`);
-  }
-  if (
-    definition.featureKey !== undefined &&
-    binding.featureKey !== definition.featureKey
-  ) {
-    throw new Error(`模块路由 Feature 与 Manifest 声明不一致：${route}`);
-  }
-  if (
-    binding.featureKey &&
-    !manifest.features.some(({ key }) => key === binding.featureKey)
-  ) {
-    throw new Error(
-      `模块路由 Feature 未在 Manifest 注册：${binding.featureKey}`,
-    );
-  }
-  if (
-    definition.auditAction &&
-    !manifest.auditActions.some((action) =>
-      typeof action === "string"
-        ? action === definition.auditAction
-        : action.key === definition.auditAction,
-    )
-  ) {
-    throw new Error(
-      `模块路由审计动作未在 Manifest 注册：${definition.auditAction}`,
-    );
-  }
-}

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

@@ -7,12 +7,21 @@ import type {
   ModuleJobSubmitter,
   ModuleRequestContext,
   ModuleStoragePort,
+  ModuleUserDirectoryPort,
+} from "@southwind-ai/server-sdk";
+import {
+  ModuleUserDirectoryError,
+  requireModuleNamespace,
 } 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 {
+  auditActor,
+  type RequestActor,
+  type RequestGuardContext,
+} from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
+import { unavailableModuleStoragePort } from "./storage-port.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -58,6 +67,7 @@ export interface ModuleRequestContextInput {
   runtime: ServerRuntime;
   jobs?: DurableJobs;
   storage?: ModuleStoragePort;
+  userDirectory?: ModuleUserDirectoryPort;
 }
 
 export function buildModuleRequestContext(
@@ -71,7 +81,22 @@ export function buildModuleRequestContext(
     body: input.body,
     audit: createModuleAuditEmitter(input),
     jobs: createModuleJobSubmitter(input),
-    storage: input.storage ?? unavailableModuleStorage(input.moduleName),
+    storage: input.storage ?? unavailableModuleStoragePort(input.moduleName),
+    userDirectory:
+      input.userDirectory ?? unavailableModuleUserDirectory(input.moduleName),
+  };
+}
+
+function unavailableModuleUserDirectory(
+  moduleName: string,
+): ModuleUserDirectoryPort {
+  return {
+    async list() {
+      throw new ModuleUserDirectoryError(
+        "USER_DIRECTORY_UNAVAILABLE",
+        `模块 ${moduleName} 的用户目录 Port 未挂载`,
+      );
+    },
   };
 }
 
@@ -109,11 +134,7 @@ function buildAuditEvent(
     id: randomUUIDv7(),
     action,
     outcome: "success",
-    actor: {
-      id: context.actor.id,
-      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
-      name: context.actor.name,
-    },
+    actor: auditActor(context),
     target: input.target,
     requestId: context.requestId,
     metadata: input.metadata,
@@ -139,18 +160,3 @@ function createModuleJobSubmitter(
     },
   };
 }
-
-/**
- * 存储 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/resource-file-policies.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey } from "@southwind-ai/shared";
+import type {
+  ModuleInitializer,
+  ModuleResourceFileAccessPolicy,
+} from "@southwind-ai/server-sdk";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("模块资源文件访问策略注册", () => {
+  test("组合保留同 Manifest 的 purpose、Feature、Permission 与 Audit 契约", async () => {
+    const declared = declaredManifest();
+    const policy = accessPolicy();
+    const hosts = await initializeModuleHosts({
+      modules: [declared],
+      initializers: [
+        initializer((host) => {
+          host.registerResourceFileAccessPolicies([policy]);
+          host.registerUploadPolicy(uploadPolicy());
+        }),
+      ],
+    });
+
+    expect(hosts.resourceFileAccessPoliciesOf("evidence")).toEqual([policy]);
+  });
+
+  test("未注册 purpose、未知 Manifest 引用与重复策略均 fail-fast", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [declaredManifest()],
+        initializers: [
+          initializer((host) => {
+            host.registerResourceFileAccessPolicies([accessPolicy()]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow(
+      "资源文件访问策略用途未由模块 evidence 或其声明依赖注册：evidence.original",
+    );
+
+    await expect(
+      initializeModuleHosts({
+        modules: [declaredManifest()],
+        initializers: [
+          initializer((host) => {
+            host.registerUploadPolicy(uploadPolicy());
+            host.registerResourceFileAccessPolicies([
+              { ...accessPolicy(), permissionKey: "evidence.unknown" },
+            ]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("资源文件访问权限未在 Manifest 声明：evidence.unknown");
+
+    await expect(
+      initializeModuleHosts({
+        modules: [declaredManifest()],
+        initializers: [
+          initializer((host) => {
+            host.registerUploadPolicy(uploadPolicy());
+            host.registerResourceFileAccessPolicies([
+              accessPolicy(),
+              accessPolicy(),
+            ]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("资源文件访问策略重复注册");
+  });
+
+  test("资源类型、用途和治理 Key 不能越过模块命名空间", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [declaredManifest()],
+        initializers: [
+          initializer((host) => {
+            host.registerUploadPolicy(uploadPolicy());
+            host.registerResourceFileAccessPolicies([
+              { ...accessPolicy(), resourceType: "other.file" },
+            ]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("资源文件类型不属于模块 evidence：other.file");
+  });
+
+  test("消费者可显式读取 Manifest 依赖模块拥有的 purpose", async () => {
+    const evidence = manifest("evidence");
+    const media = manifest("media", {
+      dependencies: ["evidence"],
+      permissions: [
+        {
+          key: "media.read",
+          label: "读取媒体",
+          module: "media",
+          moduleLabel: "媒体",
+          resource: "file",
+          resourceLabel: "文件",
+          action: "read",
+        },
+      ],
+      features: [
+        {
+          key: featureKey("media.catalog"),
+          label: "媒体目录",
+          module: "media",
+          visible: "visible",
+          enabled: true,
+          stage: "stable",
+        },
+      ],
+      auditActions: ["media.file.read"],
+    });
+    const policy: ModuleResourceFileAccessPolicy = {
+      purpose: "evidence.original",
+      resourceType: "media.evidence-file",
+      featureKey: "media.catalog",
+      permissionKey: "media.read",
+      auditAction: "media.file.read",
+      authorize: () => true,
+    };
+    const hosts = await initializeModuleHosts({
+      modules: [evidence, media],
+      installations: [
+        {
+          manifest: evidence,
+          setup(host) {
+            host.registerUploadPolicy(uploadPolicy());
+          },
+        },
+        {
+          manifest: media,
+          setup(host) {
+            host.registerResourceFileAccessPolicies([policy]);
+          },
+        },
+      ],
+    });
+
+    expect(hosts.resourceFileAccessPoliciesOf("media")).toEqual([policy]);
+  });
+});
+
+function initializer(
+  initialize: ModuleInitializer["initialize"],
+): ModuleInitializer {
+  return { moduleName: "evidence", initialize };
+}
+
+function declaredManifest() {
+  return manifest("evidence", {
+    permissions: [
+      {
+        key: "evidence.read",
+        label: "读取物证",
+        module: "evidence",
+        moduleLabel: "物证",
+        resource: "file",
+        resourceLabel: "文件",
+        action: "read",
+      },
+    ],
+    features: [
+      {
+        key: featureKey("evidence.catalog"),
+        label: "物证目录",
+        module: "evidence",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    auditActions: ["evidence.file.read"],
+  });
+}
+
+function accessPolicy(): ModuleResourceFileAccessPolicy {
+  return {
+    purpose: "evidence.original",
+    resourceType: "evidence.file",
+    featureKey: "evidence.catalog",
+    permissionKey: "evidence.read",
+    auditAction: "evidence.file.read",
+    authorize: () => true,
+  };
+}
+
+function uploadPolicy() {
+  return {
+    purpose: "evidence.original",
+    maxByteSize: 1024,
+    maxPartByteSize: 512,
+    sessionTtlMs: 60_000,
+    allowedTypes: { "image/jpeg": ["jpg"] },
+    signature: "none" as const,
+  };
+}

package/template/apps/server/src/module-host/resource-file-policies.ts

@@ -0,0 +1,108 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  requireModuleNamespace,
+  type ModuleResourceFileAccessPolicy,
+} from "@southwind-ai/server-sdk";
+
+export interface ResourceFilePolicyCollections {
+  readonly modulePurposes: Map<string, Set<string>>;
+  readonly moduleDependencies: ReadonlyMap<string, readonly string[]>;
+  readonly resourceFileAccessPolicies: ModuleResourceFileAccessPolicy[];
+  readonly moduleResourceFileAccessPolicies: Map<
+    string,
+    ModuleResourceFileAccessPolicy[]
+  >;
+  readonly resourceFileAccessPolicyKeys: Set<string>;
+}
+
+export function registerResourceFileAccessPolicies(
+  manifest: ModuleManifest,
+  state: ResourceFilePolicyCollections,
+  policies: readonly ModuleResourceFileAccessPolicy[],
+): void {
+  for (const policy of policies) {
+    validateNamespace(manifest, policy);
+    validateManifest(manifest, policy);
+    const key = `${manifest.name}:${policy.purpose}:${policy.resourceType}`;
+    if (state.resourceFileAccessPolicyKeys.has(key)) {
+      throw new Error(
+        `资源文件访问策略重复注册：${policy.purpose} / ${policy.resourceType}`,
+      );
+    }
+    state.resourceFileAccessPolicyKeys.add(key);
+    state.resourceFileAccessPolicies.push(policy);
+    const modulePolicies =
+      state.moduleResourceFileAccessPolicies.get(manifest.name) ?? [];
+    modulePolicies.push(policy);
+    state.moduleResourceFileAccessPolicies.set(manifest.name, modulePolicies);
+  }
+}
+
+export function validateResourceFileAccessPurposes(
+  state: ResourceFilePolicyCollections,
+): void {
+  for (const [moduleName, policies] of state.moduleResourceFileAccessPolicies) {
+    for (const policy of policies) {
+      const owner = [...state.modulePurposes].find(([, purposes]) =>
+        purposes.has(policy.purpose),
+      )?.[0];
+      const allowedOwners = new Set([
+        moduleName,
+        ...(state.moduleDependencies.get(moduleName) ?? []),
+      ]);
+      if (!owner || !allowedOwners.has(owner)) {
+        throw new Error(
+          `资源文件访问策略用途未由模块 ${moduleName} 或其声明依赖注册：${policy.purpose}`,
+        );
+      }
+    }
+  }
+}
+
+function validateNamespace(
+  manifest: ModuleManifest,
+  policy: ModuleResourceFileAccessPolicy,
+): void {
+  const moduleName = manifest.name;
+  if (
+    ![moduleName, ...(manifest.dependencies ?? [])].some(
+      (owner) =>
+        policy.purpose === owner || policy.purpose.startsWith(`${owner}.`),
+    )
+  ) {
+    throw new Error(
+      `资源文件用途不属于模块 ${moduleName} 或其声明依赖：${policy.purpose}`,
+    );
+  }
+  requireModuleNamespace("资源文件类型", policy.resourceType, moduleName);
+  requireModuleNamespace("资源文件权限", policy.permissionKey, moduleName);
+  requireModuleNamespace("资源文件 Feature", policy.featureKey, moduleName);
+  requireModuleNamespace("资源文件审计动作", policy.auditAction, moduleName);
+}
+
+function validateManifest(
+  manifest: ModuleManifest,
+  policy: ModuleResourceFileAccessPolicy,
+): void {
+  if (!manifest.permissions.some(({ key }) => key === policy.permissionKey)) {
+    throw new Error(
+      `资源文件访问权限未在 Manifest 声明：${policy.permissionKey}`,
+    );
+  }
+  if (!manifest.features.some(({ key }) => key === policy.featureKey)) {
+    throw new Error(
+      `资源文件访问 Feature 未在 Manifest 声明：${policy.featureKey}`,
+    );
+  }
+  if (
+    !manifest.auditActions.some((action) =>
+      typeof action === "string"
+        ? action === policy.auditAction
+        : action.key === policy.auditAction,
+    )
+  ) {
+    throw new Error(
+      `资源文件访问审计动作未在 Manifest 声明：${policy.auditAction}`,
+    );
+  }
+}

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

@@ -0,0 +1,45 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleRouteDefinition } from "@southwind-ai/server-sdk";
+
+export function validateRouteDeclaration(
+  manifest: ModuleManifest,
+  definition: ModuleRouteDefinition,
+): void {
+  const binding = manifest.apiPermissions.find(
+    (item) =>
+      item.method === definition.method && item.path === definition.path,
+  );
+  const route = `${definition.method} ${definition.path}`;
+  if (!binding) {
+    throw new Error(`模块路由未在 Manifest 声明：${route}`);
+  }
+  if (binding.permissionKey !== definition.permissionKey) {
+    throw new Error(`模块路由权限与 Manifest 声明不一致：${route}`);
+  }
+  if (
+    definition.featureKey !== undefined &&
+    binding.featureKey !== definition.featureKey
+  ) {
+    throw new Error(`模块路由 Feature 与 Manifest 声明不一致：${route}`);
+  }
+  if (
+    binding.featureKey &&
+    !manifest.features.some(({ key }) => key === binding.featureKey)
+  ) {
+    throw new Error(
+      `模块路由 Feature 未在 Manifest 注册：${binding.featureKey}`,
+    );
+  }
+  if (
+    definition.auditAction &&
+    !manifest.auditActions.some((action) =>
+      typeof action === "string"
+        ? action === definition.auditAction
+        : action.key === definition.auditAction,
+    )
+  ) {
+    throw new Error(
+      `模块路由审计动作未在 Manifest 注册：${definition.auditAction}`,
+    );
+  }
+}

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

@@ -10,6 +10,11 @@ import {
   createModuleStoragePort,
   type ModuleStorageServices,
 } from "./storage-port.js";
+import {
+  createModuleUserDirectoryPort,
+  type ModuleUserDirectoryServices,
+} from "./user-directory-port.js";
+import { createModuleStorageScope } from "./storage-scope.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -21,6 +26,8 @@ export interface ModuleRouteInstallContext {
   jobs?: DurableJobs;
   /** 平台存储服务；提供后模块获得受限 Upload/BlobRead Port。 */
   storage?: ModuleStorageServices;
+  /** 平台身份目录；Adapter 会绑定当前请求 Actor 与服务端数据范围。 */
+  userDirectory?: Omit<ModuleUserDirectoryServices, "runtime" | "features">;
 }
 
 /**
@@ -69,11 +76,28 @@ export function installModuleRoutes(
         jobs: context.jobs,
         storage: context.storage
           ? createModuleStoragePort(context.storage, {
-              moduleName,
-              ownerId: route.guardContext.actor.id,
-              purposes: hosts.uploadPurposesOf(moduleName),
+              ...createModuleStorageScope({
+                moduleName,
+                purposes: hosts.uploadPurposesOf(moduleName),
+                resourceFileAccessPolicies:
+                  hosts.resourceFileAccessPoliciesOf(moduleName),
+                guardContext: route.guardContext,
+                runtime: context.runtime,
+                features: context.features,
+                signal: new AbortController().signal,
+              }),
             })
           : undefined,
+        userDirectory: context.userDirectory
+          ? createModuleUserDirectoryPort(
+              {
+                ...context.userDirectory,
+                runtime: context.runtime,
+                features: context.features,
+              },
+              route.guardContext,
+            )
+          : undefined,
       });
       const result = await definition.handler(requestContext);
       if (definition.auditAction) {