create-windy 0.5.2 → 0.6.1

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");
+}

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

@@ -0,0 +1,60 @@
+import { isProxy } from "node:util/types";
+import type { ModuleSecretBindingResolution } from "@southwind-ai/server-sdk";
+
+const activeFields = new Set(["status", "value", "version"]);
+const inactiveFields = new Set(["status"]);
+
+export function snapshotModuleSecretBindingResolution(
+  value: unknown,
+): ModuleSecretBindingResolution {
+  if (!value || typeof value !== "object" || isProxy(value)) {
+    throw new Error("invalid module secret binding resolution");
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new Error("invalid module secret binding resolution");
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const keys = Reflect.ownKeys(descriptors);
+  if (keys.some((key) => typeof key !== "string")) {
+    throw new Error("invalid module secret binding resolution");
+  }
+  const status = dataValue(descriptors.status);
+  if (status === "disabled" || status === "unavailable") {
+    requireAllowedFields(keys, inactiveFields);
+    return Object.freeze({ status });
+  }
+  if (status !== "active") {
+    throw new Error("invalid module secret binding resolution");
+  }
+  requireAllowedFields(keys, activeFields);
+  const secret = dataValue(descriptors.value);
+  if (typeof secret !== "string") {
+    throw new Error("invalid module secret binding resolution");
+  }
+  if (descriptors.version) dataValue(descriptors.version);
+  return Object.freeze({ status, value: secret });
+}
+
+function dataValue(descriptor: PropertyDescriptor | undefined): unknown {
+  if (
+    !descriptor ||
+    descriptor.enumerable !== true ||
+    !("value" in descriptor)
+  ) {
+    throw new Error("invalid module secret binding resolution");
+  }
+  return descriptor.value;
+}
+
+function requireAllowedFields(
+  keys: readonly PropertyKey[],
+  allowed: ReadonlySet<string>,
+): void {
+  if (
+    keys.some((key) => typeof key !== "string" || !allowed.has(key)) ||
+    keys.length < 1
+  ) {
+    throw new Error("invalid module secret binding resolution");
+  }
+}

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

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "bun:test";
+import {
+  EnvironmentSecretResolver,
+  SecretRef,
+  type SecretResolver,
+} from "@southwind-ai/config";
+import type { DurableHandlerContext } from "@southwind-ai/jobs";
+import {
+  createModuleSecretBinding,
+  requireModuleSecretPort,
+  type ModuleDurableHandlerContext,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+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";
+import { manifest } from "./test-fixtures.js";
+
+const request = {
+  handle: "archive.sftp.password",
+  connection: "archive.sftp.primary",
+  purpose: "archive.sftp.read",
+};
+const feature = {
+  key: featureKey("archive.connection"),
+  label: "档案连接",
+  module: "archive",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+const moduleManifest = manifest("archive", {
+  features: [feature],
+  permissions: [
+    {
+      key: "archive.connection.read",
+      label: "读取档案连接",
+      module: "archive",
+      moduleLabel: "档案",
+      resource: "connection",
+      resourceLabel: "外部连接",
+      action: "read",
+    },
+  ],
+  secrets: [
+    {
+      ...request,
+      featureKey: feature.key,
+      permissionKey: "archive.connection.read",
+      auditAction: "archive.secret.resolve",
+    },
+  ],
+  tasks: [
+    {
+      key: "archive.sync",
+      label: "同步档案",
+      description: "同步外部档案。",
+      featureKey: feature.key,
+      permissionKey: "archive.connection.read",
+      auditAction: "archive.secret.resolve",
+      intervalSeconds: 60,
+      maxAttempts: 3,
+      retryDelaySeconds: 5,
+    },
+  ],
+  auditActions: [
+    {
+      key: "archive.secret.resolve",
+      label: "解析档案连接凭据",
+      description: "为已授权同步短暂解析凭据。",
+    },
+  ],
+});
+
+describe("Module Durable Secret attempt", () => {
+  test("每次 attempt 重新解析当前版本且不缓存原始 Secret", async () => {
+    const environment: Record<string, string | undefined> = {
+      ARCHIVE_SFTP_PASSWORD: "password-v1",
+    };
+    const environmentResolver = new EnvironmentSecretResolver(environment);
+    let calls = 0;
+    const resolver: SecretResolver = {
+      resolve(ref) {
+        calls += 1;
+        return environmentResolver.resolve(ref);
+      },
+    };
+    const hosts = await initializeModuleHosts({
+      modules: [moduleManifest],
+      secretBindings: [
+        createModuleSecretBinding({
+          moduleName: "archive",
+          ...request,
+          reference: new SecretRef("env", "ARCHIVE_SFTP_PASSWORD"),
+          resolver,
+        }),
+      ],
+      installations: [
+        {
+          manifest: moduleManifest,
+          setup(host) {
+            host.registerDurableHandler({
+              key: "archive.sync",
+              featureKey: feature.key,
+              permissionKey: "archive.connection.read",
+              auditAction: "archive.secret.resolve",
+              payload: { parse: () => ({}) },
+              execute: () => undefined,
+            });
+          },
+        },
+      ],
+    });
+    const runtime = createServerRuntime(
+      { NODE_ENV: "test" },
+      { featureCatalog: [feature] },
+    );
+    const actor = currentActor();
+    const contextualize = createModuleDurableContextualizer({
+      hosts,
+      runtime,
+      features: [feature],
+      resolveActor: async () => actor,
+    });
+    const persistedJob = job(actor);
+    const observed: string[] = [];
+
+    const first = (await contextualize({
+      claim: { job: persistedJob },
+      moduleName: "archive",
+      context: baseContext(1),
+    })) as ModuleDurableHandlerContext;
+    await requireModuleSecretPort(first).resolve(request, (value) => {
+      observed.push(value);
+    });
+
+    environment.ARCHIVE_SFTP_PASSWORD = "password-v2";
+    const retry = (await contextualize({
+      claim: { job: persistedJob },
+      moduleName: "archive",
+      context: baseContext(2),
+    })) as ModuleDurableHandlerContext;
+    await requireModuleSecretPort(retry).resolve(request, (value) => {
+      observed.push(value);
+    });
+
+    expect(observed).toEqual(["password-v1", "password-v2"]);
+    expect(calls).toBe(2);
+    const auditEvents = runtime.auditSink
+      .list()
+      .filter(({ action }) => action === "archive.secret.resolve");
+    expect(auditEvents).toHaveLength(2);
+    expect(auditEvents.map(({ metadata }) => metadata?.reason)).toEqual([
+      "resolved",
+      "resolved",
+    ]);
+    expect(auditEvents.every(({ metadata }) => !("version" in metadata!))).toBe(
+      true,
+    );
+    expect(JSON.stringify(runtime.auditSink.list())).not.toContain(
+      "password-v",
+    );
+  });
+});
+
+function currentActor(): RequestActor {
+  return {
+    id: "archive-user",
+    type: "user",
+    name: "档案用户",
+    roleCodes: ["archive-reader"],
+    permissionKeys: ["archive.connection.read"],
+    ...buildActorScopeContexts("archive-user", "archive-dept", [
+      {
+        id: "archive-role",
+        code: "archive-reader",
+        dataScope: "all",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function job(actor: RequestActor) {
+  return {
+    id: "archive-job",
+    handlerKey: "archive.sync",
+    requestedBy: actor.id,
+    authorizationScope: captureAuthorizationScope(actor.scopeContext).snapshot,
+  };
+}
+
+function baseContext(attemptNumber: number): DurableHandlerContext {
+  return {
+    jobId: "archive-job",
+    stageKey: "main",
+    attemptNumber,
+    signal: new AbortController().signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => undefined,
+  };
+}

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

@@ -0,0 +1,125 @@
+import {
+  EnvironmentSecretResolver,
+  SecretRef,
+  type SecretResolver,
+} from "@southwind-ai/config";
+import {
+  createModuleSecretBinding,
+  type ModuleSecretBinding,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { createModuleSecretPort } from "./module-secret-port.js";
+import { manifest } from "./test-fixtures.js";
+
+export const secretRequest = {
+  handle: "archive.connection.password",
+  connection: "archive.connection.primary",
+  purpose: "archive.connection.read",
+};
+
+export const secretFeature = {
+  key: featureKey("archive.connection"),
+  label: "档案连接",
+  module: "archive",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+
+const secretDeclaration = {
+  ...secretRequest,
+  featureKey: secretFeature.key,
+  permissionKey: "archive.connection.read",
+  auditAction: "archive.secret.resolve",
+};
+
+export async function secretPortFixture(input: {
+  value?: string;
+  enabled?: boolean;
+  actor?: RequestActor;
+  resolver?: SecretResolver;
+  binding?: ModuleSecretBinding;
+  runtimeOptions?: NonNullable<Parameters<typeof createServerRuntime>[1]>;
+}) {
+  const environment = { ARCHIVE_PASSWORD: input.value ?? "secret" };
+  const binding =
+    input.binding ??
+    createModuleSecretBinding({
+      moduleName: "archive",
+      ...secretRequest,
+      reference: new SecretRef("env", "ARCHIVE_PASSWORD"),
+      resolver: input.resolver ?? new EnvironmentSecretResolver(environment),
+      enabled: () => input.enabled ?? true,
+    });
+  const moduleManifest = archiveManifest();
+  const hosts = await initializeModuleHosts({
+    modules: [moduleManifest],
+    secretBindings: [binding],
+  });
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    { featureCatalog: [secretFeature], ...input.runtimeOptions },
+  );
+  const guardContext = await runtime.createGuardContextForActor(
+    new Request("http://module.test/secret"),
+    input.actor ?? currentActor(),
+  );
+  return {
+    runtime,
+    port: createModuleSecretPort({
+      moduleName: "archive",
+      declarations: hosts.secretDeclarationsOf("archive"),
+      bindings: hosts.secretBindingsOf("archive"),
+      guardContext,
+      runtime,
+      features: [secretFeature],
+    }),
+  };
+}
+
+export function currentActor(granted = true): RequestActor {
+  return {
+    id: "archive-user",
+    type: "user",
+    name: "档案用户",
+    roleCodes: ["archive-reader"],
+    permissionKeys: granted ? ["archive.connection.read"] : [],
+  };
+}
+
+export async function captureError(operation: () => Promise<unknown>) {
+  try {
+    await operation();
+  } catch (error) {
+    return error;
+  }
+  throw new Error("预期操作失败");
+}
+
+function archiveManifest() {
+  return manifest("archive", {
+    features: [secretFeature],
+    permissions: [
+      {
+        key: "archive.connection.read",
+        label: "读取档案连接",
+        module: "archive",
+        moduleLabel: "档案",
+        resource: "connection",
+        resourceLabel: "外部连接",
+        action: "read",
+      },
+    ],
+    secrets: [secretDeclaration],
+    auditActions: [
+      {
+        key: "archive.secret.resolve",
+        label: "解析档案连接凭据",
+        description: "为已授权连接短暂解析凭据。",
+      },
+    ],
+  });
+}