create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { createStorageRuntime } from "../storage/runtime.js";
+import {
+  createRestartHttpServer,
+  restartActor,
+  restartUploadPolicy,
+} from "./storage-restart-fixture.test-support.js";
+
+describe("模块 HTTP 上传 Scope 漂移", () => {
+  test("同 Actor 从 all 收缩为 self 后不能读取、续传或完成旧会话", async () => {
+    let currentActor = restartActor("all");
+    const storage = createStorageRuntime({}, undefined, [restartUploadPolicy]);
+    const { app } = await createRestartHttpServer(storage, () => currentActor);
+    const payload = new TextEncoder().encode("abc");
+    const created = await app.handle(
+      new Request("http://localhost/api/evidence/uploads", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          filename: "evidence.txt",
+          mimeType: "text/plain",
+          expectedByteSize: payload.byteLength,
+        }),
+      }),
+    );
+    expect(created.status).toBe(200);
+    const session = (await created.json()) as { id: string };
+
+    currentActor = restartActor("self");
+    const resumed = await app.handle(
+      new Request(`http://localhost/api/evidence/uploads/${session.id}`),
+    );
+    expect(resumed.status).toBe(403);
+    await expect(resumed.json()).resolves.toMatchObject({
+      error: "UPLOAD_FORBIDDEN",
+    });
+
+    let cancelled = false;
+    const part = await app.handle(
+      new Request(
+        `http://localhost/api/evidence/uploads/${session.id}/parts/0?offset=0&size=3&sha256=${"0".repeat(64)}`,
+        {
+          method: "PUT",
+          body: new ReadableStream<Uint8Array>({
+            cancel() {
+              cancelled = true;
+            },
+          }),
+        },
+      ),
+    );
+    expect(part.status).toBe(403);
+    expect(cancelled).toBe(true);
+
+    const completed = await app.handle(
+      new Request(
+        `http://localhost/api/evidence/uploads/${session.id}/complete`,
+        { method: "POST" },
+      ),
+    );
+    expect(completed.status).toBe(403);
+    expect(await storage.repository.listParts(session.id)).toEqual([]);
+    expect(await storage.repository.getSession(session.id)).toMatchObject({
+      status: "uploading",
+      receivedByteSize: 0,
+    });
+  });
+});

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

