create-windy 0.5.1 → 0.6.0

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

@@ -0,0 +1,323 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import {
+  FileService,
+  InMemoryUploadRepository,
+  MemoryBlobStore,
+  UploadService,
+  type UploadPolicy,
+} from "@southwind-ai/storage";
+import type { ModuleUploadDecision } from "./storage-port.js";
+import { createModuleStorageWritePort } from "./storage-write-port.js";
+
+const policies: UploadPolicy[] = [
+  policy("shop.attachment"),
+  policy("other.attachment"),
+];
+
+describe("模块受治理流式 Storage Writer", () => {
+  test("投影安全 DTO、复用分片校验并幂等完成", async () => {
+    const fixture = setup();
+    const body = bytes("abcdef");
+    const session = await fixture.writer.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "说明.txt",
+      mimeType: "text/plain",
+      expectedByteSize: body.byteLength,
+      expectedSha256: digest(body),
+    });
+
+    const part = await fixture.writer.appendUploadPart({
+      sessionId: session.id,
+      partNumber: 0,
+      byteOffset: 0,
+      byteSize: body.byteLength,
+      sha256: digest(body),
+      body: stream(body),
+    });
+    const first = await fixture.writer.completeUpload(session.id);
+    const replay = await fixture.writer.completeUpload(session.id);
+
+    expect(part).toMatchObject({
+      sessionId: session.id,
+      partNumber: 0,
+      byteSize: body.byteLength,
+      sha256: digest(body),
+    });
+    expect(first).toEqual(replay);
+    expect(fixture.blobs.size).toBe(1);
+    expect(await fixture.repository.getFile(first.id)).toMatchObject({
+      ownerId: "user_shop",
+      purpose: "shop.attachment",
+    });
+    expect("ownerId" in session).toBe(false);
+    expect("artifactRef" in part).toBe(false);
+    expect("artifactRef" in first).toBe(false);
+    expect(fixture.decisions.map(({ action }) => action)).toEqual([
+      "file.upload.create",
+      "file.upload.part.write",
+      "file.upload.complete",
+      "file.upload.complete",
+    ]);
+    expect(fixture.decisions.at(-1)?.metadata).toMatchObject({
+      replayed: true,
+    });
+    const auditJson = JSON.stringify(fixture.decisions);
+    expect(auditJson).not.toContain("说明.txt");
+    expect(auditJson).not.toContain("ownerId");
+    expect(auditJson).not.toContain("artifactRef");
+  });
+
+  test("同 Actor 跨 purpose、跨 Owner 与注册漂移同形拒绝", async () => {
+    const fixture = setup();
+    const body = bytes("abc");
+    const otherPurpose = await fixture.uploads.create({
+      ownerId: "user_shop",
+      purpose: "other.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: body.byteLength,
+    });
+    const otherOwner = await fixture.uploads.create({
+      ownerId: "user_other",
+      purpose: "shop.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: body.byteLength,
+    });
+
+    for (const sessionId of [
+      otherPurpose.id,
+      otherOwner.id,
+      "upload_unknown",
+    ]) {
+      await expect(
+        fixture.writer.appendUploadPart({
+          sessionId,
+          partNumber: 0,
+          byteOffset: 0,
+          byteSize: body.byteLength,
+          sha256: digest(body),
+          body: stream(body),
+        }),
+      ).rejects.toMatchObject({
+        code: "UPLOAD_FORBIDDEN",
+        message: "上传会话未授权",
+      });
+    }
+
+    const allowed = await fixture.writer.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: body.byteLength,
+    });
+    const drifted = setup({
+      repository: fixture.repository,
+      blobs: fixture.blobs,
+      purposes: [],
+    });
+    await expect(
+      drifted.writer.getUploadSession(allowed.id),
+    ).rejects.toMatchObject({ code: "UPLOAD_FORBIDDEN" });
+    expect(
+      [...fixture.decisions, ...drifted.decisions].filter(
+        ({ outcome }) => outcome === "denied",
+      ),
+    ).toHaveLength(4);
+    expect(drifted.decisions.at(-1)).toMatchObject({
+      action: "security.denied",
+      metadata: { reason: "upload-session-scope" },
+    });
+  });
+
+  test("Context 取消停止拉流且不提交分片，显式 abort 清理会话", async () => {
+    const controller = new AbortController();
+    const fixture = setup({ signal: controller.signal });
+    const session = await fixture.writer.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: 6,
+    });
+    let pulls = 0;
+    let cancelled = false;
+    let secondPull!: () => void;
+    const secondPullStarted = new Promise<void>((resolve) => {
+      secondPull = resolve;
+    });
+    let releaseSecond!: () => void;
+    const secondGate = new Promise<void>((resolve) => {
+      releaseSecond = resolve;
+    });
+    const body = new ReadableStream<Uint8Array>({
+      async pull(streamController) {
+        pulls += 1;
+        if (pulls === 1) {
+          streamController.enqueue(bytes("abc"));
+          return;
+        }
+        secondPull();
+        await secondGate;
+      },
+      cancel() {
+        cancelled = true;
+        releaseSecond();
+      },
+    });
+    const appending = fixture.writer.appendUploadPart({
+      sessionId: session.id,
+      partNumber: 0,
+      byteOffset: 0,
+      byteSize: 6,
+      sha256: digest(bytes("abcdef")),
+      body,
+    });
+    await secondPullStarted;
+    controller.abort(new DOMException("请求已取消", "AbortError"));
+
+    await expect(appending).rejects.toMatchObject({
+      code: "UPLOAD_CANCELLED",
+    });
+    expect(cancelled).toBe(true);
+    expect(pulls).toBe(2);
+    expect(await fixture.repository.listParts(session.id)).toEqual([]);
+    expect(fixture.blobs.size).toBe(0);
+
+    await expect(fixture.writer.abortUpload(session.id)).rejects.toMatchObject({
+      code: "UPLOAD_CANCELLED",
+    });
+    expect((await fixture.repository.getSession(session.id))?.status).toBe(
+      "uploading",
+    );
+
+    const cleanup = setup({
+      repository: fixture.repository,
+      blobs: fixture.blobs,
+    });
+    const aborted = await cleanup.writer.abortUpload(session.id);
+    expect(aborted.status).toBe("aborted");
+    expect(cleanup.decisions.at(-1)).toMatchObject({
+      action: "file.upload.abort",
+      outcome: "success",
+    });
+  });
+
+  test("终态摘要失败不发布文件，abort 与 TTL 均清理已提交 part", async () => {
+    let now = new Date("2026-07-31T00:00:00.000Z");
+    const fixture = setup({ now: () => now });
+    const body = bytes("abc");
+    const session = await fixture.writer.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "a.txt",
+      mimeType: "text/plain",
+      expectedByteSize: body.byteLength,
+      expectedSha256: "0".repeat(64),
+    });
+    await fixture.writer.appendUploadPart(partInput(session.id, body));
+    await expect(
+      fixture.writer.completeUpload(session.id),
+    ).rejects.toMatchObject({ code: "HASH_MISMATCH" });
+    expect(fixture.blobs.size).toBe(1);
+    await fixture.writer.abortUpload(session.id);
+    expect(fixture.blobs.size).toBe(0);
+
+    const expiring = await fixture.writer.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "b.txt",
+      mimeType: "text/plain",
+      expectedByteSize: 6,
+    });
+    await fixture.writer.appendUploadPart(partInput(expiring.id, body));
+    now = new Date("2026-07-31T00:02:00.000Z");
+    await fixture.uploads.cleanupExpired();
+    expect(await fixture.repository.getSession(expiring.id)).toBeUndefined();
+    expect(fixture.blobs.size).toBe(0);
+  });
+});
+
+interface SetupOptions {
+  repository?: InMemoryUploadRepository;
+  blobs?: MemoryBlobStore;
+  purposes?: string[];
+  moduleName?: string;
+  scopeHash?: string;
+  signal?: AbortSignal;
+  now?: () => Date;
+}
+
+function setup(options: SetupOptions = {}) {
+  const repository = options.repository ?? new InMemoryUploadRepository();
+  const blobs = options.blobs ?? new MemoryBlobStore();
+  const uploads = new UploadService({
+    repository,
+    blobStore: blobs,
+    policies,
+    now: options.now,
+  });
+  const decisions: ModuleUploadDecision[] = [];
+  const writer = createModuleStorageWritePort(
+    { uploads, files: new FileService(repository, blobs) },
+    {
+      moduleName: options.moduleName ?? "shop",
+      ownerId: "user_shop",
+      purposes: new Set(options.purposes ?? ["shop.attachment"]),
+      uploadPolicies: new Map(policies.map((entry) => [entry.purpose, entry])),
+      authorizationBinding: {
+        moduleName: options.moduleName ?? "shop",
+        scopeHash: options.scopeHash ?? "a".repeat(64),
+      },
+      actor: {
+        id: "user_shop",
+        type: "user",
+        name: "商店用户",
+        roleCodes: ["shop-user"],
+        permissionKeys: ["shop.item.manage"],
+      },
+      requestId: "request_shop",
+      signal: options.signal ?? new AbortController().signal,
+      recordUploadDecision: (decision) => decisions.push(decision),
+    },
+  );
+  return { repository, blobs, uploads, writer, decisions };
+}
+
+function policy(purpose: string): UploadPolicy {
+  return {
+    purpose,
+    maxByteSize: 1024,
+    maxPartByteSize: 512,
+    sessionTtlMs: 60_000,
+    fileRetentionMs: 24 * 60 * 60_000,
+    allowedTypes: { "text/plain": ["txt"] },
+    signature: "none",
+  };
+}
+
+function partInput(sessionId: string, body: Uint8Array) {
+  return {
+    sessionId,
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: body.byteLength,
+    sha256: digest(body),
+    body: stream(body),
+  };
+}
+
+function stream(value: Uint8Array) {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(value);
+      controller.close();
+    },
+  });
+}
+
+function bytes(value: string) {
+  return new TextEncoder().encode(value);
+}
+
+function digest(value: Uint8Array) {
+  return createHash("sha256").update(value).digest("hex");
+}

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

