create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,312 @@
+import { describe, expect, test } from "bun:test";
+import type { DurableHandlerContext } from "@southwind-ai/jobs";
+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 { createStorageRuntime } from "../storage/runtime.js";
+import { createModuleDurableContextualizer } from "./durable-context.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+const evidenceFeature = {
+  key: featureKey("evidence.catalog"),
+  label: "电子物证",
+  module: "evidence",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+const evidenceManifest = manifest("evidence", {
+  features: [evidenceFeature],
+  permissions: [
+    {
+      key: "evidence.read",
+      label: "读取物证",
+      module: "evidence",
+      moduleLabel: "物证",
+      resource: "file",
+      resourceLabel: "文件",
+      action: "read",
+    },
+  ],
+  auditActions: ["evidence.file.read"],
+});
+
+describe("模块 Durable Handler 授权上下文", () => {
+  test("后台 AI Port 固定当前模块与重建后的 Actor", async () => {
+    const calls: unknown[] = [];
+    const fixture = await setup(currentActor, {
+      create(moduleName, context) {
+        return {
+          async enqueueOperation(input) {
+            calls.push({
+              moduleName,
+              actorId: context.actor.id,
+              operationKey: input.operationKey,
+            });
+            return { runId: "run-1", output: { summary: "完成" } };
+          },
+        };
+      },
+    });
+    const context = await fixture.contextualize({
+      claim: { job: job(fixture.actor) },
+      moduleName: "evidence",
+      context: baseContext(1),
+    });
+
+    await (
+      context as typeof context & {
+        ai: {
+          enqueueOperation(input: {
+            operationKey: string;
+            input: null;
+            idempotencyKey: string;
+          }): Promise<unknown>;
+        };
+      }
+    ).ai.enqueueOperation({
+      operationKey: "evidence.summarize",
+      input: null,
+      idempotencyKey: "summary-1",
+    });
+
+    expect(calls).toEqual([
+      {
+        moduleName: "evidence",
+        actorId: "user-reader",
+        operationKey: "evidence.summarize",
+      },
+    ]);
+  });
+
+  test("重启后按 requestedBy 重建 Actor 并允许同案跨上传者读取", async () => {
+    const { contextualize, storage, actor, resolverCalls, runtime } =
+      await setup();
+    const file = await seedFile(storage);
+    const persistedJob = job(actor);
+
+    const first = await contextualize({
+      claim: { job: persistedJob },
+      moduleName: "evidence",
+      context: baseContext(1),
+    });
+    const restarted = await contextualize({
+      claim: { job: persistedJob },
+      moduleName: "evidence",
+      context: baseContext(2),
+    });
+    const opened = await (
+      restarted as typeof restarted & {
+        storage: {
+          openResourceFile(input: {
+            fileId: string;
+            purpose: string;
+            resourceType: string;
+            resourceId: string;
+          }): Promise<{ id: string; body: ReadableStream<Uint8Array> }>;
+        };
+      }
+    ).storage.openResourceFile({
+      fileId: file.id,
+      purpose: "evidence.raw",
+      resourceType: "evidence.evidence-file",
+      resourceId: "evidence-1",
+    });
+
+    expect(first).toMatchObject({
+      actor: { id: "user-reader" },
+      requestId: expect.any(String),
+    });
+    expect(opened.id).toBe(file.id);
+    expect("artifactRef" in opened).toBe(false);
+    expect(resolverCalls()).toBe(2);
+    expect(runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "evidence.file.read",
+        outcome: "success",
+        target: { type: "evidence.evidence-file", id: "evidence-1" },
+      }),
+    );
+  });
+
+  test("Scope 变化、权限撤销与资源绑定漂移均 fail-closed", async () => {
+    const stable = currentActor();
+    const scopeChanged = currentActor("self");
+    const setupScopeChanged = await setup(() => scopeChanged);
+    await expect(
+      setupScopeChanged.contextualize({
+        claim: { job: job(stable) },
+        moduleName: "evidence",
+        context: baseContext(1),
+      }),
+    ).rejects.toMatchObject({
+      code: "MODULE_AUTHORIZATION_SCOPE_CHANGED",
+      retryable: false,
+    });
+
+    const permissionRevoked = { ...stable, permissionKeys: [] };
+    const revoked = await setup(() => permissionRevoked);
+    const file = await seedFile(revoked.storage);
+    const context = await revoked.contextualize({
+      claim: { job: job(stable) },
+      moduleName: "evidence",
+      context: baseContext(1),
+    });
+    const storage = (
+      context as typeof context & {
+        storage: {
+          openResourceFile(input: {
+            fileId: string;
+            purpose: string;
+            resourceType: string;
+            resourceId: string;
+          }): Promise<unknown>;
+        };
+      }
+    ).storage;
+    await expect(
+      storage.openResourceFile({
+        fileId: file.id,
+        purpose: "evidence.raw",
+        resourceType: "evidence.evidence-file",
+        resourceId: "evidence-1",
+      }),
+    ).rejects.toThrow("资源文件访问未授权");
+    expect(revoked.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "evidence.file.read",
+        outcome: "denied",
+      }),
+    );
+  });
+});
+
+async function setup(
+  resolve: () => RequestActor = currentActor,
+  backgroundAi?: Parameters<
+    typeof createModuleDurableContextualizer
+  >[0]["backgroundAi"],
+) {
+  const hosts = await initializeModuleHosts({
+    modules: [evidenceManifest],
+    installations: [
+      {
+        manifest: evidenceManifest,
+        setup(host) {
+          host.registerUploadPolicy({
+            purpose: "evidence.raw",
+            maxByteSize: 1024,
+            maxPartByteSize: 512,
+            sessionTtlMs: 60_000,
+            allowedTypes: { "text/plain": ["txt"] },
+          });
+          host.registerResourceFileAccessPolicies([
+            {
+              purpose: "evidence.raw",
+              resourceType: "evidence.evidence-file",
+              featureKey: "evidence.catalog",
+              permissionKey: "evidence.read",
+              auditAction: "evidence.file.read",
+              authorize: ({ fileId, resourceId }, context) =>
+                fileId.startsWith("file_") &&
+                resourceId === "evidence-1" &&
+                context.actor.id === "user-reader",
+            },
+          ]);
+        },
+      },
+    ],
+  });
+  const storage = createStorageRuntime({}, undefined, hosts.uploadPolicies);
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    { featureCatalog: [evidenceFeature] },
+  );
+  let calls = 0;
+  return {
+    actor: currentActor(),
+    storage,
+    runtime,
+    resolverCalls: () => calls,
+    contextualize: createModuleDurableContextualizer({
+      hosts,
+      runtime,
+      features: [evidenceFeature],
+      storage,
+      backgroundAi,
+      async resolveActor() {
+        calls += 1;
+        return resolve();
+      },
+    }),
+  };
+}
+
+function currentActor(scope: "all" | "self" = "all"): RequestActor {
+  return {
+    id: "user-reader",
+    type: "user",
+    name: "物证读取者",
+    roleCodes: ["investigator"],
+    permissionKeys: ["evidence.read"],
+    ...buildActorScopeContexts("user-reader", "dept-case", [
+      {
+        id: "role-investigator",
+        code: "investigator",
+        dataScope: scope,
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function job(actor: RequestActor) {
+  return {
+    id: "job-evidence",
+    requestedBy: actor.id,
+    authorizationScope: captureAuthorizationScope(actor.scopeContext).snapshot,
+  };
+}
+
+function baseContext(attemptNumber: number): DurableHandlerContext {
+  return {
+    jobId: "job-evidence",
+    stageKey: "main",
+    attemptNumber,
+    signal: new AbortController().signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => undefined,
+  };
+}
+
+async function seedFile(storage: ReturnType<typeof createStorageRuntime>) {
+  const bytes = new TextEncoder().encode("evidence");
+  const sha256 = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+  const session = await storage.uploads.create({
+    ownerId: "user-uploader",
+    purpose: "evidence.raw",
+    filename: "evidence.txt",
+    mimeType: "text/plain",
+    expectedByteSize: bytes.length,
+    expectedSha256: sha256,
+  });
+  await storage.uploads.appendPart({
+    sessionId: session.id,
+    ownerId: "user-uploader",
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: bytes.length,
+    sha256,
+    body: new ReadableStream({
+      start(controller) {
+        controller.enqueue(bytes);
+        controller.close();
+      },
+    }),
+  });
+  return storage.uploads.complete(session.id, "user-uploader");
+}

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

@@ -0,0 +1,124 @@
+import {
+  DurableHandlerError,
+  type DurableHandlerContext,
+} from "@southwind-ai/jobs";
+import type {
+  AuthorizationScopeSnapshot,
+  FeatureFlagDefinition,
+} from "@southwind-ai/shared";
+import type {
+  ModuleBackgroundAiPort,
+  ModuleDurableHandlerContext,
+} from "@southwind-ai/server-sdk";
+import { ModuleBackgroundAiError } from "@southwind-ai/server-sdk";
+import {
+  captureAuthorizationScope,
+  hashAuthorizationScope,
+} from "../data-access/scope-snapshot.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+import {
+  createModuleStoragePort,
+  type ModuleStorageServices,
+} from "./storage-port.js";
+import { createModuleStorageScope } from "./storage-scope.js";
+import { toModuleActor } from "./request-context.js";
+
+export interface ModuleDurableContextServices {
+  readonly hosts: InitializedModuleHosts;
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly features: readonly FeatureFlagDefinition[];
+  readonly storage: ModuleStorageServices;
+  readonly backgroundAi?: {
+    create(
+      moduleName: string,
+      context: RequestGuardContext,
+      signal: AbortSignal,
+    ): ModuleBackgroundAiPort;
+  };
+  resolveActor(actorId: string): Promise<RequestActor | undefined>;
+}
+
+export function createModuleDurableContextualizer(
+  services: ModuleDurableContextServices,
+) {
+  return async (input: {
+    claim: {
+      job: {
+        id: string;
+        requestedBy: string;
+        authorizationScope?: AuthorizationScopeSnapshot;
+      };
+    };
+    moduleName?: string;
+    context: DurableHandlerContext;
+  }): Promise<DurableHandlerContext> => {
+    if (!input.moduleName) return input.context;
+    const snapshot = input.claim.job.authorizationScope;
+    if (!snapshot || snapshot.actorId !== input.claim.job.requestedBy) {
+      throw denied("MODULE_AUTHORIZATION_SCOPE_MISSING");
+    }
+    const actor = await services.resolveActor(input.claim.job.requestedBy);
+    if (!actor?.scopeContext) {
+      throw denied("MODULE_ACTOR_UNAVAILABLE");
+    }
+    const current = captureAuthorizationScope(actor.scopeContext);
+    if (current.hash !== hashAuthorizationScope(snapshot)) {
+      throw denied("MODULE_AUTHORIZATION_SCOPE_CHANGED");
+    }
+    const request = new Request(
+      `http://durable.internal/jobs/${encodeURIComponent(input.claim.job.id)}`,
+      { signal: input.context.signal },
+    );
+    const guardContext = await services.runtime.createGuardContextForActor(
+      request,
+      actor,
+    );
+    const storage = createModuleStoragePort(
+      services.storage,
+      createModuleStorageScope({
+        moduleName: input.moduleName,
+        purposes: services.hosts.uploadPurposesOf(input.moduleName),
+        resourceFileAccessPolicies: services.hosts.resourceFileAccessPoliciesOf(
+          input.moduleName,
+        ),
+        guardContext,
+        runtime: services.runtime,
+        features: services.features,
+        signal: input.context.signal,
+      }),
+    );
+    const moduleContext: ModuleDurableHandlerContext = {
+      ...input.context,
+      actor: toModuleActor(actor),
+      requestId: guardContext.requestId,
+      storage: {
+        openResourceFile: (request) => storage.openResourceFile(request),
+      },
+      ai:
+        services.backgroundAi?.create(
+          input.moduleName,
+          guardContext,
+          input.context.signal,
+        ) ?? unavailableBackgroundAi(input.moduleName),
+    };
+    return moduleContext;
+  };
+}
+
+function unavailableBackgroundAi(moduleName: string): ModuleBackgroundAiPort {
+  return {
+    async enqueueOperation() {
+      throw new ModuleBackgroundAiError(
+        "AI_OPERATION_UNAVAILABLE",
+        `模块 ${moduleName} 的后台 AI Operation Port 未挂载`,
+        true,
+      );
+    },
+  };
+}
+
+function denied(code: string) {
+  return new DurableHandlerError(code, "模块后台任务授权已失效", false);
+}

package/template/apps/server/src/module-host/durable-handler-registration.ts

@@ -0,0 +1,72 @@
+import {
+  DurableHandlerError,
+  type DurableHandlerContext,
+  type DurableHandlerDefinition,
+  type DurableHandlerRegistry,
+} from "@southwind-ai/jobs";
+import type {
+  ModuleDurableHandlerContext,
+  ModuleDurableHandlerDefinition,
+} from "@southwind-ai/server-sdk";
+import { ModuleBackgroundAiError } from "@southwind-ai/server-sdk";
+
+export interface DurableHandlerRegistrationState {
+  readonly handlerKeys: Set<string>;
+  readonly handlerInstallers: Array<(registry: DurableHandlerRegistry) => void>;
+}
+
+export function registerModuleDurableHandler<T>(
+  moduleName: string,
+  state: DurableHandlerRegistrationState,
+  definition: ModuleDurableHandlerDefinition<T>,
+) {
+  if (state.handlerKeys.has(definition.key)) {
+    throw new Error(`任务 handler 重复注册：${definition.key}`);
+  }
+  state.handlerKeys.add(definition.key);
+  state.handlerInstallers.push((registry) => {
+    registry.register(
+      {
+        key: definition.key,
+        payload: definition.payload,
+        async execute(payload, context) {
+          try {
+            await definition.execute(
+              payload,
+              requireModuleDurableContext(context, moduleName),
+            );
+          } catch (error) {
+            if (error instanceof ModuleBackgroundAiError) {
+              throw new DurableHandlerError(
+                error.code,
+                error.message,
+                error.retryable,
+              );
+            }
+            throw error;
+          }
+        },
+      },
+      { moduleName },
+    );
+  });
+}
+
+function requireModuleDurableContext(
+  context: Parameters<DurableHandlerDefinition<unknown>["execute"]>[1],
+  moduleName: string,
+): ModuleDurableHandlerContext {
+  if (
+    !("actor" in context) ||
+    !("requestId" in context) ||
+    !("storage" in context) ||
+    !("ai" in context)
+  ) {
+    throw new DurableHandlerError(
+      "MODULE_DURABLE_CONTEXT_UNAVAILABLE",
+      `模块 ${moduleName} 的后台授权上下文不可用`,
+      false,
+    );
+  }
+  return context as DurableHandlerContext & ModuleDurableHandlerContext;
+}

package/template/apps/server/src/module-host/governed-export-route-support.ts

@@ -0,0 +1,171 @@
+import type {
+  DataGovernancePolicyDefinition,
+  JsonValue,
+} from "@southwind-ai/shared";
+import type { ModuleGovernedResourceRegistration } from "@southwind-ai/server-sdk";
+import { DurableArtifactError } from "../jobs/artifact-service.js";
+import {
+  GovernedExportServiceError,
+  type GovernedExportTarget,
+} from "../data-governance/export/service.js";
+import type { GovernedExportRequest } from "../data-governance/export/types.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+
+export function exportTarget(
+  registration: ModuleGovernedResourceRegistration,
+  policy: DataGovernancePolicyDefinition,
+): GovernedExportTarget {
+  return {
+    resourceType: policy.resourceType,
+    policyKey: policy.key,
+    policyVersion: policy.version,
+    fieldKeys: policy.fields.map(({ fieldKey }) => fieldKey),
+    approvalRequired: registration.export?.approvalRequired,
+    retentionSeconds: registration.export?.retentionSeconds,
+    ...(registration.export?.renderers
+      ? {
+          renderers: registration.export.renderers.map((renderer) => ({
+            formatKey: renderer.formatKey,
+            templateKey: renderer.templateKey,
+            templateVersion: renderer.templateVersion,
+            inputSchemaKey: renderer.inputSchemaKey,
+            contentType: renderer.contentType,
+            filenameExtension: renderer.filenameExtension,
+            ...renderer.limits,
+          })),
+        }
+      : {}),
+  };
+}
+
+export function parseCreate(
+  body: unknown,
+  registration: ModuleGovernedResourceRegistration,
+) {
+  const value = strictObject(body, [
+    "idempotencyKey",
+    "reason",
+    "query",
+    "formatKey",
+  ]);
+  try {
+    const query = registration.export!.validateQuery(value.query ?? {});
+    if (!isJsonValue(query) || JSON.stringify(query).length > 64_000) {
+      throw new Error("invalid query");
+    }
+    const formatKey = optionalString(value.formatKey);
+    return {
+      idempotencyKey: requiredString(value.idempotencyKey),
+      reason: requiredString(value.reason),
+      query,
+      ...(formatKey === undefined ? {} : { formatKey }),
+    };
+  } catch (error) {
+    if (error instanceof GovernedExportServiceError) throw error;
+    throw new GovernedExportServiceError("EXPORT_QUERY_INVALID", 400);
+  }
+}
+
+function isJsonValue(value: unknown, depth = 0): value is JsonValue {
+  if (depth > 10) return false;
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return true;
+  }
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    return (
+      value.length <= 1_000 &&
+      value.every((item) => isJsonValue(item, depth + 1))
+    );
+  }
+  if (
+    typeof value !== "object" ||
+    Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    return false;
+  }
+  const entries = Object.entries(value);
+  return (
+    entries.length <= 100 &&
+    entries.every(
+      ([key, item]) => key.length <= 160 && isJsonValue(item, depth + 1),
+    )
+  );
+}
+
+export function strictObject(value: unknown, keys: readonly string[]) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new GovernedExportServiceError("EXPORT_INPUT_INVALID", 400);
+  }
+  const object = value as Record<string, unknown>;
+  if (Object.keys(object).some((key) => !keys.includes(key))) {
+    throw new GovernedExportServiceError("EXPORT_INPUT_INVALID", 400);
+  }
+  return object;
+}
+
+export function required(value: string | undefined) {
+  if (!value) throw new GovernedExportServiceError("EXPORT_NOT_FOUND", 404);
+  return value;
+}
+
+export function requiredString(value: unknown) {
+  if (typeof value !== "string") {
+    throw new GovernedExportServiceError("EXPORT_INPUT_INVALID", 400);
+  }
+  return value;
+}
+
+export function optionalString(value: unknown) {
+  return value === undefined ? undefined : requiredString(value);
+}
+
+export function project(request: GovernedExportRequest) {
+  return {
+    id: request.id,
+    resourceType: request.resourceType,
+    status: request.status,
+    approvalRequired: request.approvalRequired,
+    approvalId: request.approvalId,
+    jobId: request.durableJobId,
+    expiresAt: request.expiresAt,
+    createdAt: request.createdAt,
+    updatedAt: request.updatedAt,
+    formatKey: request.renderer.formatKey,
+    templateKey: request.renderer.templateKey,
+    templateVersion: request.renderer.templateVersion,
+  };
+}
+
+export function knownError(error: unknown): Response {
+  if (error instanceof GovernedExportServiceError) {
+    return Response.json({ error: error.code }, { status: error.status });
+  }
+  if (error instanceof DurableArtifactError) {
+    return Response.json(
+      { error: error.code },
+      { status: error.code === "ARTIFACT_EXPIRED" ? 410 : 409 },
+    );
+  }
+  throw error;
+}
+
+export function requirePolicy(
+  hosts: InitializedModuleHosts,
+  moduleName: string,
+  policyKey: string,
+) {
+  const policy = hosts
+    .manifestOf(moduleName)
+    .dataPolicies?.find(({ key }) => key === policyKey);
+  if (!policy) throw new Error(`模块数据治理策略不存在：${policyKey}`);
+  return policy;
+}
+
+export function stripApiPrefix(path: string) {
+  return path.slice("/api".length);
+}