create-windy 0.5.2 → 0.6.0

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: "为已授权连接短暂解析凭据。",
+      },
+    ],
+  });
+}

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

@@ -0,0 +1,161 @@
+import { describe, expect, test } from "bun:test";
+import type { SecretResolver } from "@southwind-ai/config";
+import {
+  captureError,
+  currentActor,
+  secretPortFixture as fixture,
+  secretRequest,
+} from "./module-secret-port.test-support.js";
+
+describe("Module Secret resolve Port", () => {
+  test("按声明解析并只审计逻辑标识", async () => {
+    const marker = "SECRET_MARKER_FOR_AUDIT";
+    const setup = await fixture({ value: marker });
+    const result = await setup.port.resolve(secretRequest, (value) => {
+      expect(value).toBe(marker);
+      return { connected: true };
+    });
+
+    expect(result).toEqual({ connected: true });
+    expect(setup.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "archive.secret.resolve",
+        outcome: "success",
+        target: {
+          type: "module-secret",
+          id: "archive.connection.password",
+        },
+        metadata: expect.objectContaining({
+          connection: "archive.connection.primary",
+          purpose: "archive.connection.read",
+          reason: "resolved",
+        }),
+      }),
+    );
+    expect(JSON.stringify(setup.runtime.auditSink.list())).not.toContain(
+      marker,
+    );
+  });
+
+  test("跨模块与未声明三元组同形拒绝且不调用 Resolver", async () => {
+    let calls = 0;
+    const resolver: SecretResolver = {
+      resolve() {
+        calls += 1;
+        return "must-not-resolve";
+      },
+    };
+    const setup = await fixture({ resolver });
+
+    for (const request of [
+      { ...secretRequest, handle: "other.connection.password" },
+      { ...secretRequest, purpose: "archive.connection.write" },
+    ]) {
+      await expect(
+        setup.port.resolve(request, () => ({ connected: true })),
+      ).rejects.toMatchObject({ code: "MODULE_SECRET_NOT_DECLARED" });
+    }
+    expect(calls).toBe(0);
+    expect(JSON.stringify(setup.runtime.auditSink.list())).not.toContain(
+      "other.connection.password",
+    );
+  });
+
+  test("Permission、Feature 与 License 任一拒绝都不解析 Secret", async () => {
+    const cases = [
+      {
+        expected: "missing-permission",
+        actor: currentActor(false),
+      },
+      {
+        expected: "feature-disabled",
+        runtimeOptions: {
+          featureResolver: {
+            resolve: (key: string) => ({
+              key,
+              enabled: false,
+              visible: "visible" as const,
+            }),
+          },
+        },
+      },
+      {
+        expected: "license-restricted",
+        runtimeOptions: {
+          licenseEnforced: true,
+          licenseResolver: {
+            resolve: () => ({ restricted: true, status: "invalid" as const }),
+          },
+        },
+      },
+    ];
+
+    for (const item of cases) {
+      let calls = 0;
+      const setup = await fixture({
+        actor: item.actor,
+        runtimeOptions: item.runtimeOptions,
+        resolver: {
+          resolve() {
+            calls += 1;
+            return "must-not-resolve";
+          },
+        },
+      });
+      await expect(
+        setup.port.resolve(secretRequest, () => ({ connected: true })),
+      ).rejects.toMatchObject({
+        code: "MODULE_SECRET_GUARD_DENIED",
+        reason: item.expected,
+      });
+      expect(calls).toBe(0);
+    }
+  });
+
+  test("停用、底层异常和回调异常只返回稳定脱敏错误", async () => {
+    const marker = "SECRET_MARKER_FOR_ERRORS";
+    const disabled = await fixture({ value: marker, enabled: false });
+    await expect(
+      disabled.port.resolve(secretRequest, () => ({ connected: true })),
+    ).rejects.toMatchObject({ code: "MODULE_SECRET_DISABLED" });
+
+    const failed = await fixture({
+      binding: {
+        moduleName: "archive",
+        ...secretRequest,
+        resolve() {
+          throw new Error(`resolver leaked ${marker}`);
+        },
+      },
+    });
+    const resolverError = await captureError(() =>
+      failed.port.resolve(secretRequest, () => ({ connected: true })),
+    );
+    expect(resolverError).toMatchObject({ code: "MODULE_SECRET_UNAVAILABLE" });
+    expect(JSON.stringify(resolverError)).not.toContain(marker);
+
+    const operation = await fixture({ value: marker });
+    const operationError = await captureError(() =>
+      operation.port.resolve(secretRequest, (value) => {
+        throw new Error(`operation leaked ${value}`);
+      }),
+    );
+    expect(operationError).toMatchObject({
+      code: "MODULE_SECRET_OPERATION_FAILED",
+    });
+    expect(String(operationError)).not.toContain(marker);
+    expect(JSON.stringify(operation.runtime.auditSink.list())).not.toContain(
+      marker,
+    );
+  });
+
+  test("回调结果包含原始 Secret 时 fail closed", async () => {
+    const marker = "SECRET_MARKER_FOR_RESULT";
+    const setup = await fixture({ value: marker });
+    await expect(
+      setup.port.resolve(secretRequest, (value) => ({
+        accidental: `prefix:${value}`,
+      })),
+    ).rejects.toMatchObject({ code: "MODULE_SECRET_EXPOSURE_BLOCKED" });
+  });
+});