create-windy 0.1.0

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

@@ -0,0 +1,215 @@
+import type { FeatureFlagDefinition, LifecycleStatus } from "@windy/shared";
+import type { RequestGuardContext } from "../../guards.js";
+import { DurableArtifactError } from "../../jobs/artifact-service.js";
+import { evaluateRouteGuards, findSystemFeature } 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 {
+  GovernedExportServiceError,
+  type GovernedExportService,
+} from "./service.js";
+import type { GovernedExportRequest } from "./types.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function registerGovernedUserExportRoutes(
+  app: RouteApp,
+  service: GovernedExportService,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+) {
+  const feature = findSystemFeature(features, "user");
+
+  app.post("/system/users/exports", async (rawContext) => {
+    const { guardContext, body } = routeContext(rawContext);
+    return guarded(runtime, guardContext, feature, "POST", async () => {
+      try {
+        return Response.json(
+          project(await service.request(parseCreate(body), guardContext)),
+          { status: 202 },
+        );
+      } catch (error) {
+        return knownError(error);
+      }
+    });
+  });
+
+  app.get("/system/users/exports/:id", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return guarded(runtime, guardContext, feature, "GET", async () => {
+      try {
+        return project(await service.status(required(params.id), guardContext));
+      } catch (error) {
+        return knownError(error);
+      }
+    });
+  });
+
+  app.post("/system/users/exports/:id/cancel", async (rawContext) => {
+    const { guardContext, params, body } = routeContext(rawContext);
+    return guarded(runtime, guardContext, feature, "POST", async () => {
+      try {
+        return project(
+          await service.cancel(
+            required(params.id),
+            guardContext,
+            parseCancelReason(body),
+          ),
+        );
+      } catch (error) {
+        return knownError(error);
+      }
+    });
+  });
+
+  app.get("/system/users/exports/:id/download", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return guarded(runtime, guardContext, feature, "GET", async () => {
+      try {
+        const opened = await service.download(
+          required(params.id),
+          guardContext,
+        );
+        return new Response(opened.body, {
+          headers: {
+            "cache-control": "no-store",
+            "content-type": opened.artifact.contentType,
+            "content-disposition":
+              'attachment; filename="governed-users.ndjson"',
+            "x-content-sha256": opened.artifact.sha256,
+          },
+        });
+      } catch (error) {
+        return knownError(error);
+      }
+    });
+  });
+}
+
+async function guarded<T>(
+  runtime: ServerRuntime,
+  context: RequestGuardContext,
+  feature: FeatureFlagDefinition | undefined,
+  method: "GET" | "POST",
+  handler: () => Promise<T>,
+) {
+  const decision = await evaluateRouteGuards(runtime, context, {
+    permission: {
+      method,
+      path: "/api/system/users/exports/:id",
+      permissionKey: "system.user.export",
+    },
+    feature,
+    restrictedModeAccess: "backup-export",
+  });
+  return decision.allowed
+    ? handler()
+    : Response.json(
+        { error: "FORBIDDEN", reason: decision.reason },
+        { status: 403 },
+      );
+}
+
+function parseCreate(body: unknown) {
+  const value = strictObject(body, ["idempotencyKey", "reason", "query"]);
+  const query = strictObject(value.query || {}, [
+    "q",
+    "status",
+    "includeDeleted",
+    "sort",
+  ]);
+  const status = query.status;
+  if (
+    status !== undefined &&
+    !["draft", "active", "disabled", "archived"].includes(String(status))
+  ) {
+    throw new GovernedExportServiceError("EXPORT_QUERY_INVALID", 400);
+  }
+  return {
+    idempotencyKey: requiredString(value.idempotencyKey),
+    reason: requiredString(value.reason),
+    query: {
+      q: optionalString(query.q),
+      status: status as LifecycleStatus | undefined,
+      includeDeleted: query.includeDeleted === true,
+      sort: parseSort(query.sort),
+    },
+  };
+}
+
+function parseSort(value: unknown) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > 5) {
+    throw new GovernedExportServiceError("EXPORT_QUERY_INVALID", 400);
+  }
+  return value.map((item) => {
+    const sort = strictObject(item, ["field", "order"]);
+    const field = requiredString(sort.field);
+    if (
+      !["id", "username", "displayName", "createdAt"].includes(field) ||
+      !["asc", "desc"].includes(String(sort.order))
+    ) {
+      throw new GovernedExportServiceError("EXPORT_QUERY_INVALID", 400);
+    }
+    return { field, order: sort.order as "asc" | "desc" };
+  });
+}
+
+function parseCancelReason(body: unknown) {
+  const value = strictObject(body || {}, ["reason"]);
+  return optionalString(value.reason) || "用户取消治理导出申请";
+}
+
+function strictObject(value: unknown, keys: 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;
+}
+
+function required(value: string | undefined) {
+  if (!value) throw new GovernedExportServiceError("EXPORT_NOT_FOUND", 404);
+  return value;
+}
+
+function requiredString(value: unknown) {
+  if (typeof value !== "string") {
+    throw new GovernedExportServiceError("EXPORT_INPUT_INVALID", 400);
+  }
+  return value;
+}
+
+function optionalString(value: unknown) {
+  if (value === undefined) return undefined;
+  return requiredString(value);
+}
+
+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,
+  };
+}
+
+function knownError(error: unknown): Response {
+  if (error instanceof GovernedExportServiceError) {
+    return Response.json({ error: error.code }, { status: error.status });
+  }
+  if (error instanceof DurableArtifactError) {
+    const status = error.code === "ARTIFACT_EXPIRED" ? 410 : 409;
+    return Response.json({ error: error.code }, { status });
+  }
+  throw error;
+}

