create-windy 0.3.2 → 0.3.5

package/template/apps/server/src/module-host/governed-renderer-registration.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  ModuleGovernedExportRegistration,
+  ModuleGovernedResourceRegistration,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("业务模块治理导出 Renderer 注册", () => {
+  test("同一资源可注册 NDJSON、PDF、DOCX 与 XLSX", async () => {
+    const declared = exportManifest();
+    const hosts = await initializeModuleHosts({
+      modules: [declared],
+      installations: [
+        {
+          manifest: declared,
+          setup(host) {
+            host.registerGovernedResources([resource()]);
+          },
+        },
+      ],
+    });
+    expect(
+      hosts.governedResources[0]?.registration.export?.renderers?.map(
+        ({ formatKey }) => formatKey,
+      ),
+    ).toEqual(["ndjson", "pdf", "docx", "xlsx"]);
+  });
+
+  test("重复格式、未知 Schema 和越界 limits 在监听前 fail closed", async () => {
+    await expectInvalid(
+      (configured) => ({
+        ...configured,
+        renderers: [
+          configured.renderers![0]!,
+          { ...configured.renderers![0]!, templateVersion: "2" },
+        ],
+      }),
+      "formatKey 无效或重复",
+    );
+    await expectInvalid(
+      (configured) => ({
+        ...configured,
+        renderers: [
+          {
+            ...configured.renderers![0]!,
+            inputSchemaKey: "reports.missing.v1",
+          },
+        ],
+      }),
+      "未注册 JSON Schema",
+    );
+    await expectInvalid(
+      (configured) => ({
+        ...configured,
+        renderers: [
+          {
+            ...configured.renderers![0]!,
+            limits: {
+              ...configured.renderers![0]!.limits,
+              timeoutSeconds: 901,
+            },
+          },
+        ],
+      }),
+      "元数据或上限无效",
+    );
+  });
+});
+
+async function expectInvalid(
+  change: (
+    configured: ModuleGovernedExportRegistration,
+  ) => ModuleGovernedExportRegistration,
+  message: string,
+) {
+  const declared = exportManifest();
+  await expect(
+    initializeModuleHosts({
+      modules: [declared],
+      installations: [
+        {
+          manifest: declared,
+          setup(host) {
+            const base = resource();
+            host.registerGovernedResources([
+              { ...base, export: change(base.export!) },
+            ]);
+          },
+        },
+      ],
+    }),
+  ).rejects.toThrow(message);
+}
+
+function resource(): ModuleGovernedResourceRegistration {
+  return {
+    policyKey: "reports.official.fields",
+    readPath: "/api/reports/official/:id",
+    revealPath: "/api/reports/official/:id/plaintext",
+    revealAuditAction: "reports.official.reveal",
+    authorize: () => true,
+    read: () => undefined,
+    export: exportRegistration(),
+  };
+}
+
+function exportRegistration(): ModuleGovernedExportRegistration {
+  const formats = [
+    ["ndjson", "application/x-ndjson"],
+    ["pdf", "application/pdf"],
+    [
+      "docx",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ],
+    [
+      "xlsx",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ],
+  ] as const;
+  return {
+    basePath: "/api/reports/official/exports",
+    validateQuery: () => ({}),
+    readPage: () => ({ records: [] }),
+    renderers: formats.map(([formatKey, contentType]) => ({
+      formatKey,
+      templateKey: `reports.official.${formatKey}`,
+      templateVersion: "1.0.0",
+      inputSchemaKey: "reports.official.input.v1",
+      contentType,
+      filenameExtension: formatKey,
+      limits: {
+        maxRecords: 10_000,
+        maxOutputBytes: 20 * 1024 * 1024,
+        timeoutSeconds: 120,
+      },
+      render: () => ({ body: new ReadableStream<Uint8Array>() }),
+    })),
+  };
+}
+
+function exportManifest(): ModuleManifest {
+  const feature = featureKey("reports.official");
+  const declared = manifest("reports", {
+    permissions: [
+      permission("reports.official.read", "standard"),
+      permission("reports.official.reveal", "sensitive-disclosure"),
+      permission("reports.official.export", "governed-export"),
+    ],
+    features: [
+      {
+        key: feature,
+        label: "正式报告",
+        module: "reports",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    jsonSchemas: [
+      {
+        key: "reports.official.input.v1",
+        schema: { type: "object", properties: {} },
+      },
+    ],
+    dataPolicies: [
+      {
+        key: "reports.official.fields",
+        resourceType: "reports.official",
+        version: "1",
+        featureKey: feature,
+        readPermissionKey: "reports.official.read",
+        revealPermissionKey: "reports.official.reveal",
+        exportPermissionKey: "reports.official.export",
+        display: {
+          read: "masked",
+          reveal: "plaintext",
+          unauthorized: "hidden",
+        },
+        fields: [
+          {
+            fieldKey: "content",
+            classification: "sensitive",
+            mask: { kind: "redact" },
+          },
+        ],
+      },
+    ],
+    auditActions: ["reports.official.reveal"],
+  });
+  declared.apiPermissions = [
+    route("GET", "/api/reports/official/:id", "reports.official.read", feature),
+    route(
+      "POST",
+      "/api/reports/official/:id/plaintext",
+      "reports.official.reveal",
+      feature,
+    ),
+    ...(
+      [
+        ["POST", ""],
+        ["GET", "/:id"],
+        ["POST", "/:id/cancel"],
+        ["GET", "/:id/download"],
+      ] as const
+    ).map(([method, suffix]) => {
+      return route(
+        method,
+        `/api/reports/official/exports${suffix}`,
+        "reports.official.export",
+        feature,
+      );
+    }),
+  ];
+  return declared;
+}
+
+function permission(
+  key: string,
+  accessRisk: "standard" | "sensitive-disclosure" | "governed-export",
+) {
+  return {
+    key,
+    label: key,
+    module: "reports",
+    moduleLabel: "报告",
+    resource: "official",
+    resourceLabel: "正式报告",
+    action: key.endsWith(".read")
+      ? ("read" as const)
+      : key.endsWith(".reveal")
+        ? ("reveal" as const)
+        : ("export" as const),
+    accessRisk,
+  };
+}
+
+function route(
+  method: "GET" | "POST",
+  path: string,
+  permissionKey: string,
+  feature: ReturnType<typeof featureKey>,
+) {
+  return { method, path, permissionKey, featureKey: feature };
+}

package/template/apps/server/src/module-host/governed-resource-routes.ts

@@ -0,0 +1,331 @@
+import type {
+  DataGovernancePolicyDefinition,
+  FeatureFlagDefinition,
+} from "@southwind-ai/shared";
+import { maskGovernedValue } from "@southwind-ai/shared";
+import type {
+  ModuleGovernedRecord,
+  ModuleGovernedResourceRegistration,
+} from "@southwind-ai/server-sdk";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+import {
+  issuePlaintextAccessGrant,
+  plaintextResult,
+  PlaintextAccessDeniedError,
+} from "../data-governance/plaintext-access.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+import { toModuleActor } from "./request-context.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface ModuleGovernedRouteContext {
+  readonly runtime: ServerRuntime;
+  readonly features: readonly FeatureFlagDefinition[];
+  reauthenticate(actorId: string, password: string): Promise<boolean>;
+}
+
+export function installModuleGovernedResourceRoutes(
+  hosts: InitializedModuleHosts,
+  app: RouteApp,
+  context: ModuleGovernedRouteContext,
+) {
+  for (const { moduleName, registration } of hosts.governedResources) {
+    const policy = requirePolicy(hosts, moduleName, registration.policyKey);
+    installMaskedRoute(app, registration, policy, context);
+    installRevealRoute(app, registration, policy, context);
+  }
+}
+
+function installMaskedRoute(
+  app: RouteApp,
+  registration: ModuleGovernedResourceRegistration,
+  policy: DataGovernancePolicyDefinition,
+  context: ModuleGovernedRouteContext,
+) {
+  app.get(stripApiPrefix(registration.readPath), async (raw) => {
+    const route = routeContext(raw);
+    const allowed = await authorizeRoute(
+      context,
+      route.guardContext,
+      "GET",
+      registration.readPath,
+      policy.readPermissionKey,
+      policy,
+    );
+    if (!allowed) return forbidden();
+    const record = await authorizedRecord(
+      registration,
+      requiredId(route.params.id),
+      route.guardContext,
+    );
+    return record ? maskedProjection(record, policy) : notFound();
+  });
+}
+
+function installRevealRoute(
+  app: RouteApp,
+  registration: ModuleGovernedResourceRegistration,
+  policy: DataGovernancePolicyDefinition,
+  context: ModuleGovernedRouteContext,
+) {
+  app.post(stripApiPrefix(registration.revealPath), async (raw) => {
+    const route = routeContext(raw);
+    const allowed = await authorizeRoute(
+      context,
+      route.guardContext,
+      "POST",
+      registration.revealPath,
+      policy.revealPermissionKey,
+      policy,
+    );
+    if (!allowed) return forbidden();
+    const input = parseRevealInput(route.body, policy);
+    if (input instanceof Response) return input;
+    const resourceId = requiredId(route.params.id);
+    if (
+      !(await context.reauthenticate(
+        route.guardContext.actor.id,
+        input.password,
+      ))
+    ) {
+      await auditReveal(
+        context.runtime,
+        route.guardContext,
+        registration,
+        policy,
+        resourceId,
+        input,
+        "denied",
+      );
+      return forbidden();
+    }
+    const record = await authorizedRecord(
+      registration,
+      resourceId,
+      route.guardContext,
+    );
+    if (!record) return notFound();
+    const grant = issuePlaintextAccessGrant({
+      actor: route.guardContext.actor,
+      requestId: route.guardContext.requestId,
+      policy,
+      fieldKeys: input.fieldKeys,
+    });
+    const projection = plaintextProjection(
+      record,
+      policy,
+      grant,
+      input.fieldKeys,
+    );
+    await auditReveal(
+      context.runtime,
+      route.guardContext,
+      registration,
+      policy,
+      resourceId,
+      input,
+      "success",
+    );
+    return projection;
+  });
+}
+
+async function authorizedRecord(
+  registration: ModuleGovernedResourceRegistration,
+  resourceId: string,
+  guardContext: ReturnType<typeof routeContext>["guardContext"],
+) {
+  const moduleContext = {
+    actor: toModuleActor(guardContext.actor),
+    requestId: guardContext.requestId,
+    signal: new AbortController().signal,
+  };
+  try {
+    if (!(await registration.authorize(resourceId, moduleContext))) {
+      return undefined;
+    }
+    const record = await registration.read(resourceId, moduleContext);
+    return record?.id === resourceId ? record : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function maskedProjection(
+  record: ModuleGovernedRecord,
+  policy: DataGovernancePolicyDefinition,
+) {
+  validateRecord(record, policy);
+  return {
+    id: record.id,
+    ...record.publicFields,
+    governedFields: Object.fromEntries(
+      policy.fields.map((field) => [
+        field.fieldKey,
+        maskGovernedValue(record.governedFields[field.fieldKey], field),
+      ]),
+    ),
+  };
+}
+
+function plaintextProjection(
+  record: ModuleGovernedRecord,
+  policy: DataGovernancePolicyDefinition,
+  grant: ReturnType<typeof issuePlaintextAccessGrant>,
+  fieldKeys: readonly string[],
+) {
+  validateRecord(record, policy);
+  return {
+    id: record.id,
+    ...record.publicFields,
+    governedFields: Object.fromEntries(
+      policy.fields
+        .filter(({ fieldKey }) => fieldKeys.includes(fieldKey))
+        .map((field) => [
+          field.fieldKey,
+          plaintextResult({
+            value: record.governedFields[field.fieldKey],
+            field,
+            policy,
+            grant,
+          }),
+        ]),
+    ),
+  };
+}
+
+function validateRecord(
+  record: ModuleGovernedRecord,
+  policy: DataGovernancePolicyDefinition,
+) {
+  const governed = new Set(policy.fields.map(({ fieldKey }) => fieldKey));
+  if (
+    Object.keys(record.governedFields).some((key) => !governed.has(key)) ||
+    Object.keys(record.publicFields).some((key) => governed.has(key))
+  ) {
+    throw new PlaintextAccessDeniedError("业务治理投影与 Manifest 不一致");
+  }
+}
+
+async function authorizeRoute(
+  context: ModuleGovernedRouteContext,
+  guardContext: ReturnType<typeof routeContext>["guardContext"],
+  method: "GET" | "POST",
+  path: string,
+  permissionKey: string,
+  policy: DataGovernancePolicyDefinition,
+) {
+  const feature = findFeature([...context.features], policy.featureKey);
+  if (!feature) return false;
+  return (
+    await evaluateRouteGuards(context.runtime, guardContext, {
+      permission: {
+        method,
+        path,
+        permissionKey,
+        featureKey: policy.featureKey,
+      },
+      feature,
+    })
+  ).allowed;
+}
+
+function parseRevealInput(
+  body: unknown,
+  policy: DataGovernancePolicyDefinition,
+): { reason: string; password: string; fieldKeys: string[] } | Response {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return invalid();
+  }
+  const value = body as Record<string, unknown>;
+  if (
+    Object.keys(value).some(
+      (key) => !["reason", "password", "fieldKeys"].includes(key),
+    ) ||
+    typeof value.reason !== "string" ||
+    value.reason.trim().length < 5 ||
+    value.reason.length > 200 ||
+    typeof value.password !== "string" ||
+    !Array.isArray(value.fieldKeys)
+  ) {
+    return invalid();
+  }
+  const registered = new Set(policy.fields.map(({ fieldKey }) => fieldKey));
+  const fieldKeys = [
+    ...new Set(
+      value.fieldKeys.filter(
+        (key): key is string => typeof key === "string" && registered.has(key),
+      ),
+    ),
+  ].sort();
+  return fieldKeys.length === value.fieldKeys.length && fieldKeys.length > 0
+    ? { reason: value.reason.trim(), password: value.password, fieldKeys }
+    : invalid();
+}
+
+async function auditReveal(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  registration: ModuleGovernedResourceRegistration,
+  policy: DataGovernancePolicyDefinition,
+  resourceId: string,
+  input: { reason: string; fieldKeys: string[] },
+  outcome: "success" | "denied",
+) {
+  await runtime.auditSink.recordCriticalEvent({
+    id: Bun.randomUUIDv7(),
+    action: registration.revealAuditAction,
+    outcome,
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "service" ? "service" : "user",
+      name: context.actor.name,
+      roleCodes: context.actor.roleCodes,
+    },
+    target: { type: policy.resourceType, id: resourceId },
+    requestId: context.requestId,
+    metadata: {
+      policyKey: policy.key,
+      policyVersion: policy.version,
+      fieldKeys: input.fieldKeys,
+      reason: input.reason,
+    },
+    occurredAt: new Date().toISOString(),
+  });
+}
+
+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;
+}
+
+function stripApiPrefix(path: string) {
+  return path.slice("/api".length);
+}
+
+function requiredId(id: string | undefined) {
+  if (!id) throw new Error("业务治理资源缺少 ID");
+  return id;
+}
+
+function forbidden() {
+  return Response.json({ error: "FORBIDDEN" }, { status: 403 });
+}
+
+function notFound() {
+  return Response.json({ error: "NOT_FOUND" }, { status: 404 });
+}
+
+function invalid() {
+  return Response.json({ error: "INVALID_REVEAL_REQUEST" }, { status: 400 });
+}