@@ -6,10 +6,15 @@ import type {
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { isServerScopeContext } from "../data-access/context.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
 import { auditActor, 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 type {
+  ModuleStorageScope,
+  ModuleUploadDecision,
+} from "./storage-port.js";
+import type { ModuleUploadPolicy } from "@southwind-ai/server-sdk";
 import { toModuleActor } from "./request-context.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
@@ -17,21 +22,35 @@ type ServerRuntime = ReturnType<typeof createServerRuntime>;
 export interface ModuleStorageScopeInput {
   readonly moduleName: string;
   readonly purposes: ReadonlySet<string>;
+  readonly uploadPolicies?: readonly ModuleUploadPolicy[];
   readonly resourceFileAccessPolicies: readonly ModuleResourceFileAccessPolicy[];
   readonly guardContext: RequestGuardContext;
   readonly runtime: ServerRuntime;
   readonly features: readonly FeatureFlagDefinition[];
   readonly signal: AbortSignal;
+  readonly uploadAuditMetadata?: Readonly<Record<string, string | number>>;
 }
 
 export function createModuleStorageScope(
   input: ModuleStorageScopeInput,
 ): ModuleStorageScope {
   const actor = toModuleActor(input.guardContext.actor);
+  const scopeContext = input.guardContext.actor.scopeContext;
+  const authorizationBinding =
+    isServerScopeContext(scopeContext) && scopeContext.actorId === actor.id
+      ? {
+          moduleName: input.moduleName,
+          scopeHash: captureAuthorizationScope(scopeContext).hash,
+        }
+      : undefined;
   return {
     moduleName: input.moduleName,
     ownerId: actor.id,
     purposes: input.purposes,
+    uploadPolicies: new Map(
+      (input.uploadPolicies ?? []).map((policy) => [policy.purpose, policy]),
+    ),
+    authorizationBinding,
     actor,
     requestId: input.guardContext.requestId,
     signal: input.signal,
@@ -60,6 +79,38 @@ export function createModuleStorageScope(
         resourceFileEvent(input, policy, request, outcome),
       );
     },
+    recordUploadDecision(decision) {
+      input.runtime.auditSink.recordEvent(uploadEvent(input, decision));
+    },
+    uploadAuditMetadata: input.uploadAuditMetadata,
+  };
+}
+
+function uploadEvent(
+  input: ModuleStorageScopeInput,
+  decision: ModuleUploadDecision,
+) {
+  return {
+    id: randomUUIDv7(),
+    action: decision.action,
+    outcome: decision.outcome,
+    actor: auditActor(input.guardContext),
+    ...(decision.targetId
+      ? {
+          target: {
+            type: "module-storage-upload",
+            id: decision.targetId,
+          },
+        }
+      : {}),
+    module: input.moduleName,
+    requestId: input.guardContext.requestId,
+    metadata: {
+      ...(decision.purpose ? { purpose: decision.purpose } : {}),
+      ...input.uploadAuditMetadata,
+      ...decision.metadata,
+    },
+    occurredAt: new Date().toISOString(),
   };
 }
 

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

@@ -0,0 +1,282 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { requireModuleStorageWritePortV1 } from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+import type { RouteApp } from "../system/route-types.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { installModuleRoutes } from "./route-installer.js";
+
+describe("模块 HTTP 流式写入路由", () => {
+  test("显式关闭 body parser，并在每个请求 Guard 后下发原始流与取消信号", async () => {
+    const manifest = shopManifest();
+    let handled = 0;
+    let sawParsedBody = false;
+    let sawSignal = false;
+    const hosts = await initializeModuleHosts({
+      modules: [manifest],
+      installations: [
+        {
+          manifest,
+          setup(host) {
+            host.registerUploadPolicy(uploadPolicy());
+            host.registerRoutes([
+              {
+                method: "PUT",
+                path: "/api/shop/uploads/:id/parts/:partNumber",
+                permissionKey: "shop.upload.manage",
+                bodyMode: "stream",
+                async handler(context) {
+                  handled += 1;
+                  sawParsedBody = context.body !== undefined;
+                  sawSignal = context.signal === activeRequest?.signal;
+                  if (!context.bodyStream) throw new Error("缺少流式请求体");
+                  return requireModuleStorageWritePortV1(
+                    context,
+                  ).appendUploadPart({
+                    sessionId: String(context.params.id),
+                    partNumber: Number(context.params.partNumber),
+                    byteOffset: 0,
+                    byteSize: payload.byteLength,
+                    sha256: digest(payload),
+                    body: context.bodyStream,
+                  });
+                },
+              },
+            ]);
+          },
+        },
+      ],
+    });
+    const storage = createStorageRuntime({}, undefined, hosts.uploadPolicies);
+    const authorizedActor = actor(["shop.upload.manage"]);
+    const session = await storage.uploads.create({
+      ownerId: "user_shop",
+      purpose: "shop.upload",
+      authorizationBinding: {
+        moduleName: manifest.name,
+        scopeHash: captureAuthorizationScope(authorizedActor.scopeContext).hash,
+      },
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: payload.byteLength,
+      expectedSha256: digest(payload),
+    });
+    const runtime = createServerRuntime(
+      { NODE_ENV: "test" },
+      { featureCatalog: manifest.features },
+    );
+    const app = new StreamRouteApp();
+    installModuleRoutes(hosts, app, {
+      runtime,
+      features: manifest.features,
+      storage: { uploads: storage.uploads, files: storage.files },
+    });
+
+    expect(app.options.get("PUT /shop/uploads/:id/parts/:partNumber")).toEqual({
+      parse: "none",
+    });
+    activeRequest = requestWithBody();
+    const result = await app.invoke(
+      "PUT",
+      "/shop/uploads/:id/parts/:partNumber",
+      await routeContext(runtime, authorizedActor, session.id),
+    );
+    expect(result).toMatchObject({
+      sessionId: session.id,
+      partNumber: 0,
+      byteSize: payload.byteLength,
+    });
+    expect(sawParsedBody).toBe(false);
+    expect(sawSignal).toBe(true);
+    expect(
+      await storage.uploads.getSession(session.id, "user_shop"),
+    ).toMatchObject({
+      receivedByteSize: payload.byteLength,
+      nextPartNumber: 1,
+    });
+
+    let deniedCancelled = false;
+    activeRequest = requestWithBody(() => {
+      deniedCancelled = true;
+    });
+    const denied = (await app.invoke(
+      "PUT",
+      "/shop/uploads/:id/parts/:partNumber",
+      await routeContext(runtime, actor([]), session.id),
+    )) as Response;
+    expect(denied.status).toBe(403);
+    expect(deniedCancelled).toBe(true);
+    expect(handled).toBe(1);
+    expect(runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "security.denied",
+        outcome: "denied",
+      }),
+    );
+  });
+});
+
+const payload = new TextEncoder().encode("abc");
+let activeRequest: Request | undefined;
+
+class StreamRouteApp implements RouteApp {
+  readonly handlers = new Map<string, (context: unknown) => unknown>();
+  readonly options = new Map<string, { parse?: "none" } | undefined>();
+
+  get(path: string, handler: (context: unknown) => unknown) {
+    this.register("GET", path, handler);
+  }
+
+  post(
+    path: string,
+    handler: (context: unknown) => unknown,
+    options?: { parse?: "none" },
+  ) {
+    this.register("POST", path, handler, options);
+  }
+
+  put(
+    path: string,
+    handler: (context: unknown) => unknown,
+    options?: { parse?: "none" },
+  ) {
+    this.register("PUT", path, handler, options);
+  }
+
+  delete(path: string, handler: (context: unknown) => unknown) {
+    this.register("DELETE", path, handler);
+  }
+
+  invoke(method: string, path: string, context: unknown) {
+    const handler = this.handlers.get(`${method} ${path}`);
+    if (!handler) throw new Error(`未注册路由 ${method} ${path}`);
+    return handler(context);
+  }
+
+  private register(
+    method: string,
+    path: string,
+    handler: (context: unknown) => unknown,
+    options?: { parse?: "none" },
+  ) {
+    const key = `${method} ${path}`;
+    this.handlers.set(key, handler);
+    this.options.set(key, options);
+  }
+}
+
+async function routeContext(
+  runtime: ReturnType<typeof createServerRuntime>,
+  currentActor: RequestActor,
+  sessionId: string,
+) {
+  if (!activeRequest) throw new Error("缺少请求");
+  return {
+    guardContext: await runtime.createGuardContextForActor(
+      activeRequest,
+      currentActor,
+    ),
+    request: activeRequest,
+    params: { id: sessionId, partNumber: "0" },
+    query: {},
+    body: { shouldNotBeVisible: true },
+  };
+}
+
+function requestWithBody(onCancel?: () => void) {
+  return new Request("http://localhost/api/shop/uploads/x/parts/0", {
+    method: "PUT",
+    body: onCancel
+      ? new ReadableStream<Uint8Array>({
+          cancel: onCancel,
+        })
+      : new Blob([payload]).stream(),
+  });
+}
+
+function actor(permissionKeys: string[]): RequestActor {
+  return {
+    id: "user_shop",
+    type: "user",
+    name: "商店用户",
+    roleCodes: ["shop-user"],
+    permissionKeys,
+    scopeContext: buildScopeContext("user_shop", undefined, [
+      {
+        id: "shop-user",
+        code: "shop-user",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function uploadPolicy() {
+  return {
+    purpose: "shop.upload",
+    maxByteSize: 1024,
+    maxPartByteSize: 512,
+    sessionTtlMs: 60_000,
+    fileRetentionMs: 24 * 60 * 60_000,
+    allowedTypes: { "text/plain": ["txt"] },
+    signature: "none" as const,
+  };
+}
+
+function shopManifest(): ModuleManifest {
+  return {
+    name: "shop",
+    version: "0.1.0",
+    label: "商店",
+    description: "商店上传测试模块",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "shop.upload.manage",
+        label: "管理上传",
+        module: "shop",
+        moduleLabel: "商店",
+        resource: "upload",
+        resourceLabel: "上传",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [
+      {
+        method: "PUT",
+        path: "/api/shop/uploads/:id/parts/:partNumber",
+        permissionKey: "shop.upload.manage",
+        featureKey: "shop.upload",
+        auditAction: "crud.update",
+      },
+    ],
+    features: [
+      {
+        key: featureKey("shop.upload"),
+        label: "商店上传",
+        module: "shop",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: ["crud.update"],
+  };
+}
+
+function digest(value: Uint8Array) {
+  return createHash("sha256").update(value).digest("hex");
+}

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

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { describe, expect, test } from "bun:test";
+import type { ModuleUploadPolicy } from "@southwind-ai/server-sdk";
+import {
+  FileService,
+  InMemoryUploadRepository,
+  MemoryBlobStore,
+  UploadService,
+} from "@southwind-ai/storage";
+import type { ModuleUploadDecision } from "./storage-port.js";
+import { createModuleStorageWritePort } from "./storage-write-port.js";
+
+describe("模块 Storage Writer 错误契约", () => {
+  test("可修正错误保留稳定 code，未知异常不泄漏物理路径", async () => {
+    const repository = new InMemoryUploadRepository();
+    const blobs = new MemoryBlobStore();
+    const uploads = new UploadService({
+      repository,
+      blobStore: blobs,
+      policies: [
+        {
+          purpose: "shop.attachment",
+          maxByteSize: 1024,
+          maxPartByteSize: 512,
+          sessionTtlMs: 60_000,
+          fileRetentionMs: 24 * 60 * 60_000,
+          allowedTypes: { "text/plain": ["txt"] },
+          signature: "none",
+        },
+        {
+          purpose: "shop.image",
+          maxByteSize: 1024,
+          maxPartByteSize: 512,
+          sessionTtlMs: 60_000,
+          fileRetentionMs: 24 * 60 * 60_000,
+          allowedTypes: { "image/png": ["png"] },
+          signature: "image",
+        },
+      ],
+    });
+    const decisions: ModuleUploadDecision[] = [];
+    const writer = createModuleStorageWritePort(
+      { uploads, files: new FileService(repository, blobs) },
+      {
+        moduleName: "shop",
+        ownerId: "user_shop",
+        purposes: new Set(["shop.attachment", "shop.image"]),
+        uploadPolicies: new Map<string, ModuleUploadPolicy>([
+          [
+            "shop.attachment",
+            {
+              purpose: "shop.attachment",
+              maxByteSize: 1024,
+              maxPartByteSize: 512,
+              sessionTtlMs: 60_000,
+              fileRetentionMs: 24 * 60 * 60_000,
+              allowedTypes: { "text/plain": ["txt"] },
+            },
+          ],
+          [
+            "shop.image",
+            {
+              purpose: "shop.image",
+              maxByteSize: 1024,
+              maxPartByteSize: 512,
+              sessionTtlMs: 60_000,
+              fileRetentionMs: 24 * 60 * 60_000,
+              allowedTypes: { "image/png": ["png"] },
+            },
+          ],
+        ]),
+        authorizationBinding: {
+          moduleName: "shop",
+          scopeHash: "a".repeat(64),
+        },
+        actor: {
+          id: "user_shop",
+          type: "user",
+          name: "商店用户",
+          roleCodes: ["shop-user"],
+          permissionKeys: ["shop.item.manage"],
+        },
+        requestId: "request_shop",
+        signal: new AbortController().signal,
+        recordUploadDecision: (decision) => decisions.push(decision),
+      },
+    );
+    const body = new TextEncoder().encode("abc");
+    const session = await writer.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: body.byteLength,
+    });
+
+    await expect(
+      writer.appendUploadPart({
+        ...partInput(session.id, body),
+        sha256: "invalid",
+      }),
+    ).rejects.toMatchObject({
+      name: "ModuleStorageError",
+      code: "INVALID_UPLOAD",
+    });
+    blobs.put = async () => {
+      const failure = new Error(
+        "open /private/storage/blob.partial",
+      ) as Error & {
+        path: string;
+      };
+      failure.path = "/private/storage/blob.partial";
+      throw failure;
+    };
+    let cancelled = false;
+    const failedPart = {
+      ...partInput(session.id, body),
+      body: new ReadableStream<Uint8Array>({
+        pull(controller) {
+          controller.enqueue(body);
+        },
+        cancel() {
+          cancelled = true;
+        },
+      }),
+    };
+
+    await expect(writer.appendUploadPart(failedPart)).rejects.toMatchObject({
+      name: "ModuleStorageError",
+      code: "STORAGE_WRITE_FAILED",
+      message: "存储写入失败",
+    });
+    expect(cancelled).toBe(true);
+
+    const image = Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]);
+    const imageSession = await writer.createUploadSession({
+      purpose: "shop.image",
+      filename: "a.png",
+      mimeType: "image/png",
+      expectedByteSize: image.byteLength,
+    });
+    let imageCancelled = false;
+    await expect(
+      writer.appendUploadPart({
+        ...partInput(imageSession.id, image),
+        body: new ReadableStream<Uint8Array>({
+          pull(controller) {
+            controller.enqueue(image);
+          },
+          cancel() {
+            imageCancelled = true;
+          },
+        }),
+      }),
+    ).rejects.toMatchObject({ code: "STORAGE_WRITE_FAILED" });
+    expect(imageCancelled).toBe(true);
+    expect(JSON.stringify(decisions)).not.toContain("/private/storage");
+  });
+});
+
+function partInput(sessionId: string, value: Uint8Array) {
+  return {
+    sessionId,
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: value.byteLength,
+    sha256: createHash("sha256").update(value).digest("hex"),
+    body: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(value);
+        controller.close();
+      },
+    }),
+  };
+}

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