package/template/apps/server/src/data-governance/export/scope-snapshot.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildScopeContext,
+  isServerScopeContext,
+  restoreServerScopeContext,
+} from "../../data-access/context.js";
+import {
+  captureGovernedExportScope,
+  hashGovernedExportScope,
+} from "./scope-snapshot.js";
+
+describe("governed export scope snapshot", () => {
+  test("只从 nominal ScopeContext 生成稳定投影并可由 Worker 恢复", () => {
+    const context = buildScopeContext("user-1", "dept-1", [
+      {
+        id: "role-1",
+        code: "auditor",
+        dataScope: "department-and-children",
+        departmentIds: [],
+      },
+    ]);
+    const first = captureGovernedExportScope(context);
+    const second = captureGovernedExportScope(context);
+    const restored = restoreServerScopeContext(first.snapshot);
+
+    expect(first).toEqual(second);
+    expect(first.hash).toHaveLength(64);
+    expect(hashGovernedExportScope(first.snapshot)).toBe(first.hash);
+    expect(isServerScopeContext(restored)).toBe(true);
+    expect(Object.isFrozen(restored)).toBe(true);
+    expect(JSON.stringify(first.snapshot)).not.toContain("permissionKeys");
+    expect(JSON.stringify(first.snapshot)).not.toContain("plaintext");
+  });
+
+  test("拒绝客户端构造的同形对象", () => {
+    expect(() =>
+      captureGovernedExportScope({
+        tenantId: "single-tenant",
+        actorId: "forged",
+        grants: [{ scope: "all" }],
+        roleIds: [],
+      }),
+    ).toThrow("服务端 ScopeContext");
+  });
+});

