create-windy 0.2.33 → 0.2.34

package/template/apps/server/src/module-host/storage-port.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import type { ModuleInitializer } from "@southwind-ai/server-sdk";
+import type {
+  ModuleInitializer,
+  ModuleResourceFileAccessPolicy,
+} from "@southwind-ai/server-sdk";
 import type { FileMetadata, UploadPolicy } from "@southwind-ai/storage";
 import { createStorageRuntime } from "../storage/runtime.js";
 import { initializeModuleHosts } from "./initialize.js";
@@ -83,6 +86,120 @@ describe("模块受限 Upload/BlobRead Port", () => {
     expect(opened.id).toBe(file.id);
   });
 
+  test("资源绑定策略允许案件范围内跨上传者读取且只返回最小元数据", async () => {
+    const { storage } = setup();
+    const file = await seedFile(storage, "user_uploader", "shop.attachment");
+    const decisions: Array<{
+      outcome: "success" | "denied";
+      fileId: string;
+    }> = [];
+    const port = resourcePort(storage, {
+      authorize: ({ fileId, resourceId }, context) =>
+        fileId === file.id &&
+        resourceId === "order_1" &&
+        context.actor.id === "user_reader",
+      record: (_policy, input, outcome) => {
+        decisions.push({ outcome, fileId: input.fileId });
+      },
+    });
+
+    const opened = await port.openResourceFile({
+      fileId: file.id,
+      purpose: "shop.attachment",
+      resourceType: "shop.order-file",
+      resourceId: "order_1",
+    });
+
+    expect(opened).toMatchObject({
+      id: file.id,
+      purpose: "shop.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      byteSize: 3,
+      sha256: file.contentHash.value,
+    });
+    expect("ownerId" in opened).toBe(false);
+    expect("artifactRef" in opened).toBe(false);
+    expect(decisions).toEqual([{ outcome: "success", fileId: file.id }]);
+  });
+
+  test("资源绑定、平台 Guard、用途与资源类型任一不满足均 fail-closed", async () => {
+    const { storage } = setup();
+    const file = await seedFile(storage, "user_uploader", "shop.attachment");
+    let resolverCalls = 0;
+    const deniedByGuard = resourcePort(storage, {
+      platformAllowed: false,
+      authorize: () => {
+        resolverCalls += 1;
+        return true;
+      },
+    });
+    await expect(
+      deniedByGuard.openResourceFile(resourceRequest(file.id)),
+    ).rejects.toThrow("资源文件访问未授权");
+    expect(resolverCalls).toBe(0);
+
+    const deniedByBinding = resourcePort(storage, {
+      authorize: () => false,
+    });
+    await expect(
+      deniedByBinding.openResourceFile(resourceRequest(file.id)),
+    ).rejects.toThrow("资源文件访问未授权");
+    await expect(
+      deniedByBinding.openResourceFile(resourceRequest("file_not_exists")),
+    ).rejects.toThrow("资源文件访问未授权");
+
+    await expect(
+      deniedByBinding.openResourceFile({
+        ...resourceRequest(file.id),
+        resourceType: "shop.unknown",
+      }),
+    ).rejects.toThrow("资源文件访问未授权");
+    await expect(
+      deniedByBinding.openResourceFile({
+        ...resourceRequest(file.id),
+        purpose: "other.attachment",
+      }),
+    ).rejects.toThrow("资源文件访问未授权");
+  });
+
+  test("资源拒绝与成功审计只接收稳定 ID 和 purpose", async () => {
+    const { storage } = setup();
+    const file = await seedFile(storage, "user_uploader", "shop.attachment");
+    const outcomes: string[] = [];
+    const port = resourcePort(storage, {
+      authorize: () => false,
+      record: (_policy, input, outcome) => {
+        outcomes.push(`${outcome}:${input.resourceId}:${input.purpose}`);
+      },
+    });
+
+    await expect(
+      port.openResourceFile(resourceRequest(file.id)),
+    ).rejects.toThrow("资源文件访问未授权");
+    expect(outcomes).toEqual(["denied:order_1:shop.attachment"]);
+
+    const failedResolver = resourcePort(storage, {
+      authorize: () => {
+        throw new Error("database details");
+      },
+    });
+    await expect(
+      failedResolver.openResourceFile(resourceRequest(file.id)),
+    ).rejects.toThrow("资源文件访问未授权");
+
+    const storageDenied: string[] = [];
+    const missingFile = resourcePort(storage, {
+      record: (_policy, _input, outcome) => {
+        storageDenied.push(outcome);
+      },
+    });
+    await expect(
+      missingFile.openResourceFile(resourceRequest("file_not_exists")),
+    ).rejects.toThrow("资源文件访问未授权");
+    expect(storageDenied).toEqual(["denied"]);
+  });
+
   test("命名空间重叠模块注册同一用途在启动时失败", async () => {
     const initializer = (
       moduleName: string,
@@ -121,6 +238,58 @@ function setup() {
   return { storage, port };
 }
 
+interface ResourcePortOptions {
+  platformAllowed?: boolean;
+  authorize?: ModuleResourceFileAccessPolicy["authorize"];
+  record?: NonNullable<
+    Parameters<typeof createModuleStoragePort>[1]["recordResourceFileDecision"]
+  >;
+}
+
+function resourcePort(
+  storage: ReturnType<typeof createStorageRuntime>,
+  options: ResourcePortOptions = {},
+) {
+  const policy: ModuleResourceFileAccessPolicy = {
+    purpose: "shop.attachment",
+    resourceType: "shop.order-file",
+    featureKey: "shop.order",
+    permissionKey: "shop.order.read",
+    auditAction: "shop.order.file-read",
+    authorize: options.authorize ?? (() => true),
+  };
+  return createModuleStoragePort(
+    { uploads: storage.uploads, files: storage.files },
+    {
+      moduleName: "shop",
+      ownerId: "user_reader",
+      purposes: new Set(["shop.attachment"]),
+      actor: {
+        id: "user_reader",
+        type: "user",
+        name: "读取者",
+        roleCodes: ["reader"],
+        permissionKeys: ["shop.order.read"],
+      },
+      requestId: "request_resource",
+      signal: new AbortController().signal,
+      resourceFileAccessPolicies: [policy],
+      authorizeResourceFileAccess: () =>
+        Promise.resolve(options.platformAllowed ?? true),
+      recordResourceFileDecision: options.record,
+    },
+  );
+}
+
+function resourceRequest(fileId: string) {
+  return {
+    fileId,
+    purpose: "shop.attachment",
+    resourceType: "shop.order-file",
+    resourceId: "order_1",
+  };
+}
+
 function policy(purpose: string): UploadPolicy {
   return {
     purpose,

package/template/apps/server/src/module-host/storage-port.ts

@@ -1,4 +1,9 @@
-import type { ModuleStoragePort } from "@southwind-ai/server-sdk";
+import type {
+  ModuleActor,
+  ModuleResourceFileAccessPolicy,
+  ModuleResourceFileRequest,
+  ModuleStoragePort,
+} from "@southwind-ai/server-sdk";
 import {
   UploadError,
   type FileService,
@@ -15,6 +20,19 @@ export interface ModuleStorageScope {
   ownerId: string;
   /** 本模块经 Host 注册的上传用途集合；跨模块与平台用途一律拒绝。 */
   purposes: ReadonlySet<string>;
+  /** Host 颁发的 Actor 只读视图；资源文件访问策略不能从输入伪造 Actor。 */
+  actor?: ModuleActor;
+  requestId?: string;
+  signal?: AbortSignal;
+  resourceFileAccessPolicies?: readonly ModuleResourceFileAccessPolicy[];
+  authorizeResourceFileAccess?: (
+    policy: ModuleResourceFileAccessPolicy,
+  ) => Promise<boolean>;
+  recordResourceFileDecision?: (
+    policy: ModuleResourceFileAccessPolicy,
+    input: ModuleResourceFileRequest,
+    outcome: "success" | "denied",
+  ) => Promise<void> | void;
 }
 
 /**
@@ -23,6 +41,7 @@ export interface ModuleStorageScope {
  * - 上传会话强制 purpose ∈ 本模块已注册 Policy，Owner 由宿主以当前 Actor 补齐；
  * - 文件读取走 FileService 的 Owner 约束，且文件用途必须属于本模块；
  * - 公开读取走 FileService 的 Purpose 约束，用途同样必须属于本模块；
+ * - 资源文件读取须匹配当前模块注册的绑定策略，可读取显式依赖模块的用途；
  * - 模块不直接接触 BlobStore 或 Upload Repository。
  */
 export function createModuleStoragePort(
@@ -43,9 +62,105 @@ export function createModuleStoragePort(
       requireModulePurpose(scope, purpose);
       return services.files.openPublic(fileId, purpose);
     },
+    async openResourceFile(input) {
+      const policy = findResourceFileAccessPolicy(scope, input);
+      const actor = scope.actor;
+      if (
+        !actor ||
+        !scope.requestId ||
+        !scope.signal ||
+        !scope.authorizeResourceFileAccess
+      ) {
+        throw forbiddenResourceFile();
+      }
+      if (!(await authorizeHost(scope, policy))) {
+        return denyResourceFile(scope, policy, input);
+      }
+      if (!(await authorizeBusinessResource(scope, policy, input, actor))) {
+        return denyResourceFile(scope, policy, input);
+      }
+      let opened: Awaited<ReturnType<FileService["open"]>>;
+      try {
+        opened = await services.files.open(input.fileId, actor.id, true);
+      } catch {
+        return denyResourceFile(scope, policy, input);
+      }
+      if (opened.purpose !== input.purpose) {
+        return denyResourceFile(scope, policy, input);
+      }
+      await scope.recordResourceFileDecision?.(policy, input, "success");
+      return {
+        id: opened.id,
+        purpose: opened.purpose,
+        filename: opened.filename,
+        mimeType: opened.mimeType,
+        byteSize: opened.byteSize,
+        sha256: opened.contentHash.value,
+        body: opened.body,
+      };
+    },
   };
 }
 
+async function denyResourceFile(
+  scope: ModuleStorageScope,
+  policy: ModuleResourceFileAccessPolicy,
+  input: ModuleResourceFileRequest,
+): Promise<never> {
+  try {
+    await scope.recordResourceFileDecision?.(policy, input, "denied");
+  } catch {
+    // 审计失败不能把底层错误暴露给调用方，访问仍保持 fail-closed。
+  }
+  throw forbiddenResourceFile();
+}
+
+async function authorizeHost(
+  scope: ModuleStorageScope,
+  policy: ModuleResourceFileAccessPolicy,
+): Promise<boolean> {
+  try {
+    return (await scope.authorizeResourceFileAccess?.(policy)) === true;
+  } catch {
+    return false;
+  }
+}
+
+async function authorizeBusinessResource(
+  scope: ModuleStorageScope,
+  policy: ModuleResourceFileAccessPolicy,
+  input: ModuleResourceFileRequest,
+  actor: ModuleActor,
+): Promise<boolean> {
+  try {
+    return (
+      (await policy.authorize(
+        { fileId: input.fileId, resourceId: input.resourceId },
+        {
+          actor,
+          requestId: scope.requestId!,
+          signal: scope.signal!,
+        },
+      )) === true
+    );
+  } catch {
+    return false;
+  }
+}
+
+function findResourceFileAccessPolicy(
+  scope: ModuleStorageScope,
+  input: ModuleResourceFileRequest,
+): ModuleResourceFileAccessPolicy {
+  const policy = scope.resourceFileAccessPolicies?.find(
+    (candidate) =>
+      candidate.purpose === input.purpose &&
+      candidate.resourceType === input.resourceType,
+  );
+  if (!policy) throw forbiddenResourceFile();
+  return policy;
+}
+
 function requireModulePurpose(
   scope: ModuleStorageScope,
   purpose: string,
@@ -57,3 +172,21 @@ function requireModulePurpose(
     );
   }
 }
+
+function forbiddenResourceFile(): UploadError {
+  return new UploadError("UPLOAD_FORBIDDEN", "资源文件访问未授权");
+}
+
+export function unavailableModuleStoragePort(
+  moduleName: string,
+): ModuleStoragePort {
+  const fail = (): never => {
+    throw new Error(`模块 ${moduleName} 的存储 Port 未挂载`);
+  };
+  return {
+    createUploadSession: () => fail(),
+    openFile: () => fail(),
+    openPublicFile: () => fail(),
+    openResourceFile: () => fail(),
+  };
+}

package/template/apps/server/src/module-host/storage-scope.ts

@@ -0,0 +1,96 @@
+import { randomUUIDv7 } from "bun";
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type {
+  ModuleResourceFileAccessPolicy,
+  ModuleResourceFileRequest,
+} from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { findFeature } from "../route-guards.js";
+import type { ModuleStorageScope } from "./storage-port.js";
+import { toModuleActor } from "./request-context.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface ModuleStorageScopeInput {
+  readonly moduleName: string;
+  readonly purposes: ReadonlySet<string>;
+  readonly resourceFileAccessPolicies: readonly ModuleResourceFileAccessPolicy[];
+  readonly guardContext: RequestGuardContext;
+  readonly runtime: ServerRuntime;
+  readonly features: readonly FeatureFlagDefinition[];
+  readonly signal: AbortSignal;
+}
+
+export function createModuleStorageScope(
+  input: ModuleStorageScopeInput,
+): ModuleStorageScope {
+  const actor = toModuleActor(input.guardContext.actor);
+  return {
+    moduleName: input.moduleName,
+    ownerId: actor.id,
+    purposes: input.purposes,
+    actor,
+    requestId: input.guardContext.requestId,
+    signal: input.signal,
+    resourceFileAccessPolicies: input.resourceFileAccessPolicies,
+    async authorizeResourceFileAccess(policy) {
+      if (
+        !isServerScopeContext(input.guardContext.actor.scopeContext) ||
+        input.guardContext.actor.scopeContext.actorId !== actor.id
+      ) {
+        return false;
+      }
+      const feature = findFeature([...input.features], policy.featureKey);
+      if (!feature) return false;
+      const result = await evaluateAccessGuards(
+        input.runtime,
+        input.guardContext,
+        {
+          permission: { permissionKey: policy.permissionKey },
+          feature,
+        },
+      );
+      return result.decision.allowed;
+    },
+    recordResourceFileDecision(policy, request, outcome) {
+      input.runtime.auditSink.recordEvent(
+        resourceFileEvent(input, policy, request, outcome),
+      );
+    },
+  };
+}
+
+function resourceFileEvent(
+  input: ModuleStorageScopeInput,
+  policy: ModuleResourceFileAccessPolicy,
+  request: ModuleResourceFileRequest,
+  outcome: "success" | "denied",
+) {
+  return {
+    id: randomUUIDv7(),
+    action: policy.auditAction,
+    outcome,
+    actor: {
+      id: input.guardContext.actor.id,
+      type:
+        input.guardContext.actor.type === "anonymous"
+          ? ("user" as const)
+          : input.guardContext.actor.type,
+      name: input.guardContext.actor.name,
+    },
+    target: {
+      type: request.resourceType,
+      id: request.resourceId,
+    },
+    module: input.moduleName,
+    requestId: input.guardContext.requestId,
+    metadata: {
+      fileId: request.fileId,
+      purpose: request.purpose,
+    },
+    occurredAt: new Date().toISOString(),
+  };
+}