@@ -0,0 +1,62 @@
+import {
+  ModuleStorageError,
+  type ModuleStorageErrorCode,
+} from "@southwind-ai/server-sdk";
+import {
+  BlobStoreError,
+  UploadError,
+  type UploadErrorCode,
+} from "@southwind-ai/storage";
+
+const uploadErrorCodes: Readonly<
+  Record<UploadErrorCode, ModuleStorageErrorCode>
+> = {
+  INVALID_UPLOAD: "INVALID_UPLOAD",
+  UNSUPPORTED_FILE_TYPE: "UNSUPPORTED_FILE_TYPE",
+  UPLOAD_TOO_LARGE: "UPLOAD_TOO_LARGE",
+  PART_TOO_LARGE: "PART_TOO_LARGE",
+  UPLOAD_NOT_FOUND: "UPLOAD_FORBIDDEN",
+  UPLOAD_FORBIDDEN: "UPLOAD_FORBIDDEN",
+  UPLOAD_NOT_ACTIVE: "UPLOAD_NOT_ACTIVE",
+  UPLOAD_EXPIRED: "UPLOAD_EXPIRED",
+  UPLOAD_OFFSET_CONFLICT: "UPLOAD_OFFSET_CONFLICT",
+  UPLOAD_INCOMPLETE: "UPLOAD_INCOMPLETE",
+  UPLOAD_CANCELLED: "UPLOAD_CANCELLED",
+  FILE_SIGNATURE_MISMATCH: "FILE_SIGNATURE_MISMATCH",
+  CONCURRENT_UPLOAD: "CONCURRENT_UPLOAD",
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  FILE_EXPIRED: "FILE_EXPIRED",
+  FILE_CONTENT_MISSING: "FILE_CONTENT_MISSING",
+};
+
+export function toModuleStorageError(error: unknown): ModuleStorageError {
+  if (error instanceof ModuleStorageError) return error;
+  if (error instanceof UploadError) {
+    if (
+      error.code === "UPLOAD_NOT_FOUND" ||
+      error.code === "UPLOAD_FORBIDDEN"
+    ) {
+      return forbiddenStorageSession();
+    }
+    return new ModuleStorageError(uploadErrorCodes[error.code], error.message);
+  }
+  if (error instanceof BlobStoreError) {
+    if (error.code === "INVALID_CONTENT_HASH") {
+      return new ModuleStorageError("INVALID_UPLOAD", "SHA-256 格式无效");
+    }
+    if (error.code === "SIZE_MISMATCH" || error.code === "HASH_MISMATCH") {
+      return new ModuleStorageError(error.code, error.message);
+    }
+  }
+  return new ModuleStorageError("STORAGE_WRITE_FAILED", "存储写入失败");
+}
+
+export function forbiddenStorageSession(): ModuleStorageError {
+  return new ModuleStorageError("UPLOAD_FORBIDDEN", "上传会话未授权");
+}
+
+export function isStorageAuthorizationError(error: unknown): boolean {
+  return (
+    error instanceof ModuleStorageError && error.code === "UPLOAD_FORBIDDEN"
+  );
+}