package/template/apps/server/src/data-governance/export/scope-snapshot.ts

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+import type { GovernedExportScopeSnapshot } from "@windy/database";
+import { snapshotServerScopeContext } from "../../data-access/context.js";
+
+export function captureGovernedExportScope(value: unknown) {
+  const snapshot = snapshotServerScopeContext(value);
+  return { snapshot, hash: hashGovernedExportScope(snapshot) };
+}
+
+export function hashGovernedExportScope(
+  snapshot: GovernedExportScopeSnapshot,
+): string {
+  return createHash("sha256").update(stableJson(snapshot)).digest("hex");
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/template/apps/server/src/data-governance/export/service.ts

@@ -0,0 +1,337 @@
+import type { GovernedExportQuerySnapshot } from "@windy/database";
+import type { AuditEvent } from "@windy/shared";
+import type { RequestGuardContext } from "../../guards.js";
+import {
+  DurableArtifactError,
+  type DurableArtifactService,
+  type OpenedDurableArtifact,
+} from "../../jobs/artifact-service.js";
+import type { DurableJobService } from "../../jobs/service.js";
+import type { createServerRuntime } from "../../runtime.js";
+import type { GovernedExportApprovalPort } from "./approval-port.js";
+import type { GovernedExportJobRuntime } from "./job-runtime.js";
+import type { GovernedExportRepository } from "./repository.js";
+import { captureGovernedExportScope } from "./scope-snapshot.js";
+import type { GovernedExportRequest, GovernedExportStatus } from "./types.js";
+import { fingerprintGovernedExportRequest } from "./request-fingerprint.js";
+
+export interface CreateGovernedExportInput {
+  idempotencyKey: string;
+  reason: string;
+  query: GovernedExportQuerySnapshot;
+}
+
+export interface GovernedExportPolicy {
+  approvalRequired: boolean;
+  retentionSeconds: number;
+}
+
+type AuditSink = ReturnType<typeof createServerRuntime>["auditSink"];
+
+export class GovernedExportService {
+  constructor(
+    private readonly requests: GovernedExportRepository,
+    private readonly jobRuntime: GovernedExportJobRuntime,
+    private readonly durableJobs: DurableJobService,
+    private readonly artifacts: DurableArtifactService,
+    private readonly approvals: GovernedExportApprovalPort,
+    private readonly audit: AuditSink,
+    private readonly policy: GovernedExportPolicy,
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  async request(
+    input: CreateGovernedExportInput,
+    context: RequestGuardContext,
+  ) {
+    validateCreate(input);
+    const scope = captureGovernedExportScope(context.actor.scopeContext);
+    const id = Bun.randomUUIDv7();
+    const expiresAt = new Date(
+      this.now().getTime() + this.policy.retentionSeconds * 1_000,
+    ).toISOString();
+    const draft = {
+      id,
+      resourceType: "system.user",
+      policyKey: "system.user.fields",
+      policyVersion: "1",
+      fieldKeys: ["email", "phone"],
+      requesterId: context.actor.id,
+      requesterName: context.actor.displayName || context.actor.name,
+      idempotencyKey: input.idempotencyKey,
+      reason: input.reason.trim(),
+      scopeSnapshot: scope.snapshot,
+      scopeHash: scope.hash,
+      querySnapshot: structuredClone(input.query),
+      approvalRequired: this.policy.approvalRequired,
+      expiresAt,
+    };
+    const created = await this.requests.create(
+      {
+        ...draft,
+        requestFingerprint: fingerprintGovernedExportRequest(draft),
+      },
+      this.now(),
+    );
+    if (created.fingerprintConflict) {
+      throw new GovernedExportServiceError("EXPORT_IDEMPOTENCY_CONFLICT", 409);
+    }
+    await this.audit.recordCriticalEvent(
+      event(context, "data.governed-export.request", created.request.id, {
+        policyKey: created.request.policyKey,
+        policyVersion: created.request.policyVersion,
+        scopeHash: created.request.scopeHash,
+        requestFingerprint: created.request.requestFingerprint,
+        replayed: !created.created,
+      }),
+    );
+    return this.reconcile(created.request, context);
+  }
+
+  async status(id: string, context: RequestGuardContext) {
+    return this.reconcile(await this.owned(id, context), context);
+  }
+
+  async cancel(id: string, context: RequestGuardContext, reason: string) {
+    const request = await this.owned(id, context);
+    if (request.status === "cancelled") return request;
+    await this.audit.recordCriticalEvent(
+      event(context, "data.governed-export.cancel", request.id, {
+        scopeHash: request.scopeHash,
+        jobId: request.durableJobId,
+      }),
+    );
+    await this.approvals.cancel(
+      request,
+      context.actor,
+      reason.trim() || "用户取消治理导出申请",
+    );
+    if (request.durableJobId) {
+      await this.jobRuntime.cancel(request.durableJobId);
+      await this.deleteArtifact(request);
+    }
+    return (
+      (await this.requests.update(request.id, {
+        status: "cancelled",
+        updatedAt: this.now().toISOString(),
+      })) || request
+    );
+  }
+
+  async download(
+    id: string,
+    context: RequestGuardContext,
+  ): Promise<OpenedDurableArtifact> {
+    const request = await this.reconcile(
+      await this.owned(id, context),
+      context,
+    );
+    if (request.status !== "succeeded" || !request.durableJobId) {
+      throw new GovernedExportServiceError("EXPORT_NOT_READY", 409);
+    }
+    await this.requireApproved(request);
+    this.requireUnexpired(request);
+    const artifact = await this.artifacts.inspect(
+      request.durableJobId,
+      "governed-export",
+      context.actor.id,
+    );
+    assertArtifactMetadata(artifact, request);
+    await this.audit.recordCriticalEvent(
+      downloadEvent(context, request, artifact.sha256, "intent"),
+    );
+    const opened = await this.artifacts.openInspected(artifact);
+    try {
+      await this.audit.recordCriticalEvent(
+        downloadEvent(context, request, artifact.sha256, "authorized"),
+      );
+    } catch (error) {
+      await opened.body.cancel().catch(() => undefined);
+      throw error;
+    }
+    return opened;
+  }
+
+  private async owned(id: string, context: RequestGuardContext) {
+    const request = await this.requests.get(id);
+    if (!request) throw new GovernedExportServiceError("EXPORT_NOT_FOUND", 404);
+    if (request.requesterId !== context.actor.id) {
+      throw new GovernedExportServiceError("EXPORT_FORBIDDEN", 403);
+    }
+    const current = captureGovernedExportScope(context.actor.scopeContext);
+    if (current.hash !== request.scopeHash) {
+      throw new GovernedExportServiceError("EXPORT_SCOPE_CHANGED", 403);
+    }
+    return request;
+  }
+
+  private async reconcile(
+    request: GovernedExportRequest,
+    context: RequestGuardContext,
+  ) {
+    if (request.expiresAt <= this.now().toISOString()) {
+      if (!["cancelled", "failed", "rejected"].includes(request.status)) {
+        return this.cancel(request.id, context, "治理导出申请已过期");
+      }
+      return request;
+    }
+    request = await this.ensureApproval(request, context);
+    const approvalStatus = await this.approvals.status(request);
+    if (approvalStatus === "rejected")
+      return this.setStatus(request, "rejected");
+    if (["cancelled", "timed-out"].includes(approvalStatus || "")) {
+      return this.setStatus(request, "cancelled");
+    }
+    if (request.approvalRequired && approvalStatus !== "approved")
+      return request;
+    if (!request.durableJobId) {
+      await this.jobRuntime.submit(request);
+      request = (await this.requests.get(request.id)) || request;
+    }
+    const job = request.durableJobId
+      ? await this.durableJobs.get(request.durableJobId)
+      : undefined;
+    const status = job && durableStatus(job.job.status);
+    return status && status !== request.status
+      ? this.setStatus(request, status)
+      : request;
+  }
+
+  private async ensureApproval(
+    request: GovernedExportRequest,
+    context: RequestGuardContext,
+  ) {
+    if (!request.approvalRequired || request.approvalId) return request;
+    try {
+      const approval = await this.approvals.create(request, context.actor);
+      const linked = await this.requests.update(request.id, {
+        approvalId: approval.id,
+        updatedAt: this.now().toISOString(),
+      });
+      if (linked) return linked;
+    } catch {
+      // 同一 request id 的审批创建可幂等重放，下一次请求会继续补偿链接。
+    }
+    throw new GovernedExportServiceError("EXPORT_APPROVAL_LINK_FAILED", 503);
+  }
+
+  private async requireApproved(request: GovernedExportRequest) {
+    if (!(await this.approvals.isApproved(request))) {
+      throw new GovernedExportServiceError("EXPORT_APPROVAL_REQUIRED", 409);
+    }
+  }
+
+  private requireUnexpired(request: GovernedExportRequest) {
+    if (request.expiresAt <= this.now().toISOString()) {
+      throw new GovernedExportServiceError("EXPORT_EXPIRED", 410);
+    }
+  }
+
+  private async setStatus(
+    request: GovernedExportRequest,
+    status: GovernedExportStatus,
+  ) {
+    return (
+      (await this.requests.update(request.id, {
+        status,
+        updatedAt: this.now().toISOString(),
+      })) || request
+    );
+  }
+
+  private async deleteArtifact(request: GovernedExportRequest) {
+    try {
+      const artifact = await this.artifacts.inspect(
+        request.durableJobId!,
+        "governed-export",
+        request.requesterId,
+      );
+      await this.artifacts.deleteInspected(artifact);
+    } catch (error) {
+      if (
+        !(error instanceof DurableArtifactError) ||
+        error.code !== "ARTIFACT_NOT_FOUND"
+      ) {
+        throw error;
+      }
+    }
+  }
+}
+
+export class GovernedExportServiceError extends Error {
+  constructor(
+    readonly code: string,
+    readonly status: number,
+  ) {
+    super(code);
+    this.name = "GovernedExportServiceError";
+  }
+}
+
+function validateCreate(input: CreateGovernedExportInput) {
+  if (!input.idempotencyKey.trim() || input.idempotencyKey.length > 120) {
+    throw new GovernedExportServiceError("EXPORT_IDEMPOTENCY_KEY_INVALID", 400);
+  }
+  if (input.reason.trim().length < 5 || input.reason.length > 200) {
+    throw new GovernedExportServiceError("EXPORT_REASON_INVALID", 400);
+  }
+}
+
+function durableStatus(status: string): GovernedExportStatus | undefined {
+  return ["queued", "running", "succeeded", "failed", "cancelled"].includes(
+    status,
+  )
+    ? (status as GovernedExportStatus)
+    : undefined;
+}
+
+function assertArtifactMetadata(
+  artifact: Awaited<ReturnType<DurableArtifactService["inspect"]>>,
+  request: GovernedExportRequest,
+) {
+  if (
+    artifact.jobId !== request.durableJobId ||
+    artifact.ownerId !== request.requesterId ||
+    artifact.contentType !== "application/x-ndjson" ||
+    artifact.byteSize < 0 ||
+    !/^[a-f0-9]{64}$/.test(artifact.sha256)
+  ) {
+    throw new GovernedExportServiceError("EXPORT_ARTIFACT_INVALID", 409);
+  }
+}
+
+function event(
+  context: RequestGuardContext,
+  action: AuditEvent["action"],
+  id: string,
+  metadata: Record<string, unknown>,
+): AuditEvent {
+  return {
+    id: Bun.randomUUIDv7(),
+    action,
+    outcome: "success",
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+      name: context.actor.name,
+    },
+    target: { type: "system.user.governed-export", id },
+    requestId: context.requestId,
+    metadata,
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+function downloadEvent(
+  context: RequestGuardContext,
+  request: GovernedExportRequest,
+  sha256: string,
+  phase: "intent" | "authorized",
+) {
+  return event(context, "data.governed-export.download", request.id, {
+    phase,
+    scopeHash: request.scopeHash,
+    jobId: request.durableJobId,
+    sha256,
+  });
+}

package/template/apps/server/src/data-governance/export/source.ts

@@ -0,0 +1,69 @@
+import type { GovernedExportQuerySnapshot } from "@windy/database";
+import { restoreServerScopeContext } from "../../data-access/context.js";
+import type { RequestActor } from "../../guards.js";
+import type { ManagedUser } from "../../system/entities.js";
+import type { ResourceRouteConfig } from "../../system/route-types.js";
+import type { GovernedExportRequest } from "./types.js";
+
+export interface GovernedExportSource {
+  readonly resourceType: string;
+  pages(
+    request: GovernedExportRequest,
+  ): AsyncIterable<readonly Record<string, unknown>[]>;
+}
+
+export class GovernedUserExportSource implements GovernedExportSource {
+  readonly resourceType = "system.user";
+
+  constructor(private readonly config: ResourceRouteConfig<ManagedUser>) {}
+
+  async *pages(request: GovernedExportRequest) {
+    const actor = exportActor(request);
+    let page = 1;
+    while (true) {
+      const result = await this.list(request.querySnapshot, page, actor);
+      yield result.items.map((user) => projectUser(user, request.fieldKeys));
+      if (page * result.pageSize >= result.total) return;
+      page += 1;
+    }
+  }
+
+  private list(
+    query: GovernedExportQuerySnapshot,
+    page: number,
+    actor: RequestActor,
+  ) {
+    const input = { ...query, page, pageSize: 100 };
+    return this.config.dataAccess.mode === "request"
+      ? this.config.dataAccess.access.list(
+          input,
+          this.config.searchFields,
+          actor,
+        )
+      : this.config.repository.list(input, this.config.searchFields);
+  }
+}
+
+function exportActor(request: GovernedExportRequest): RequestActor {
+  return {
+    id: request.requesterId,
+    type: "service",
+    name: request.requesterName,
+    roleCodes: [],
+    permissionKeys: [],
+    scopeContext: restoreServerScopeContext(request.scopeSnapshot),
+  };
+}
+
+function projectUser(user: ManagedUser, fieldKeys: string[]) {
+  const output: Record<string, unknown> = {
+    id: user.id,
+    username: user.username,
+    displayName: user.displayName,
+    departmentId: user.departmentId,
+    status: user.status,
+  };
+  if (fieldKeys.includes("email")) output.email = user.email || null;
+  if (fieldKeys.includes("phone")) output.phone = user.phone || null;
+  return output;
+}