create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/module-host/secret-bindings.ts

@@ -0,0 +1,184 @@
+import type {
+  ModuleManifest,
+  ModuleSecretDefinition,
+} from "@southwind-ai/modules";
+import type { ModuleSecretBinding } from "@southwind-ai/server-sdk";
+import { isStableKey, requireStableModuleKey } from "@southwind-ai/shared";
+import { isProxy } from "node:util/types";
+
+const bindingFields = new Set([
+  "moduleName",
+  "handle",
+  "connection",
+  "purpose",
+  "resolve",
+]);
+
+export function validateModuleSecretBindings(
+  manifests: readonly ModuleManifest[],
+  bindings: readonly ModuleSecretBinding[],
+  declarationsByModule: ReadonlyMap<string, readonly ModuleSecretDefinition[]>,
+): ReadonlyMap<string, readonly ModuleSecretBinding[]> {
+  const manifestsByName = new Map(
+    manifests.map((manifest) => [manifest.name, manifest]),
+  );
+  const byModule = new Map<string, ModuleSecretBinding[]>();
+  const keys = new Set<string>();
+
+  for (const candidate of bindings) {
+    const binding = snapshotBinding(candidate);
+    if (!isStableKey(binding.moduleName)) {
+      throw new Error("模块 Secret 绑定 moduleName 非法");
+    }
+    const manifest = manifestsByName.get(binding.moduleName);
+    if (!manifest) {
+      throw new Error("模块 Secret 绑定引用了未安装模块");
+    }
+    try {
+      requireStableModuleKey(
+        "Secret handle",
+        binding.handle,
+        binding.moduleName,
+      );
+      requireStableModuleKey(
+        "Secret connection",
+        binding.connection,
+        binding.moduleName,
+      );
+      requireStableModuleKey(
+        "Secret purpose",
+        binding.purpose,
+        binding.moduleName,
+      );
+    } catch {
+      throw new Error("模块 Secret 绑定逻辑标识非法");
+    }
+    const key = bindingKey(binding);
+    if (keys.has(key)) {
+      throw new Error(`模块 Secret 绑定重复：${binding.handle}`);
+    }
+    if (
+      !hasDeclaration(declarationsByModule.get(manifest.name) ?? [], binding)
+    ) {
+      throw new Error("模块 Secret 绑定未在 Manifest 声明");
+    }
+    keys.add(key);
+    const moduleBindings = byModule.get(binding.moduleName) ?? [];
+    moduleBindings.push(binding);
+    byModule.set(binding.moduleName, moduleBindings);
+  }
+
+  return new Map(
+    [...byModule].map(([moduleName, moduleBindings]) => [
+      moduleName,
+      Object.freeze([...moduleBindings]),
+    ]),
+  );
+}
+
+function hasDeclaration(
+  declarations: readonly ModuleSecretDefinition[],
+  binding: ModuleSecretBinding,
+): boolean {
+  for (let index = 0; index < declarations.length; index += 1) {
+    const declaration = declarations[index];
+    if (declaration && sameSecret(declaration, binding)) return true;
+  }
+  return false;
+}
+
+function snapshotBinding(candidate: unknown): ModuleSecretBinding {
+  try {
+    if (!candidate || typeof candidate !== "object" || isProxy(candidate)) {
+      invalidBinding();
+    }
+    const prototype = Object.getPrototypeOf(candidate);
+    if (prototype !== Object.prototype && prototype !== null) {
+      invalidBinding();
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(candidate);
+    const keys = Reflect.ownKeys(descriptors);
+    if (
+      keys.length !== bindingFields.size ||
+      keys.some((key) => typeof key !== "string" || !bindingFields.has(key))
+    ) {
+      invalidBinding();
+    }
+    const moduleName = stringValue(descriptors.moduleName);
+    const handle = stringValue(descriptors.handle);
+    const connection = stringValue(descriptors.connection);
+    const purpose = stringValue(descriptors.purpose);
+    const resolveValue = dataValue(descriptors.resolve);
+    if (typeof resolveValue !== "function" || isProxy(resolveValue)) {
+      invalidBinding();
+    }
+    const resolve = resolveValue as ModuleSecretBinding["resolve"];
+    const snapshot = Object.create(null) as {
+      moduleName: string;
+      handle: string;
+      connection: string;
+      purpose: string;
+      resolve: ModuleSecretBinding["resolve"];
+    };
+    Object.defineProperties(snapshot, {
+      moduleName: dataDescriptor(moduleName),
+      handle: dataDescriptor(handle),
+      connection: dataDescriptor(connection),
+      purpose: dataDescriptor(purpose),
+      resolve: dataDescriptor(() => resolve()),
+    });
+    return Object.freeze(snapshot);
+  } catch {
+    throw new Error("模块 Secret 绑定结构非法");
+  }
+}
+
+function stringValue(descriptor: PropertyDescriptor | undefined): string {
+  const value = dataValue(descriptor);
+  if (typeof value !== "string") invalidBinding();
+  return value;
+}
+
+function dataValue(descriptor: PropertyDescriptor | undefined): unknown {
+  if (
+    !descriptor ||
+    descriptor.enumerable !== true ||
+    !("value" in descriptor)
+  ) {
+    invalidBinding();
+  }
+  return descriptor.value;
+}
+
+function dataDescriptor(value: unknown): PropertyDescriptor {
+  return {
+    value,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  };
+}
+
+function invalidBinding(): never {
+  throw new Error("invalid module secret binding");
+}
+
+function bindingKey(binding: ModuleSecretBinding): string {
+  return [
+    binding.moduleName,
+    binding.handle,
+    binding.connection,
+    binding.purpose,
+  ].join("\0");
+}
+
+function sameSecret(
+  declaration: ModuleSecretDefinition,
+  binding: ModuleSecretBinding,
+): boolean {
+  return (
+    declaration.handle === binding.handle &&
+    declaration.connection === binding.connection &&
+    declaration.purpose === binding.purpose
+  );
+}

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

@@ -0,0 +1,242 @@
+import { createHash } from "node:crypto";
+import { describe, expect, test } from "bun:test";
+import {
+  FileService,
+  InMemoryUploadRepository,
+  MemoryBlobStore,
+  UploadService,
+  type UploadPolicy,
+} from "@southwind-ai/storage";
+import type { ModuleUploadDecision } from "./storage-port.js";
+import { buildScopeContext } from "../data-access/context.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { bindModuleUserProjection } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { createModuleStorageScope } from "./storage-scope.js";
+import { createModuleStorageWritePort } from "./storage-write-port.js";
+
+const policy: UploadPolicy = {
+  purpose: "shop.attachment",
+  maxByteSize: 1024,
+  maxPartByteSize: 512,
+  sessionTtlMs: 60_000,
+  fileRetentionMs: 24 * 60 * 60_000,
+  allowedTypes: { "text/plain": ["txt"] },
+  signature: "none",
+};
+const allScopeHash = "a".repeat(64);
+const selfScopeHash = "b".repeat(64);
+
+describe("模块上传会话授权绑定", () => {
+  test("同 Actor all→self、跨模块与历史无绑定会话均 fail closed", async () => {
+    const repository = new InMemoryUploadRepository();
+    const blobs = new MemoryBlobStore();
+    const original = setup(repository, blobs, {
+      moduleName: "shop",
+      scopeHash: allScopeHash,
+    });
+    const value = bytes("abc");
+    const session = await original.writer.createUploadSession({
+      purpose: policy.purpose,
+      filename: "evidence.txt",
+      mimeType: "text/plain",
+      expectedByteSize: value.byteLength,
+    });
+
+    const restarted = setup(repository, blobs, {
+      moduleName: "shop",
+      scopeHash: allScopeHash,
+    });
+    await expect(
+      restarted.writer.getUploadSession(session.id),
+    ).resolves.toMatchObject({
+      id: session.id,
+      status: "uploading",
+    });
+    expect(
+      (await repository.getSession(session.id))?.authorizationBinding,
+    ).toEqual({ moduleName: "shop", scopeHash: allScopeHash });
+
+    const drifted = setup(repository, blobs, {
+      moduleName: "shop",
+      scopeHash: selfScopeHash,
+    });
+    const driftedOperations = [
+      () => drifted.writer.getUploadSession(session.id),
+      () =>
+        drifted.writer.appendUploadPart({
+          sessionId: session.id,
+          partNumber: 0,
+          byteOffset: 0,
+          byteSize: value.byteLength,
+          sha256: digest(value),
+          body: new Blob([value]).stream(),
+        }),
+      () => drifted.writer.completeUpload(session.id),
+      () => drifted.writer.abortUpload(session.id),
+    ];
+    for (const operation of driftedOperations) {
+      await expect(operation()).rejects.toMatchObject({
+        code: "UPLOAD_FORBIDDEN",
+        message: "上传会话未授权",
+      });
+    }
+
+    const otherModule = setup(repository, blobs, {
+      moduleName: "other",
+      scopeHash: allScopeHash,
+    });
+    await expect(
+      otherModule.writer.getUploadSession(session.id),
+    ).rejects.toMatchObject({ code: "UPLOAD_FORBIDDEN" });
+
+    const legacy = await original.uploads.create({
+      ownerId: "user_shop",
+      purpose: policy.purpose,
+      filename: "legacy.txt",
+      mimeType: "text/plain",
+      expectedByteSize: value.byteLength,
+    });
+    await expect(
+      original.writer.getUploadSession(legacy.id),
+    ).rejects.toMatchObject({ code: "UPLOAD_FORBIDDEN" });
+    expect(await repository.getSession(session.id)).toMatchObject({
+      status: "uploading",
+      receivedByteSize: 0,
+    });
+  });
+
+  test("调用方文本不是合法 opaque ID 时不会进入审计 target", async () => {
+    const fixture = setup(
+      new InMemoryUploadRepository(),
+      new MemoryBlobStore(),
+      { moduleName: "shop", scopeHash: allScopeHash },
+    );
+    const hostile =
+      "/private/storage?next=https://attacker.invalid\nAuthorization: Bearer secret";
+    const operations = [
+      () => fixture.writer.getUploadSession(hostile),
+      () => fixture.writer.completeUpload(hostile),
+      () => fixture.writer.abortUpload(hostile),
+      () =>
+        fixture.writer.appendUploadPart({
+          sessionId: hostile,
+          partNumber: 0,
+          byteOffset: 0,
+          byteSize: 3,
+          sha256: "0".repeat(64),
+          body: new Blob(["abc"]).stream(),
+        }),
+    ];
+    for (const operation of operations) {
+      await expect(operation()).rejects.toMatchObject({
+        code: "UPLOAD_FORBIDDEN",
+      });
+    }
+    await expect(
+      fixture.writer.getUploadSession("file_11111111111111111111111111111111"),
+    ).rejects.toMatchObject({ code: "UPLOAD_FORBIDDEN" });
+
+    const auditJson = JSON.stringify(fixture.decisions);
+    expect(auditJson).not.toContain("/private/storage");
+    expect(auditJson).not.toContain("attacker.invalid");
+    expect(auditJson).not.toContain("Bearer");
+    expect(
+      fixture.decisions.every(({ targetId }) => targetId === undefined),
+    ).toBe(true);
+  });
+
+  test("Host 投影 service actor 时仍以业务用户 Scope 颁发绑定", async () => {
+    const scopeContext = buildScopeContext("user_projected", undefined, [
+      {
+        id: "role-projected",
+        code: "projected",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]);
+    const actor = bindModuleUserProjection(
+      {
+        id: "service_adk_debug",
+        type: "service",
+        name: "调试服务",
+        roleCodes: ["adk-debug"],
+        permissionKeys: ["shop.upload.manage"],
+        scopeContext,
+      },
+      "user_projected",
+    );
+    const runtime = createServerRuntime({ NODE_ENV: "test" });
+    const request = new Request("http://localhost/api/shop/uploads");
+    const guardContext = await runtime.createGuardContextForActor(
+      request,
+      actor,
+    );
+    const scope = createModuleStorageScope({
+      moduleName: "shop",
+      purposes: new Set([policy.purpose]),
+      uploadPolicies: [policy],
+      resourceFileAccessPolicies: [],
+      guardContext,
+      runtime,
+      features: [],
+      signal: request.signal,
+    });
+
+    expect(scope.ownerId).toBe("user_projected");
+    expect(scope.authorizationBinding).toEqual({
+      moduleName: "shop",
+      scopeHash: captureAuthorizationScope(scopeContext).hash,
+    });
+  });
+});
+
+interface SetupOptions {
+  readonly moduleName: string;
+  readonly scopeHash: string;
+}
+
+function setup(
+  repository: InMemoryUploadRepository,
+  blobs: MemoryBlobStore,
+  options: SetupOptions,
+) {
+  const uploads = new UploadService({
+    repository,
+    blobStore: blobs,
+    policies: [policy],
+  });
+  const decisions: ModuleUploadDecision[] = [];
+  const writer = createModuleStorageWritePort(
+    { uploads, files: new FileService(repository, blobs) },
+    {
+      moduleName: options.moduleName,
+      ownerId: "user_shop",
+      purposes: new Set([policy.purpose]),
+      uploadPolicies: new Map([[policy.purpose, policy]]),
+      authorizationBinding: {
+        moduleName: options.moduleName,
+        scopeHash: options.scopeHash,
+      },
+      actor: {
+        id: "user_shop",
+        type: "user",
+        name: "商店用户",
+        roleCodes: ["shop-user"],
+        permissionKeys: ["shop.upload.manage"],
+      },
+      requestId: "request_shop",
+      signal: new AbortController().signal,
+      recordUploadDecision: (decision) => decisions.push(decision),
+    },
+  );
+  return { uploads, writer, decisions };
+}
+
+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-port.test.ts

@@ -14,7 +14,7 @@ const OTHER_POLICY = policy("other.attachment");
 
 describe("模块受限 Upload/BlobRead Port", () => {
   test("本模块用途可以创建上传会话，Owner 由宿主补齐", async () => {
-    const { port } = setup();
+    const { storage, port } = setup();
     const session = await port.createUploadSession({
       purpose: "shop.attachment",
       filename: "现场照片.txt",
@@ -24,6 +24,9 @@ describe("模块受限 Upload/BlobRead Port", () => {
 
     expect(session.ownerId).toBe("user_shop");
     expect(session.purpose).toBe("shop.attachment");
+    await expect(
+      storage.uploads.inspectSession(session.id, "user_shop"),
+    ).resolves.toMatchObject({ ownerId: "user_shop" });
   });
 
   test("跨模块与平台用途创建会话被拒绝", async () => {
@@ -233,6 +236,10 @@ function setup() {
       moduleName: "shop",
       ownerId: "user_shop",
       purposes: new Set(["shop.attachment"]),
+      authorizationBinding: {
+        moduleName: "shop",
+        scopeHash: "a".repeat(64),
+      },
     },
   );
   return { storage, port };

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

@@ -1,12 +1,20 @@
-import type {
-  ModuleActor,
-  ModuleResourceFileAccessPolicy,
-  ModuleResourceFileRequest,
-  ModuleStoragePort,
+import {
+  ModuleStorageError,
+  type ModuleActor,
+  type ModuleFileView,
+  type ModuleResourceFileAccessPolicy,
+  type ModuleResourceFileRequest,
+  type ModuleStoragePort,
+  type ModuleUploadPolicy,
+  type ModuleUploadSessionView,
 } from "@southwind-ai/server-sdk";
+import type { AuditOutcome } from "@southwind-ai/shared";
 import {
   UploadError,
+  type UploadAuthorizationBinding,
+  type FileMetadata,
   type FileService,
+  type UploadSession,
   type UploadService,
 } from "@southwind-ai/storage";
 
@@ -20,6 +28,10 @@ export interface ModuleStorageScope {
   ownerId: string;
   /** 本模块经 Host 注册的上传用途集合；跨模块与平台用途一律拒绝。 */
   purposes: ReadonlySet<string>;
+  /** Host 注册的用途策略；Writer 只从这里派生保留期。 */
+  uploadPolicies?: ReadonlyMap<string, ModuleUploadPolicy>;
+  /** Host 从不可伪造 ScopeContext 生成；业务输入不能提供或覆盖。 */
+  authorizationBinding?: UploadAuthorizationBinding;
   /** Host 颁发的 Actor 只读视图；资源文件访问策略不能从输入伪造 Actor。 */
   actor?: ModuleActor;
   requestId?: string;
@@ -33,6 +45,23 @@ export interface ModuleStorageScope {
     input: ModuleResourceFileRequest,
     outcome: "success" | "denied",
   ) => Promise<void> | void;
+  /** 流式写入由 Host 统一记录内置上传动作，不接受模块自定义 Action。 */
+  recordUploadDecision?: (decision: ModuleUploadDecision) => void;
+  /** Durable attempt 等 Host 事实；调用方不能覆盖。 */
+  uploadAuditMetadata?: Readonly<Record<string, string | number>>;
+}
+
+export interface ModuleUploadDecision {
+  readonly action:
+    | "file.upload.create"
+    | "file.upload.part.write"
+    | "file.upload.complete"
+    | "file.upload.abort"
+    | "security.denied";
+  readonly outcome: AuditOutcome;
+  readonly targetId?: string;
+  readonly purpose?: string;
+  readonly metadata?: Readonly<Record<string, string | number | boolean>>;
 }
 
 /**
@@ -51,7 +80,19 @@ export function createModuleStoragePort(
   return {
     async createUploadSession(input) {
       requireModulePurpose(scope, input.purpose);
-      return services.uploads.create({ ...input, ownerId: scope.ownerId });
+      if (!scope.authorizationBinding) {
+        throw new UploadError("UPLOAD_FORBIDDEN", "上传会话未授权");
+      }
+      return services.uploads.create({
+        ownerId: scope.ownerId,
+        purpose: input.purpose,
+        authorizationBinding: scope.authorizationBinding,
+        filename: input.filename,
+        mimeType: input.mimeType,
+        expectedByteSize: input.expectedByteSize,
+        expectedSha256: input.expectedSha256,
+        fileExpiresAt: input.fileExpiresAt,
+      });
     },
     async openFile(fileId) {
       const file = await services.files.open(fileId, scope.ownerId);
@@ -161,7 +202,7 @@ function findResourceFileAccessPolicy(
   return policy;
 }
 
-function requireModulePurpose(
+export function requireModulePurpose(
   scope: ModuleStorageScope,
   purpose: string,
 ): void {
@@ -173,6 +214,38 @@ function requireModulePurpose(
   }
 }
 
+export function projectUploadSession(
+  session: UploadSession,
+): ModuleUploadSessionView {
+  return {
+    id: session.id,
+    purpose: session.purpose,
+    filename: session.filename,
+    mimeType: session.mimeType,
+    expectedByteSize: session.expectedByteSize,
+    expectedSha256: session.expectedContentHash?.value,
+    receivedByteSize: session.receivedByteSize,
+    nextPartNumber: session.nextPartNumber,
+    status: session.status,
+    expiresAt: session.expiresAt,
+    fileExpiresAt: session.fileExpiresAt,
+    fileId: session.fileId,
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
+  };
+}
+
+export function projectFile(file: FileMetadata): ModuleFileView {
+  return {
+    id: file.id,
+    purpose: file.purpose,
+    filename: file.filename,
+    mimeType: file.mimeType,
+    byteSize: file.byteSize,
+    sha256: file.contentHash.value,
+  };
+}
+
 function forbiddenResourceFile(): UploadError {
   return new UploadError("UPLOAD_FORBIDDEN", "资源文件访问未授权");
 }
@@ -181,7 +254,10 @@ export function unavailableModuleStoragePort(
   moduleName: string,
 ): ModuleStoragePort {
   const fail = async (): Promise<never> => {
-    throw new Error(`模块 ${moduleName} 的存储 Port 未挂载`);
+    throw new ModuleStorageError(
+      "STORAGE_UNAVAILABLE",
+      `模块 ${moduleName} 的存储 Port 未挂载`,
+    );
   };
   return {
     createUploadSession: () => fail(),