create-windy 0.1.0

package/template/apps/server/src/data-governance/user-plaintext-routes.test.ts

@@ -0,0 +1,287 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime, type AuditEventWriter } from "../runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { registerSystemRoutes } from "../system/routes.js";
+import { createSystemRepositories } from "../system/seed.js";
+import { buildScopeContext } from "../data-access/context.js";
+
+describe("用户敏感字段 API", () => {
+  test("普通列表和详情始终返回掩码结果，用户同步导出入口不存在", async () => {
+    const { app, guardContext, repositories } = await fixture();
+    await addSensitiveValues(repositories, guardContext.actor);
+
+    const listed = await app.invoke("GET", "/system/users", {
+      guardContext,
+      params: {},
+      query: {},
+    });
+    const detail = await app.invoke("GET", "/system/users/:id", {
+      guardContext,
+      params: { id: "user_dev_admin" },
+      query: {},
+    });
+    const serialized = JSON.stringify([listed, detail]);
+
+    expect(serialized).toContain("138****8000");
+    expect(serialized).not.toContain("13800138000");
+    expect(serialized).not.toContain("secret@example.com");
+    expect(app.handlers.has("GET /system/users/export")).toBe(false);
+  });
+
+  test("read 或客户端伪造上下文不能调用明文路由", async () => {
+    const { app, guardContext, repositories } = await fixture();
+    await addSensitiveValues(repositories, guardContext.actor);
+
+    const denied = (await app.invoke("GET", "/system/users/:id/plaintext", {
+      guardContext,
+      params: { id: "user_dev_admin" },
+      query: { role: "super-admin", scope: "all" },
+    })) as Response;
+    const invalidBatch = (await app.invoke(
+      "POST",
+      "/system/users/plaintext/batch",
+      {
+        guardContext: withReveal(guardContext),
+        params: {},
+        query: {},
+        body: { ids: ["user_dev_admin"], roleCodes: ["super-admin"] },
+      },
+    )) as Response;
+
+    expect(denied.status).toBe(403);
+    expect(invalidBatch.status).toBe(400);
+  });
+
+  test("单条和批量明文分别执行 SQL Scope、独立 Guard 与关键审计", async () => {
+    const policies: string[] = [];
+    const writer: AuditEventWriter = {
+      write: async (_event, policy) => void policies.push(policy || "ordinary"),
+    };
+    const { app, guardContext, repositories, runtime } = await fixture(writer);
+    await addSensitiveValues(repositories, guardContext.actor);
+    await repositories.users.create(
+      {
+        id: "user_outside",
+        username: "outside",
+        displayName: "范围外用户",
+        email: "outside@example.com",
+        phone: "13900139000",
+        roleIds: ["role_user"],
+        departmentId: "dept_platform",
+      },
+      guardContext.actor,
+    );
+    const revealContext = withReveal(guardContext);
+    revealContext.actor = {
+      ...revealContext.actor,
+      scopeContext: buildScopeContext("user_dev_admin", "dept_platform", [
+        {
+          id: "role_self",
+          code: "self",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    };
+
+    const detail = (await app.invoke("GET", "/system/users/:id/plaintext", {
+      guardContext: revealContext,
+      params: { id: "user_dev_admin" },
+      query: {},
+    })) as Record<string, unknown>;
+    const batch = (await app.invoke("POST", "/system/users/plaintext/batch", {
+      guardContext: revealContext,
+      params: {},
+      query: {},
+      body: { ids: ["user_dev_admin"] },
+    })) as { items: Array<Record<string, unknown>> };
+    const outside = (await app.invoke("GET", "/system/users/:id/plaintext", {
+      guardContext: revealContext,
+      params: { id: "user_outside" },
+      query: { scope: "all" },
+    })) as Response;
+
+    expect(detail.phone).toMatchObject({
+      kind: "plaintext",
+      value: "13800138000",
+    });
+    expect(batch.items[0]?.email).toMatchObject({
+      kind: "plaintext",
+      value: "secret@example.com",
+    });
+    expect(outside.status).toBe(403);
+    expect(policies).toEqual(["critical", "critical"]);
+    expect(runtime.auditSink.list().map(({ action }) => action)).toEqual([
+      "data.plaintext.read",
+      "data.plaintext.batch-read",
+    ]);
+    expect(JSON.stringify(runtime.auditSink.list())).not.toContain(
+      "13800138000",
+    );
+    expect(JSON.stringify(runtime.auditSink.list())).not.toContain(
+      "secret@example.com",
+    );
+  });
+
+  test("关键审计不可持久化时不返回已经读取的明文", async () => {
+    const { app, guardContext, repositories } = await fixture({
+      write: async () => {
+        throw new Error("audit unavailable");
+      },
+    });
+    await addSensitiveValues(repositories, guardContext.actor);
+
+    await expect(
+      app.invoke("GET", "/system/users/:id/plaintext", {
+        guardContext: withReveal(guardContext),
+        params: { id: "user_dev_admin" },
+        query: {},
+      }),
+    ).rejects.toThrow("audit unavailable");
+  });
+
+  test("批量输入按 trim、去重和排序形成稳定摘要", async () => {
+    const { app, guardContext, repositories, runtime } = await fixture();
+    await addSensitiveValues(repositories, guardContext.actor);
+    await repositories.users.create(
+      {
+        id: "user_batch_second",
+        username: "batch-second",
+        displayName: "批量用户",
+        roleIds: ["role_user"],
+        departmentId: "dept_platform",
+      },
+      guardContext.actor,
+    );
+    const context = withReveal(guardContext);
+
+    for (const ids of [
+      [" user_dev_admin", "user_batch_second", "user_dev_admin"],
+      ["user_batch_second", "user_dev_admin"],
+    ]) {
+      const response = (await app.invoke(
+        "POST",
+        "/system/users/plaintext/batch",
+        { guardContext: context, params: {}, query: {}, body: { ids } },
+      )) as { items: unknown[] };
+      expect(response.items).toHaveLength(2);
+    }
+
+    const events = runtime.auditSink
+      .list()
+      .filter(({ action }) => action === "data.plaintext.batch-read");
+    expect(events.map(({ outcome }) => outcome)).toEqual([
+      "success",
+      "success",
+    ]);
+    expect(events[0]?.metadata).toEqual(events[1]?.metadata);
+    expect(events[0]?.metadata).toMatchObject({
+      requestedCount: 2,
+      returnedCount: 2,
+    });
+    const serializedMetadata = JSON.stringify(
+      events.map(({ metadata }) => metadata),
+    );
+    expect(serializedMetadata).not.toContain("user_dev_admin");
+    expect(serializedMetadata).not.toContain("user_batch_second");
+  });
+
+  test("批量 missing 与 scope denied 均整体 403 并写关键拒绝审计", async () => {
+    const policies: string[] = [];
+    const { app, guardContext, repositories, runtime } = await fixture({
+      write: async (_event, policy) => void policies.push(policy || "ordinary"),
+    });
+    await addSensitiveValues(repositories, guardContext.actor);
+    await repositories.users.create(
+      {
+        id: "user_outside",
+        username: "outside",
+        displayName: "范围外用户",
+        roleIds: ["role_user"],
+        departmentId: "dept_platform",
+      },
+      guardContext.actor,
+    );
+    const context = withReveal(guardContext);
+    context.actor = {
+      ...context.actor,
+      scopeContext: buildScopeContext("user_dev_admin", "dept_platform", [
+        {
+          id: "role_self",
+          code: "self",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    };
+
+    const responses: Response[] = [];
+    for (const ids of [
+      ["user_dev_admin", "user_missing"],
+      ["user_dev_admin", "user_outside"],
+    ]) {
+      responses.push(
+        (await app.invoke("POST", "/system/users/plaintext/batch", {
+          guardContext: context,
+          params: {},
+          query: {},
+          body: { ids },
+        })) as Response,
+      );
+    }
+
+    expect(responses.map(({ status }) => status)).toEqual([403, 403]);
+    expect(await responses[0]!.clone().text()).toBe(
+      await responses[1]!.clone().text(),
+    );
+    const denied = runtime.auditSink
+      .list()
+      .filter(({ action }) => action === "data.plaintext.batch-read");
+    expect(denied.map(({ outcome }) => outcome)).toEqual(["denied", "denied"]);
+    expect(denied.map(({ metadata }) => metadata?.returnedCount)).toEqual([
+      0, 0,
+    ]);
+    expect(policies).toEqual(["critical", "critical"]);
+  });
+});
+
+async function fixture(auditWriter?: AuditEventWriter) {
+  const snapshot = createFoundationSnapshot();
+  const repositories = createSystemRepositories(snapshot);
+  const runtime = createServerRuntime(
+    { WINDY_DEV_ADMIN_TOKEN: "token" },
+    { auditWriter },
+  );
+  const app = new FakeRouteApp();
+  registerSystemRoutes(app, repositories, runtime, snapshot.features);
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/system/users", {
+      headers: { authorization: "Bearer token" },
+    }),
+  );
+  return { app, guardContext, repositories, runtime };
+}
+
+function withReveal<T extends { actor: { permissionKeys: string[] } }>(
+  context: T,
+): T {
+  return {
+    ...context,
+    actor: {
+      ...context.actor,
+      permissionKeys: [...context.actor.permissionKeys, "system.user.reveal"],
+    },
+  };
+}
+
+async function addSensitiveValues(
+  repositories: ReturnType<typeof createSystemRepositories>,
+  actor: Parameters<typeof repositories.users.update>[2],
+) {
+  await repositories.users.update(
+    "user_dev_admin",
+    { email: "secret@example.com", phone: "13800138000" },
+    actor,
+  );
+}

package/template/apps/server/src/data-governance/user-plaintext-routes.ts

@@ -0,0 +1,181 @@
+import type { AuditOutcome } from "@windy/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { ManagedUser } from "../system/entities.js";
+import type { ResourceRouteConfig, RouteApp } from "../system/route-types.js";
+import { routeContext, resourceEvent } from "../system/route-helpers.js";
+import { accessCall } from "../system/resource-access-response.js";
+import { evaluateRouteGuards, routeForbidden } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { systemUserDataPolicy } from "./user-projection.js";
+import { UserSensitiveReadService } from "./user-sensitive-read-service.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+const plaintextFields = ["email", "phone"] as const;
+
+export function registerUserPlaintextRoutes(
+  app: RouteApp,
+  config: ResourceRouteConfig<ManagedUser>,
+  runtime: ServerRuntime,
+) {
+  const sensitiveReads = new UserSensitiveReadService(config);
+  app.get("/system/users/:id/plaintext", (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return withRevealPermission(
+      runtime,
+      guardContext,
+      config,
+      "GET",
+      "/api/system/users/:id/plaintext",
+      async () => {
+        const user = await accessCall(() =>
+          sensitiveReads.read(
+            requiredUserId(params.id),
+            guardContext.actor,
+            guardContext.requestId,
+          ),
+        );
+        if (user instanceof Response) return user;
+        if (!user) return userNotFound(requiredUserId(params.id));
+        const policy = systemUserDataPolicy();
+        await runtime.auditSink.recordCriticalEvent(
+          resourceEvent(
+            guardContext,
+            "data.plaintext.read",
+            "users",
+            String(user.id),
+            disclosureMetadata(policy.key, policy.version, 1),
+          ),
+        );
+        return user;
+      },
+    );
+  });
+
+  app.post("/system/users/plaintext/batch", async (rawContext) => {
+    const { guardContext, body } = routeContext(rawContext);
+    const decision = await revealDecision(
+      runtime,
+      guardContext,
+      config,
+      "POST",
+      "/api/system/users/plaintext/batch",
+    );
+    const ids = parseBatchIds(body);
+    if (!decision.allowed) {
+      if (!(ids instanceof Response)) {
+        await recordBatchAudit(runtime, guardContext, ids, "denied", 0);
+      }
+      return routeForbidden(decision.reason);
+    }
+    if (ids instanceof Response) return ids;
+    const users = await accessCall(() =>
+      sensitiveReads.batch(ids, guardContext.actor, guardContext.requestId),
+    );
+    if (users instanceof Response || !users) {
+      await recordBatchAudit(runtime, guardContext, ids, "denied", 0);
+      return routeForbidden("batch-scope-or-member-denied");
+    }
+    await recordBatchAudit(runtime, guardContext, ids, "success", users.length);
+    return { items: users };
+  });
+}
+
+async function withRevealPermission(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  config: ResourceRouteConfig<ManagedUser>,
+  method: "GET" | "POST",
+  path: string,
+  handler: () => unknown,
+) {
+  const decision = await revealDecision(runtime, context, config, method, path);
+  return decision.allowed ? handler() : routeForbidden(decision.reason);
+}
+
+function revealDecision(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  config: ResourceRouteConfig<ManagedUser>,
+  method: "GET" | "POST",
+  path: string,
+) {
+  return evaluateRouteGuards(runtime, context, {
+    permission: {
+      method,
+      path,
+      permissionKey: systemUserDataPolicy().revealPermissionKey,
+    },
+    feature: config.feature,
+  });
+}
+
+function parseBatchIds(body: unknown): string[] | Response {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return invalidBatch("请求体必须只包含 ids 数组");
+  }
+  const payload = body as Record<string, unknown>;
+  if (Object.keys(payload).some((key) => key !== "ids")) {
+    return invalidBatch("批量明文查询不接受角色、数据范围或其他客户端上下文");
+  }
+  if (!Array.isArray(payload.ids)) return invalidBatch("ids 必须是数组");
+  if (payload.ids.some((id) => typeof id !== "string" || !id.trim())) {
+    return invalidBatch("ids 必须包含 1 到 100 个非空字符串");
+  }
+  const ids = [
+    ...new Set((payload.ids as string[]).map((id) => id.trim())),
+  ].sort();
+  if (ids.length < 1 || ids.length > 100) {
+    return invalidBatch("ids 去重后必须包含 1 到 100 个非空字符串");
+  }
+  return ids;
+}
+
+async function recordBatchAudit(
+  runtime: ServerRuntime,
+  context: RequestGuardContext,
+  ids: readonly string[],
+  outcome: Extract<AuditOutcome, "success" | "denied">,
+  returnedCount: number,
+) {
+  const event = resourceEvent(
+    context,
+    "data.plaintext.batch-read",
+    "users",
+    undefined,
+    {
+      idSetDigest: new Bun.CryptoHasher("sha256")
+        .update(JSON.stringify(ids))
+        .digest("hex"),
+      requestedCount: ids.length,
+      returnedCount,
+    },
+  );
+  await runtime.auditSink.recordCriticalEvent({ ...event, outcome });
+}
+
+function disclosureMetadata(
+  policyKey: string,
+  policyVersion: string,
+  count: number,
+) {
+  return { policyKey, policyVersion, fieldKeys: plaintextFields, count };
+}
+
+function requiredUserId(id: string | undefined): string {
+  if (!id) throw new Error("缺少用户 ID");
+  return id;
+}
+
+function userNotFound(id: string) {
+  return Response.json(
+    { error: "NOT_FOUND", resource: "users", id },
+    { status: 404 },
+  );
+}
+
+function invalidBatch(message: string) {
+  return Response.json(
+    { error: "INVALID_PLAINTEXT_BATCH", message },
+    { status: 400 },
+  );
+}

package/template/apps/server/src/data-governance/user-projection.ts

@@ -0,0 +1,54 @@
+import { systemModuleManifest } from "@windy/modules";
+import {
+  type DataGovernancePolicyDefinition,
+  type GovernedFieldPolicy,
+} from "@windy/shared";
+import type { ManagedUser } from "../system/entities.js";
+import {
+  plaintextResult,
+  type PlaintextAccessGrant,
+} from "./plaintext-access.js";
+
+export function systemUserDataPolicy(): DataGovernancePolicyDefinition {
+  const policy = systemModuleManifest(
+    "system.data-governance",
+  ).dataPolicies?.find(({ key }) => key === "system.user.fields");
+  if (!policy) throw new Error("缺少 system.user.fields 数据治理策略");
+  return policy;
+}
+
+export function projectPlaintextUser(
+  user: ManagedUser,
+  grant: PlaintextAccessGrant,
+  policy = systemUserDataPolicy(),
+): Record<string, unknown> {
+  return projectUser(user, policy, (value, field) =>
+    plaintextResult({ value: value ?? null, field, policy, grant }),
+  );
+}
+
+function projectUser(
+  user: ManagedUser,
+  policy: DataGovernancePolicyDefinition,
+  project: (value: string | undefined, field: GovernedFieldPolicy) => unknown,
+): Record<string, unknown> {
+  const governed = new Map(
+    policy.fields.map((field) => [field.fieldKey, field]),
+  );
+  const email = requiredField(governed, "email");
+  const phone = requiredField(governed, "phone");
+  return {
+    ...user,
+    email: project(user.email, email),
+    phone: project(user.phone, phone),
+  };
+}
+
+function requiredField(
+  fields: ReadonlyMap<string, GovernedFieldPolicy>,
+  key: string,
+): GovernedFieldPolicy {
+  const field = fields.get(key);
+  if (!field) throw new Error(`数据治理策略缺少字段：${key}`);
+  return field;
+}

package/template/apps/server/src/data-governance/user-sensitive-read-service.ts

@@ -0,0 +1,54 @@
+import type { RequestActor } from "../guards.js";
+import type { ManagedUser } from "../system/entities.js";
+import type { ResourceRouteConfig } from "../system/route-types.js";
+import { issuePlaintextAccessGrant } from "./plaintext-access.js";
+import {
+  projectPlaintextUser,
+  systemUserDataPolicy,
+} from "./user-projection.js";
+
+const plaintextFields = ["email", "phone"] as const;
+
+export class UserSensitiveReadService {
+  constructor(private readonly config: ResourceRouteConfig<ManagedUser>) {}
+
+  async read(
+    id: string,
+    actor: RequestActor,
+    requestId: string,
+  ): Promise<Record<string, unknown> | undefined> {
+    const user = await this.get(id, actor);
+    if (!user) return undefined;
+    return projectPlaintextUser(user, this.grant(actor, requestId));
+  }
+
+  async batch(
+    ids: readonly string[],
+    actor: RequestActor,
+    requestId: string,
+  ): Promise<Array<Record<string, unknown>> | undefined> {
+    if (this.config.dataAccess.mode !== "request") return undefined;
+    const users = await this.config.dataAccess.access.getManySnapshot(
+      ids,
+      actor,
+    );
+    if (!users) return undefined;
+    const grant = this.grant(actor, requestId);
+    return users.map((user) => projectPlaintextUser(user, grant));
+  }
+
+  private get(id: string, actor: RequestActor) {
+    return this.config.dataAccess.mode === "request"
+      ? this.config.dataAccess.access.get(id, actor)
+      : this.config.repository.get(id);
+  }
+
+  private grant(actor: RequestActor, requestId: string) {
+    return issuePlaintextAccessGrant({
+      actor,
+      requestId,
+      policy: systemUserDataPolicy(),
+      fieldKeys: plaintextFields,
+    });
+  }
+}

package/template/apps/server/src/example-modules.ts

@@ -0,0 +1,62 @@
+import type { FeatureFlagDefinition } from "@windy/shared";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { createServerRuntime } from "./runtime.js";
+import type { ScheduledTaskDefinition } from "./scheduler/types.js";
+import type { SearchProvider } from "./search/contracts.js";
+import type { ManagedDepartment } from "./system/entities.js";
+import type { EntityRepository } from "./system/repository.js";
+import type { RouteApp } from "./system/route-types.js";
+import { createWorkOrderRepository } from "./work-order/repository.js";
+import { createDrizzleWorkOrderRepository } from "./work-order/drizzle-repository.js";
+import { registerWorkOrderRoutes } from "./work-order/routes.js";
+import { WorkOrderService } from "./work-order/service.js";
+import { WorkOrderSearchProvider } from "./work-order/search-provider.js";
+import { createWorkOrderTaskDefinitions } from "./work-order/task.js";
+
+export interface ExampleModuleRuntimeDependencies {
+  features: FeatureFlagDefinition[];
+  departments: EntityRepository<ManagedDepartment>;
+  db?: NodePgDatabase;
+}
+
+export interface ExampleModuleRuntime {
+  service: WorkOrderService;
+  tasks: ScheduledTaskDefinition[];
+  providers: SearchProvider[];
+}
+
+export function createExampleModuleRuntime(
+  dependencies: ExampleModuleRuntimeDependencies,
+): ExampleModuleRuntime | undefined {
+  if (!dependencies.features.some(({ key }) => key === "work-order.ticket")) {
+    return undefined;
+  }
+  const service = new WorkOrderService(
+    dependencies.db
+      ? createDrizzleWorkOrderRepository(dependencies.db)
+      : createWorkOrderRepository(),
+    dependencies.departments,
+  );
+  return {
+    service,
+    tasks: createWorkOrderTaskDefinitions(dependencies.features, service),
+    providers: [new WorkOrderSearchProvider(service)],
+  };
+}
+
+export interface ExampleModuleRouteDependencies {
+  app: RouteApp;
+  runtime: ReturnType<typeof createServerRuntime>;
+  moduleRuntime?: ExampleModuleRuntime;
+}
+
+export function registerExampleModuleRoutes(
+  dependencies: ExampleModuleRouteDependencies,
+): void {
+  if (!dependencies.moduleRuntime) return;
+  registerWorkOrderRoutes(
+    dependencies.app,
+    dependencies.moduleRuntime.service,
+    dependencies.runtime,
+  );
+}

package/template/apps/server/src/example-permissions.ts

@@ -0,0 +1,5 @@
+export const exampleDevelopmentPermissionKeys = [
+  "work-order.ticket.read",
+  "work-order.ticket.create",
+  "work-order.ticket.manage",
+];