create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/module-host/screenshot-intake-test-support.ts

@@ -0,0 +1,68 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+
+export const screenshotOperationKey = "evidence.document.ocr";
+
+export function screenshotIntakeManifest(): ModuleManifest {
+  return {
+    name: "evidence",
+    version: "0.1.0",
+    label: "物证",
+    description: "Screenshot Intake 测试模块",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "evidence.document.ocr.execute",
+        label: "OCR",
+        module: "evidence",
+        moduleLabel: "物证",
+        resource: "document",
+        resourceLabel: "文档",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("evidence.document.ocr"),
+        label: "OCR",
+        module: "evidence",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [],
+    tasks: [],
+    tools: [],
+    aiOperations: [
+      {
+        key: screenshotOperationKey,
+        kind: "document",
+        featureKey: "evidence.document.ocr",
+        permissionKey: "evidence.document.ocr.execute",
+        auditAction: "evidence.document.ocr.execute",
+        inputSchemaKey: "evidence.document.input.v1",
+        outputSchemaKey: "evidence.document.output.v1",
+        inputModalities: ["document"],
+        requiredCapabilities: ["document.ocr"],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "background",
+        providerEgress: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 20,
+          maxArtifacts: 2,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: ["evidence.document.ocr.execute"],
+  };
+}

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

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleSecretBinding } from "@southwind-ai/server-sdk";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+const declaration = {
+  handle: "archive.smb.password",
+  connection: "archive.smb.primary",
+  purpose: "archive.smb.read",
+  featureKey: "archive.connection",
+  permissionKey: "archive.connection.read",
+  auditAction: "data.read",
+};
+
+function binding(moduleName = "archive") {
+  return {
+    moduleName,
+    handle: declaration.handle,
+    connection: declaration.connection,
+    purpose: declaration.purpose,
+    resolve: () => ({ status: "disabled" as const }),
+  };
+}
+
+describe("Module Secret Composition binding", () => {
+  test("只接受 Manifest 精确声明的 project-owned binding", async () => {
+    const archive = manifest("archive", { secrets: [declaration] });
+    const hosts = await initializeModuleHosts({
+      modules: [archive],
+      secretBindings: [binding()],
+    });
+
+    expect(hosts.secretBindingsOf("archive")).toHaveLength(1);
+    expect(hosts.secretBindingsOf("other")).toEqual([]);
+  });
+
+  test("跨模块、未声明和重复 binding 均 fail closed", async () => {
+    const archive = manifest("archive", { secrets: [declaration] });
+
+    await expect(
+      initializeModuleHosts({
+        modules: [archive],
+        secretBindings: [binding("other")],
+      }),
+    ).rejects.toThrow("引用了未安装模块");
+
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("archive")],
+        secretBindings: [binding()],
+      }),
+    ).rejects.toThrow("未在 Manifest 声明");
+
+    await expect(
+      initializeModuleHosts({
+        modules: [archive],
+        secretBindings: [binding(), binding()],
+      }),
+    ).rejects.toThrow("模块 Secret 绑定重复");
+
+    const locator = binding("file:/run/secrets/credential");
+    const error = await captureInitializationError(locator);
+    expect(String(error)).toContain("moduleName 非法");
+    expect(String(error)).not.toContain("run/secrets");
+  });
+
+  test("preflight 拒绝 accessor、Proxy、隐藏字段、symbol 与非普通对象", async () => {
+    const marker = "file:/run/secrets/archive-password";
+    let reads = 0;
+    const accessor = binding();
+    Object.defineProperty(accessor, "handle", {
+      enumerable: true,
+      get() {
+        reads += 1;
+        throw new Error(marker);
+      },
+    });
+    const resolveAccessor = binding();
+    Object.defineProperty(resolveAccessor, "resolve", {
+      enumerable: true,
+      get() {
+        reads += 1;
+        throw new Error(marker);
+      },
+    });
+    const hidden = binding();
+    Object.defineProperty(hidden, "locator", {
+      enumerable: false,
+      value: marker,
+    });
+    const symbolic = binding();
+    Object.defineProperty(symbolic, Symbol("locator"), {
+      enumerable: true,
+      value: marker,
+    });
+    const proxied = new Proxy(binding(), {
+      ownKeys() {
+        reads += 1;
+        throw new Error(marker);
+      },
+    });
+    const proxiedResolve = binding();
+    proxiedResolve.resolve = new Proxy(proxiedResolve.resolve, {
+      apply() {
+        reads += 1;
+        throw new Error(marker);
+      },
+    });
+    const nonPlain = Object.assign(
+      Object.create({ locator: marker }),
+      binding(),
+    );
+
+    for (const candidate of [
+      accessor,
+      resolveAccessor,
+      hidden,
+      symbolic,
+      proxied,
+      proxiedResolve,
+      nonPlain,
+    ]) {
+      const error = await captureInitializationError(
+        candidate as unknown as ModuleSecretBinding,
+      );
+      expect(String(error)).toContain("模块 Secret 绑定结构非法");
+      expect(String(error)).not.toContain(marker);
+    }
+    expect(reads).toBe(0);
+  });
+
+  test("Host 保存逻辑字段与 resolve callable 的规范快照", async () => {
+    const source = binding();
+    const mutableDeclaration = { ...declaration };
+    const archive = manifest("archive", { secrets: [mutableDeclaration] });
+    const hosts = await initializeModuleHosts({
+      modules: [archive],
+      secretBindings: [source],
+    });
+    source.handle = "archive.changed.password";
+    source.resolve = () => {
+      throw new Error("file:/run/secrets/changed");
+    };
+
+    const captured = hosts.secretBindingsOf("archive")[0]!;
+    const capturedDeclaration = hosts.secretDeclarationsOf("archive")[0]!;
+    mutableDeclaration.handle = "archive.changed.manifest";
+    expect(captured.handle).toBe(declaration.handle);
+    expect(capturedDeclaration.handle).toBe("archive.smb.password");
+    expect(Object.getPrototypeOf(captured)).toBeNull();
+    expect(captured.resolve()).toEqual({ status: "disabled" });
+  });
+});
+
+async function captureInitializationError(
+  candidate: ModuleSecretBinding,
+): Promise<unknown> {
+  try {
+    await initializeModuleHosts({
+      modules: [manifest("archive", { secrets: [declaration] })],
+      secretBindings: [candidate],
+    });
+  } catch (error) {
+    return error;
+  }
+  throw new Error("预期初始化失败");
+}

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 };