create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,345 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import type { DurableHandlerContext } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  requireModuleStorageWritePortV1,
+  type ModuleDurableHandlerContext,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import {
+  FileService,
+  InMemoryUploadRepository,
+  MemoryBlobStore,
+  UploadService,
+  type UploadPolicy,
+} from "@southwind-ai/storage";
+import { buildActorScopeContexts } from "../data-access/context.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { createModuleDurableContextualizer } from "./durable-context.js";
+import { initializeModuleHosts } from "./initialize.js";
+
+const uploadPolicy: UploadPolicy = {
+  purpose: "evidence.generated",
+  maxByteSize: 1024,
+  maxPartByteSize: 512,
+  sessionTtlMs: 60_000,
+  fileRetentionMs: 24 * 60 * 60_000,
+  allowedTypes: { "text/plain": ["txt"] },
+  signature: "none",
+};
+
+describe("模块 Durable 流式写入恢复", () => {
+  test("重建 Host/Service 后按持久会话续传并幂等完成", async () => {
+    const repository = new InMemoryUploadRepository();
+    const blobs = new MemoryBlobStore();
+    const runtime = createServerRuntime(
+      { NODE_ENV: "test" },
+      { featureCatalog: moduleManifest.features },
+    );
+    const actor = currentActor();
+    const firstHosts = await moduleHosts(true);
+    const first = contextualizer(
+      firstHosts,
+      storage(repository, blobs),
+      runtime,
+      actor,
+    );
+    const attempt1 = await moduleContext(first, actor, baseContext(1));
+    const whole = bytes("abcdef");
+    const session = await requireModuleStorageWritePortV1(
+      attempt1,
+    ).createUploadSession({
+      purpose: "evidence.generated",
+      filename: "result.txt",
+      mimeType: "text/plain",
+      expectedByteSize: whole.byteLength,
+      expectedSha256: digest(whole),
+    });
+    await requireModuleStorageWritePortV1(attempt1).appendUploadPart(
+      part(session.id, 0, 0, bytes("abc")),
+    );
+
+    const restartedHosts = await moduleHosts(true);
+    const restarted = contextualizer(
+      restartedHosts,
+      storage(repository, blobs),
+      runtime,
+      actor,
+    );
+    const attempt2 = await moduleContext(restarted, actor, baseContext(2));
+    const writer2 = requireModuleStorageWritePortV1(attempt2);
+    await expect(writer2.getUploadSession(session.id)).resolves.toMatchObject({
+      receivedByteSize: 3,
+      nextPartNumber: 1,
+      status: "uploading",
+    });
+    await writer2.appendUploadPart(part(session.id, 1, 3, bytes("def")));
+    const completed = await writer2.completeUpload(session.id);
+    const replay = await writer2.completeUpload(session.id);
+
+    expect(replay).toEqual(completed);
+    expect(blobs.size).toBe(1);
+    expect(await repository.getFile(completed.id)).toMatchObject({
+      ownerId: actor.id,
+      contentHash: { value: digest(whole) },
+    });
+    expect(runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "file.upload.complete",
+        module: "evidence",
+        metadata: expect.objectContaining({
+          jobId: "job-evidence",
+          attemptNumber: 2,
+        }),
+      }),
+    );
+  });
+
+  test("purpose 注册漂移与下一 attempt 权限撤销均在写入前 fail closed", async () => {
+    const repository = new InMemoryUploadRepository();
+    const blobs = new MemoryBlobStore();
+    const actor = currentActor();
+    const runtime = createServerRuntime(
+      { NODE_ENV: "test" },
+      { featureCatalog: moduleManifest.features },
+    );
+    const first = contextualizer(
+      await moduleHosts(true),
+      storage(repository, blobs),
+      runtime,
+      actor,
+    );
+    const staleAttempt = new AbortController();
+    const firstContext = await moduleContext(
+      first,
+      actor,
+      baseContext(1, staleAttempt.signal),
+    );
+    const session = await requireModuleStorageWritePortV1(
+      firstContext,
+    ).createUploadSession({
+      purpose: "evidence.generated",
+      filename: "result.txt",
+      mimeType: "text/plain",
+      expectedByteSize: 3,
+    });
+    staleAttempt.abort("lease-lost");
+    await expect(
+      requireModuleStorageWritePortV1(firstContext).abortUpload(session.id),
+    ).rejects.toMatchObject({ code: "UPLOAD_CANCELLED" });
+    expect((await repository.getSession(session.id))?.status).toBe("uploading");
+
+    const drifted = contextualizer(
+      await moduleHosts(false),
+      storage(repository, blobs),
+      runtime,
+      actor,
+    );
+    const driftedContext = await moduleContext(drifted, actor, baseContext(2));
+    await expect(
+      requireModuleStorageWritePortV1(driftedContext).getUploadSession(
+        session.id,
+      ),
+    ).rejects.toMatchObject({
+      code: "UPLOAD_FORBIDDEN",
+      message: "上传会话未授权",
+    });
+
+    const revoked = contextualizer(
+      await moduleHosts(true),
+      storage(repository, blobs),
+      runtime,
+      { ...actor, permissionKeys: [] },
+    );
+    await expect(
+      moduleContext(revoked, actor, baseContext(3)),
+    ).rejects.toMatchObject({
+      code: "MODULE_DURABLE_GUARD_DENIED",
+      details: { reason: "missing-permission" },
+    });
+    expect(await repository.listParts(session.id)).toEqual([]);
+  });
+});
+
+const moduleFeature = {
+  key: featureKey("evidence.catalog"),
+  label: "电子物证",
+  module: "evidence",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+
+const moduleManifest: ModuleManifest = {
+  name: "evidence",
+  version: "0.1.0",
+  label: "电子物证",
+  description: "电子物证测试模块",
+  menus: [],
+  adminRoutes: [],
+  permissions: [
+    {
+      key: "evidence.catalog.manage",
+      label: "管理物证",
+      module: "evidence",
+      moduleLabel: "电子物证",
+      resource: "catalog",
+      resourceLabel: "物证",
+      action: "manage",
+    },
+  ],
+  apiPermissions: [],
+  features: [moduleFeature],
+  migrations: [],
+  schemaExports: [],
+  tasks: [
+    {
+      key: "evidence.catalog.generate",
+      label: "生成物证文件",
+      description: "生成受控物证文件。",
+      permissionKey: "evidence.catalog.manage",
+      featureKey: "evidence.catalog",
+      auditAction: "task.execute",
+      intervalSeconds: 60,
+      maxAttempts: 3,
+      retryDelaySeconds: 5,
+    },
+  ],
+  tools: [],
+  providers: [],
+  auditActions: ["task.execute"],
+};
+
+async function moduleHosts(registerPurpose: boolean) {
+  return initializeModuleHosts({
+    modules: [moduleManifest],
+    installations: [
+      {
+        manifest: moduleManifest,
+        setup(host) {
+          if (registerPurpose) host.registerUploadPolicy(uploadPolicy);
+          host.registerDurableHandler({
+            key: "evidence.catalog.generate",
+            featureKey: "evidence.catalog",
+            permissionKey: "evidence.catalog.manage",
+            auditAction: "task.execute",
+            payload: { parse: () => ({}) },
+            execute: () => undefined,
+          });
+        },
+      },
+    ],
+  });
+}
+
+function storage(repository: InMemoryUploadRepository, blobs: MemoryBlobStore) {
+  return {
+    uploads: new UploadService({
+      repository,
+      blobStore: blobs,
+      policies: [uploadPolicy],
+    }),
+    files: new FileService(repository, blobs),
+  };
+}
+
+function contextualizer(
+  hosts: Awaited<ReturnType<typeof moduleHosts>>,
+  storageServices: ReturnType<typeof storage>,
+  runtime: ReturnType<typeof createServerRuntime>,
+  resolvedActor: RequestActor,
+) {
+  return createModuleDurableContextualizer({
+    hosts,
+    runtime,
+    features: moduleManifest.features,
+    storage: storageServices,
+    resolveActor: async () => resolvedActor,
+  });
+}
+
+async function moduleContext(
+  contextualize: ReturnType<typeof createModuleDurableContextualizer>,
+  submittedActor: RequestActor,
+  context: DurableHandlerContext,
+) {
+  return (await contextualize({
+    claim: { job: job(submittedActor) },
+    moduleName: "evidence",
+    context,
+  })) as ModuleDurableHandlerContext;
+}
+
+function currentActor(): RequestActor {
+  return {
+    id: "user-evidence",
+    type: "user",
+    name: "物证管理员",
+    roleCodes: ["investigator"],
+    permissionKeys: ["evidence.catalog.manage"],
+    ...buildActorScopeContexts("user-evidence", "dept-case", [
+      {
+        id: "role-investigator",
+        code: "investigator",
+        dataScope: "all",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function job(actor: RequestActor) {
+  return {
+    id: "job-evidence",
+    handlerKey: "evidence.catalog.generate",
+    requestedBy: actor.id,
+    authorizationScope: captureAuthorizationScope(actor.scopeContext).snapshot,
+  };
+}
+
+function baseContext(
+  attemptNumber: number,
+  signal = new AbortController().signal,
+): DurableHandlerContext {
+  return {
+    jobId: "job-evidence",
+    stageKey: "main",
+    attemptNumber,
+    signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => undefined,
+  };
+}
+
+function part(
+  sessionId: string,
+  partNumber: number,
+  byteOffset: number,
+  value: Uint8Array,
+) {
+  return {
+    sessionId,
+    partNumber,
+    byteOffset,
+    byteSize: value.byteLength,
+    sha256: digest(value),
+    body: 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/http-runtime.ts

@@ -6,6 +6,7 @@ import type { DurableJobWorker } from "../jobs/worker.js";
 import type { createServerRuntime } from "../runtime.js";
 // @windy-module system.storage begin
 import type { createStorageRuntime } from "../storage/runtime.js";
+import type { ReportStagingService } from "../report-staging/service.js";
 // @windy-module system.storage end
 import type { RouteApp } from "../system/route-types.js";
 import type { SystemRepositories } from "../system/seed.js";
@@ -13,6 +14,8 @@ import type { SystemRepositories } from "../system/seed.js";
 import type { RequestGuardContext } from "../guards.js";
 import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
 import type { ModuleAiOperationPort } from "@southwind-ai/server-sdk";
+import type { ModuleAiOperationReadinessPortV1 } from "@southwind-ai/server-sdk";
+import type { ModuleAiScreenshotIntakePortV1 } from "@southwind-ai/server-sdk";
 // @windy-module system.agent end
 import { installModuleRoutes } from "./route-installer.js";
 import type { InitializedModuleHosts } from "./initialize.js";
@@ -36,6 +39,7 @@ export function installModuleHttpRuntime(
     // @windy-module system.scheduler end
     // @windy-module system.storage begin
     storage: ReturnType<typeof createStorageRuntime>;
+    reportStaging?: ReportStagingService;
     // @windy-module system.storage end
     systemRepositories: SystemRepositories;
     // @windy-module system.agent begin
@@ -45,6 +49,16 @@ export function installModuleHttpRuntime(
       guardContext: RequestGuardContext,
       signal: AbortSignal,
     ) => ModuleAiOperationPort;
+    aiReadiness?: (
+      moduleName: string,
+      guardContext: RequestGuardContext,
+      signal: AbortSignal,
+    ) => ModuleAiOperationReadinessPortV1;
+    screenshots?: (
+      moduleName: string,
+      guardContext: RequestGuardContext,
+      signal: AbortSignal,
+    ) => ModuleAiScreenshotIntakePortV1;
     // @windy-module system.agent end
     // @windy-module system.data-governance begin
     reauthenticate(actorId: string, password: string): Promise<boolean>;
@@ -64,6 +78,7 @@ export function installModuleHttpRuntime(
       uploads: context.storage.uploads,
       files: context.storage.files,
     },
+    reportStaging: context.reportStaging,
     // @windy-module system.storage end
     userDirectory: {
       repositories: context.systemRepositories,
@@ -77,7 +92,17 @@ export function installModuleHttpRuntime(
             signal,
           )
       : undefined,
+    validateAiArtifact: context.aiArtifacts
+      ? (reference, moduleName, guardContext) =>
+          context.aiArtifacts!.validateReference(
+            reference,
+            guardContext.actor.id,
+            moduleName,
+          )
+      : undefined,
     aiOperations: context.aiOperations,
+    aiReadiness: context.aiReadiness,
+    screenshots: context.screenshots,
     // @windy-module system.agent end
   });
   // @windy-module system.data-governance begin

package/template/apps/server/src/module-host/initialize-contracts.ts

@@ -1,5 +1,8 @@
 import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
-import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  ModuleManifest,
+  ModuleSecretDefinition,
+} from "@southwind-ai/modules";
 import type {
   InstallableServerModule,
   ModuleAiOperationHandlerRegistration,
@@ -8,7 +11,9 @@ import type {
   ModuleInitializer,
   ModuleGovernedResourceRegistration,
   ModuleRolePreset,
+  ModuleSecretBinding,
   ModuleResourceFileAccessPolicy,
+  ModuleReportStagingPolicyV1,
   ModuleRouteDefinition,
   ModuleSearchProvider,
   ModuleSandboxToolHandlerRegistration,
@@ -77,11 +82,14 @@ export interface InitializeModuleHostsInput {
   /** @deprecated 仅供旧模块迁移；新模块必须使用 installations。 */
   initializers?: readonly ModuleInitializer[];
   baseUploadPolicies?: readonly ModuleUploadPolicy[];
+  /** project-owned Server Composition 提供的物理 Secret 绑定。 */
+  secretBindings?: readonly ModuleSecretBinding[];
 }
 
 export interface InitializedModuleHosts {
   readonly manifests: readonly ModuleManifest[];
   readonly uploadPolicies: readonly ModuleUploadPolicy[];
+  readonly reportStagingPolicies: readonly ModuleReportStagingPolicyV1[];
   readonly resourceFileAccessPolicies: readonly ModuleResourceFileAccessPolicy[];
   readonly routes: readonly RegisteredModuleRoute[];
   readonly taskHandlers: readonly RegisteredModuleTaskHandler[];
@@ -89,6 +97,7 @@ export interface InitializedModuleHosts {
   readonly sandboxToolHandlers: readonly RegisteredModuleSandboxToolHandler[];
   readonly aiOperationHandlers: readonly RegisteredModuleAiOperationHandler[];
   readonly durableHandlers: readonly RegisteredModuleDurableHandler[];
+  readonly secretBindings: readonly ModuleSecretBinding[];
   readonly governedResources: readonly RegisteredModuleGovernedResource[];
   readonly rolePresets: readonly RegisteredModuleRolePreset[];
   readonly searchProviders: readonly RegisteredModuleSearchProvider[];
@@ -96,6 +105,12 @@ export interface InitializedModuleHosts {
   manifestOf(moduleName: string): ModuleManifest;
   /** 该模块经 Host 注册的上传用途集合（不含平台基础用途）。 */
   uploadPurposesOf(moduleName: string): ReadonlySet<string>;
+  /** 该模块注册的完整上传策略；仅供 Host 派生 Writer 治理参数。 */
+  uploadPoliciesOf(moduleName: string): readonly ModuleUploadPolicy[];
+  /** 该模块注册的完整大报告暂存策略。 */
+  reportStagingPoliciesOf(
+    moduleName: string,
+  ): readonly ModuleReportStagingPolicyV1[];
   /** 该模块注册的资源文件读取策略。 */
   resourceFileAccessPoliciesOf(
     moduleName: string,
@@ -104,5 +119,7 @@ export interface InitializedModuleHosts {
     moduleName: string,
     handlerKey: string,
   ): RegisteredModuleDurableHandler["definition"] | undefined;
+  secretBindingsOf(moduleName: string): readonly ModuleSecretBinding[];
+  secretDeclarationsOf(moduleName: string): readonly ModuleSecretDefinition[];
   installDurableHandlers(registry: DurableHandlerRegistry): void;
 }

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

@@ -126,6 +126,24 @@ describe("模块 Host 初始化", () => {
     ).rejects.toThrow("任务 handler Feature 未在 Manifest 注册：known.missing");
   });
 
+  test("上传用途显式保留期必须在 Host 边界内", async () => {
+    for (const fileRetentionMs of [0, 59_999, 365 * 24 * 60 * 60_000 + 1]) {
+      await expect(
+        initializeModuleHosts({
+          modules: [manifest("known")],
+          initializers: [
+            initializer("known", (host) => {
+              host.registerUploadPolicy({
+                ...policy("known.attachment"),
+                fileRetentionMs,
+              });
+            }),
+          ],
+        }),
+      ).rejects.toThrow("模块上传用途文件保留期无效");
+    }
+  });
+
   test("安装单元的 Manifest 必须来自同一平台能力目录", async () => {
     await expect(
       initializeModuleHosts({

package/template/apps/server/src/module-host/initialize.ts

@@ -1,6 +1,10 @@
 import {
-  type ModuleResourceFileAccessPolicy,
-  type ModuleUploadPolicy,
+  snapshotModuleSecretDeclarations,
+  type ModuleSecretDefinition,
+} from "@southwind-ai/modules";
+import type {
+  ModuleResourceFileAccessPolicy,
+  ModuleUploadPolicy,
 } from "@southwind-ai/server-sdk";
 import type {
   InitializedModuleHosts,
@@ -9,6 +13,7 @@ import type {
 import { validateResourceFileAccessPurposes } from "./resource-file-policies.js";
 import { createScopedSandboxHost } from "./sandbox-tool-registration.js";
 import { createScopedHost, type HostCollections } from "./scoped-host.js";
+import { validateModuleSecretBindings } from "./secret-bindings.js";
 
 export type {
   InitializedModuleHosts,
@@ -31,7 +36,21 @@ export async function initializeModuleHosts(
   const manifests = new Map(
     input.modules.map((module) => [module.name, module]),
   );
+  const secretDeclarationsByModule = new Map<
+    string,
+    readonly ModuleSecretDefinition[]
+  >(
+    input.modules.map((module) => [
+      module.name,
+      snapshotModuleSecretDeclarations(module),
+    ]),
+  );
   const initializedNames = new Set<string>();
+  const secretBindingsByModule = validateModuleSecretBindings(
+    input.modules,
+    input.secretBindings ?? [],
+    secretDeclarationsByModule,
+  );
   const uploadPolicies: ModuleUploadPolicy[] = [];
   const uploadPurposes = new Set<string>();
   for (const policy of input.baseUploadPolicies ?? []) {
@@ -45,6 +64,9 @@ export async function initializeModuleHosts(
     uploadPolicies,
     uploadPurposes,
     modulePurposes: new Map<string, Set<string>>(),
+    reportStagingPolicies: [],
+    reportStagingPurposes: new Set<string>(),
+    moduleReportStagingPolicies: new Map(),
     moduleDependencies: new Map(
       input.modules.map((module) => [module.name, module.dependencies ?? []]),
     ),
@@ -121,6 +143,7 @@ export async function initializeModuleHosts(
   return {
     manifests: input.modules,
     uploadPolicies: [...state.uploadPolicies],
+    reportStagingPolicies: [...state.reportStagingPolicies],
     resourceFileAccessPolicies: [...state.resourceFileAccessPolicies],
     routes: [...state.routes],
     taskHandlers: [...state.taskHandlers],
@@ -128,6 +151,7 @@ export async function initializeModuleHosts(
     sandboxToolHandlers: [...state.sandboxToolHandlers],
     aiOperationHandlers: [...state.aiOperationHandlers],
     durableHandlers: [...state.durableHandlers],
+    secretBindings: [...secretBindingsByModule.values()].flat(),
     governedResources: [...state.governedResources],
     rolePresets: [...state.rolePresets],
     searchProviders: [...state.searchProviders],
@@ -140,6 +164,16 @@ export async function initializeModuleHosts(
     uploadPurposesOf(moduleName) {
       return state.modulePurposes.get(moduleName) ?? new Set<string>();
     },
+    uploadPoliciesOf(moduleName) {
+      const purposes = state.modulePurposes.get(moduleName);
+      if (!purposes) return [];
+      return state.uploadPolicies.filter(({ purpose }) =>
+        purposes.has(purpose),
+      );
+    },
+    reportStagingPoliciesOf(moduleName) {
+      return state.moduleReportStagingPolicies.get(moduleName) ?? [];
+    },
     resourceFileAccessPoliciesOf(moduleName) {
       return state.moduleResourceFileAccessPolicies.get(moduleName) ?? [];
     },
@@ -150,6 +184,12 @@ export async function initializeModuleHosts(
           entry.definition.key === handlerKey,
       )?.definition;
     },
+    secretBindingsOf(moduleName) {
+      return secretBindingsByModule.get(moduleName) ?? [];
+    },
+    secretDeclarationsOf(moduleName) {
+      return secretDeclarationsByModule.get(moduleName) ?? [];
+    },
     installDurableHandlers(registry) {
       for (const install of state.handlerInstallers) install(registry);
     },

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

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import { describe, expect, test } from "bun:test";
+import type {
+  ModuleSecretBinding,
+  ModuleSecretBindingResolution,
+} from "@southwind-ai/server-sdk";
+import {
+  secretPortFixture,
+  secretRequest,
+} from "./module-secret-port.test-support.js";
+
+describe("Module Secret audit version boundary", () => {
+  test("provider version 与可公开字典验证的摘要都不进入审计", async () => {
+    const secret = "RAW_SECRET_EQUALS_VERSION";
+    const versions: readonly unknown[] = [
+      "password",
+      "ARCHIVE_PASSWORD",
+      "kv-prod-secret",
+      "file:/run/secrets/archive",
+      "Authorization: Bearer other-secret",
+      secret,
+      "x".repeat(512),
+      42,
+      { credential: "other-secret" },
+      Symbol("other-secret"),
+    ];
+
+    for (const version of versions) {
+      const setup = await secretPortFixture({
+        binding: runtimeVersionBinding(secret, version),
+      });
+      await expect(
+        setup.port.resolve(secretRequest, () => ({ connected: true })),
+      ).resolves.toEqual({ connected: true });
+
+      const auditJson = JSON.stringify(setup.runtime.auditSink.list());
+      expect(auditJson).not.toContain(secret);
+      expect(auditJson).not.toContain("version");
+      if (typeof version === "string") {
+        expect(auditJson).not.toContain(JSON.stringify(version));
+        expect(auditJson).not.toContain(sha256(version));
+        expect(auditJson).not.toContain(`sha256:${sha256(version)}`);
+      }
+      expect(setup.runtime.auditSink.list()).toContainEqual(
+        expect.objectContaining({
+          outcome: "success",
+          metadata: expect.objectContaining({ reason: "resolved" }),
+        }),
+      );
+    }
+  });
+});
+
+function runtimeVersionBinding(
+  value: string,
+  version: unknown,
+): ModuleSecretBinding {
+  return {
+    moduleName: "archive",
+    ...secretRequest,
+    resolve() {
+      return {
+        status: "active",
+        value,
+        version,
+      } as unknown as ModuleSecretBindingResolution;
+    },
+  };
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}