@@ -0,0 +1,320 @@
+import {
+  ModuleStorageError,
+  type ModuleStorageWritePortV1,
+} from "@southwind-ai/server-sdk";
+import {
+  UploadError,
+  throwIfUploadCancelled,
+  type UploadPart,
+  type UploadSession,
+} from "@southwind-ai/storage";
+import {
+  projectFile,
+  projectUploadSession,
+  requireModulePurpose,
+  type ModuleStorageScope,
+  type ModuleStorageServices,
+  type ModuleUploadDecision,
+} from "./storage-port.js";
+import {
+  forbiddenStorageSession,
+  isStorageAuthorizationError,
+  toModuleStorageError,
+} from "./storage-write-error.js";
+
+interface MutableAuditContext {
+  targetId?: string;
+  purpose?: string;
+  metadata?: Record<string, string | number | boolean>;
+}
+
+/**
+ * 把平台 UploadService 的持久会话生命周期投影为模块 writer。
+ *
+ * 输入只接受不透明 session ID、顺序/偏移、声明大小/SHA 与 Web Stream；
+ * Owner、模块范围、取消 Signal 和审计全部来自 Host scope。
+ */
+export function createModuleStorageWritePort(
+  services: ModuleStorageServices,
+  scope: ModuleStorageScope,
+): ModuleStorageWritePortV1 {
+  return {
+    createUploadSession(input) {
+      const audit: MutableAuditContext = {};
+      return executeAudited(scope, "file.upload.create", audit, async () => {
+        requireModulePurpose(scope, input.purpose);
+        audit.purpose = input.purpose;
+        const session = await services.uploads.create({
+          ownerId: scope.ownerId,
+          purpose: input.purpose,
+          authorizationBinding: scope.authorizationBinding,
+          filename: input.filename,
+          mimeType: input.mimeType,
+          expectedByteSize: input.expectedByteSize,
+          expectedSha256: input.expectedSha256,
+          fileRetentionMs: requireFileRetentionMs(scope, input.purpose),
+        });
+        audit.targetId = safeUploadAuditTarget(session.id);
+        audit.metadata = {
+          expectedByteSize: session.expectedByteSize,
+          ...(session.expectedContentHash
+            ? { expectedSha256: session.expectedContentHash.value }
+            : {}),
+        };
+        return projectUploadSession(session);
+      });
+    },
+    async getUploadSession(sessionId) {
+      try {
+        return await executeWithoutAudit(scope, async () => {
+          const session = await requireScopedSession(
+            services,
+            scope,
+            sessionId,
+          );
+          if (session.status === "completed") {
+            return projectUploadSession(session);
+          }
+          if (session.status === "expired") {
+            throw new UploadError("UPLOAD_EXPIRED", "上传会话已过期");
+          }
+          if (session.status !== "uploading") {
+            throw new UploadError("UPLOAD_NOT_ACTIVE", "上传会话不可继续操作");
+          }
+          return projectUploadSession(
+            await services.uploads.getSession(sessionId, scope.ownerId),
+          );
+        });
+      } catch (error) {
+        if (isStorageAuthorizationError(error)) {
+          record(scope, {
+            action: "security.denied",
+            outcome: "denied",
+            targetId: safeUploadAuditTarget(sessionId),
+            metadata: { reason: "upload-session-scope" },
+          });
+        }
+        throw error;
+      }
+    },
+    async appendUploadPart(input) {
+      const audit: MutableAuditContext = {
+        targetId: safeUploadAuditTarget(input.sessionId),
+      };
+      try {
+        return await executeAudited(
+          scope,
+          "file.upload.part.write",
+          audit,
+          async () => {
+            const session = await requireScopedSession(
+              services,
+              scope,
+              input.sessionId,
+            );
+            audit.purpose = session.purpose;
+            const part = await services.uploads.appendPart({
+              sessionId: input.sessionId,
+              ownerId: scope.ownerId,
+              partNumber: input.partNumber,
+              byteOffset: input.byteOffset,
+              byteSize: input.byteSize,
+              sha256: input.sha256,
+              body: input.body,
+              signal: scope.signal,
+            });
+            audit.metadata = {
+              partNumber: part.partNumber,
+              byteOffset: part.byteOffset,
+              byteSize: part.byteSize,
+              sha256: part.contentHash.value,
+            };
+            return projectPart(part);
+          },
+        );
+      } catch (error) {
+        await input.body.cancel(error).catch(() => undefined);
+        throw error;
+      }
+    },
+    completeUpload(sessionId) {
+      const audit: MutableAuditContext = {
+        targetId: safeUploadAuditTarget(sessionId),
+      };
+      return executeAudited(scope, "file.upload.complete", audit, async () => {
+        const session = await requireScopedSession(services, scope, sessionId);
+        audit.purpose = session.purpose;
+        if (session.status === "completed") {
+          audit.metadata = { replayed: true };
+        }
+        const file = await services.uploads.complete(
+          sessionId,
+          scope.ownerId,
+          scope.signal,
+        );
+        audit.targetId = safeFileAuditTarget(file.id);
+        audit.metadata = {
+          ...audit.metadata,
+          byteSize: file.byteSize,
+          sha256: file.contentHash.value,
+        };
+        return projectFile(file);
+      });
+    },
+    abortUpload(sessionId) {
+      const audit: MutableAuditContext = {
+        targetId: safeUploadAuditTarget(sessionId),
+      };
+      return executeAudited(scope, "file.upload.abort", audit, async () => {
+        const session = await requireScopedSession(services, scope, sessionId);
+        audit.purpose = session.purpose;
+        if (session.status !== "uploading") {
+          audit.metadata = { replayed: true };
+        }
+        await services.uploads.abort(sessionId, scope.ownerId, scope.signal);
+        return projectUploadSession(
+          await services.uploads.inspectSession(sessionId, scope.ownerId),
+        );
+      });
+    },
+  };
+}
+
+async function requireScopedSession(
+  services: ModuleStorageServices,
+  scope: ModuleStorageScope,
+  sessionId: string,
+): Promise<UploadSession> {
+  let session: UploadSession;
+  try {
+    session = await services.uploads.inspectSession(sessionId, scope.ownerId);
+  } catch (error) {
+    throw toModuleStorageError(error);
+  }
+  try {
+    requireModulePurpose(scope, session.purpose);
+    if (
+      !scope.authorizationBinding ||
+      session.authorizationBinding?.moduleName !==
+        scope.authorizationBinding.moduleName ||
+      session.authorizationBinding.scopeHash !==
+        scope.authorizationBinding.scopeHash
+    ) {
+      throw forbiddenStorageSession();
+    }
+  } catch {
+    throw forbiddenStorageSession();
+  }
+  return session;
+}
+
+function requireFileRetentionMs(
+  scope: ModuleStorageScope,
+  purpose: string,
+): number {
+  const retention = scope.uploadPolicies?.get(purpose)?.fileRetentionMs;
+  if (
+    retention === undefined ||
+    !Number.isSafeInteger(retention) ||
+    retention < 60_000 ||
+    retention > 365 * 24 * 60 * 60_000
+  ) {
+    throw new ModuleStorageError(
+      "STORAGE_UNAVAILABLE",
+      `模块 ${scope.moduleName} 的用途 ${purpose} 未配置有效文件保留期`,
+    );
+  }
+  return retention;
+}
+
+async function executeWithoutAudit<T>(
+  scope: ModuleStorageScope,
+  operation: () => Promise<T>,
+): Promise<T> {
+  try {
+    requireWriteBoundary(scope);
+    throwIfUploadCancelled(scope.signal);
+    return await operation();
+  } catch (error) {
+    throw toModuleStorageError(error);
+  }
+}
+
+async function executeAudited<T>(
+  scope: ModuleStorageScope,
+  action: ModuleUploadDecision["action"],
+  audit: MutableAuditContext,
+  operation: () => Promise<T>,
+): Promise<T> {
+  try {
+    requireWriteBoundary(scope);
+    throwIfUploadCancelled(scope.signal);
+    const value = await operation();
+    record(scope, {
+      action,
+      outcome: "success",
+      targetId: audit.targetId,
+      purpose: audit.purpose,
+      metadata: audit.metadata,
+    });
+    return value;
+  } catch (error) {
+    const normalized = toModuleStorageError(error);
+    record(scope, {
+      action,
+      outcome: isStorageAuthorizationError(normalized) ? "denied" : "failure",
+      targetId: audit.targetId,
+      purpose: audit.purpose,
+      metadata: {
+        ...audit.metadata,
+        errorCode: normalized.code,
+      },
+    });
+    throw normalized;
+  }
+}
+
+function requireWriteBoundary(scope: ModuleStorageScope): void {
+  if (
+    !scope.actor ||
+    !scope.requestId ||
+    !scope.signal ||
+    !scope.recordUploadDecision ||
+    !scope.authorizationBinding
+  ) {
+    throw new ModuleStorageError(
+      "STORAGE_UNAVAILABLE",
+      `模块 ${scope.moduleName} 的存储 Writer 治理边界未挂载`,
+    );
+  }
+}
+
+function safeUploadAuditTarget(value: string): string | undefined {
+  return /^upload_[0-9a-f]{32}$/.test(value) ? value : undefined;
+}
+
+function safeFileAuditTarget(value: string): string | undefined {
+  return /^file_[0-9a-f]{32}$/.test(value) ? value : undefined;
+}
+
+function record(
+  scope: ModuleStorageScope,
+  decision: ModuleUploadDecision,
+): void {
+  try {
+    scope.recordUploadDecision?.(decision);
+  } catch {
+    // 上传动作属于普通审计；可靠写入器负责降级与告警，不反转已提交的存储事实。
+  }
+}
+
+function projectPart(part: UploadPart) {
+  return {
+    sessionId: part.sessionId,
+    partNumber: part.partNumber,
+    byteOffset: part.byteOffset,
+    byteSize: part.byteSize,
+    sha256: part.contentHash.value,
+    createdAt: part.createdAt,
+  };
+}

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

@@ -0,0 +1,21 @@
+import {
+  ModuleStorageError,
+  type ModuleStorageWritePortV1,
+} from "@southwind-ai/server-sdk";
+export function unavailableModuleStorageWritePort(
+  moduleName: string,
+): ModuleStorageWritePortV1 {
+  const fail = async (): Promise<never> => {
+    throw new ModuleStorageError(
+      "STORAGE_UNAVAILABLE",
+      `模块 ${moduleName} 的存储 Writer 未挂载`,
+    );
+  };
+  return {
+    createUploadSession: () => fail(),
+    getUploadSession: () => fail(),
+    appendUploadPart: () => fail(),
+    completeUpload: () => fail(),
+    abortUpload: () => fail(),
+  };
+}