create-windy 0.1.0

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

@@ -0,0 +1,83 @@
+import type {
+  CreateGovernedExportRequest,
+  GovernedExportRequest,
+  GovernedExportStatus,
+} from "./types.js";
+
+export interface GovernedExportRepository {
+  create(
+    input: CreateGovernedExportRequest,
+    now: Date,
+  ): Promise<{
+    request: GovernedExportRequest;
+    created: boolean;
+    fingerprintConflict: boolean;
+  }>;
+  get(id: string): Promise<GovernedExportRequest | undefined>;
+  update(
+    id: string,
+    patch: Partial<
+      Pick<
+        GovernedExportRequest,
+        "status" | "approvalId" | "durableJobId" | "updatedAt"
+      >
+    >,
+  ): Promise<GovernedExportRequest | undefined>;
+}
+
+export class InMemoryGovernedExportRepository implements GovernedExportRepository {
+  private readonly requests = new Map<string, GovernedExportRequest>();
+
+  async create(input: CreateGovernedExportRequest, now: Date) {
+    const existing = [...this.requests.values()].find(
+      (request) =>
+        request.requesterId === input.requesterId &&
+        request.resourceType === input.resourceType &&
+        request.idempotencyKey === input.idempotencyKey,
+    );
+    if (existing) {
+      return {
+        request: clone(existing),
+        created: false,
+        fingerprintConflict:
+          existing.requestFingerprint !== input.requestFingerprint,
+      };
+    }
+    const timestamp = now.toISOString();
+    const request: GovernedExportRequest = {
+      ...structuredClone(input),
+      status: input.approvalRequired ? "pending-approval" : "queued",
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+    this.requests.set(request.id, request);
+    return {
+      request: clone(request),
+      created: true,
+      fingerprintConflict: false,
+    };
+  }
+
+  async get(id: string) {
+    const request = this.requests.get(id);
+    return request ? clone(request) : undefined;
+  }
+
+  async update(
+    id: string,
+    patch: Partial<{
+      status: GovernedExportStatus;
+      approvalId: string;
+      durableJobId: string;
+      updatedAt: string;
+    }>,
+  ) {
+    const current = this.requests.get(id);
+    if (!current) return undefined;
+    const updated = { ...current, ...structuredClone(patch) };
+    this.requests.set(id, updated);
+    return clone(updated);
+  }
+}
+
+const clone = <T>(value: T): T => structuredClone(value);

package/template/apps/server/src/data-governance/export/request-fingerprint.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { fingerprintGovernedExportRequest } from "./request-fingerprint.js";
+
+const request = {
+  resourceType: "system.user",
+  policyKey: "system.user.fields",
+  policyVersion: "1",
+  fieldKeys: ["email", "phone"],
+  requesterId: "user-1",
+  reason: "合规复核用户字段",
+  scopeHash: "a".repeat(64),
+  querySnapshot: { includeDeleted: false, q: "审计" },
+  approvalRequired: true,
+};
+
+describe("governed export request fingerprint", () => {
+  test("对象键顺序不影响摘要，但用途或查询变化会冲突", () => {
+    const first = fingerprintGovernedExportRequest(request);
+    const reordered = fingerprintGovernedExportRequest({
+      ...request,
+      querySnapshot: { q: "审计", includeDeleted: false },
+    });
+
+    expect(first).toMatch(/^[a-f0-9]{64}$/);
+    expect(reordered).toBe(first);
+    expect(
+      fingerprintGovernedExportRequest({
+        ...request,
+        reason: "另一项合规复核用途",
+      }),
+    ).not.toBe(first);
+  });
+
+  test("数据库标识和到期时间不参与同一业务请求的摘要", () => {
+    const first = {
+      ...request,
+      id: "request-a",
+      idempotencyKey: "export-a",
+      expiresAt: "2026-01-01T00:00:00.000Z",
+    };
+    const second = {
+      ...request,
+      id: "request-b",
+      idempotencyKey: "export-a",
+      expiresAt: "2027-01-01T00:00:00.000Z",
+    };
+    expect(fingerprintGovernedExportRequest(first)).toBe(
+      fingerprintGovernedExportRequest(second),
+    );
+  });
+});

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

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import type { CreateGovernedExportRequest } from "./types.js";
+
+type FingerprintedRequest = Pick<
+  CreateGovernedExportRequest,
+  | "resourceType"
+  | "policyKey"
+  | "policyVersion"
+  | "fieldKeys"
+  | "requesterId"
+  | "reason"
+  | "scopeHash"
+  | "querySnapshot"
+  | "approvalRequired"
+>;
+
+export function fingerprintGovernedExportRequest(
+  request: FingerprintedRequest,
+): string {
+  const payload: FingerprintedRequest = {
+    resourceType: request.resourceType,
+    policyKey: request.policyKey,
+    policyVersion: request.policyVersion,
+    fieldKeys: request.fieldKeys,
+    requesterId: request.requesterId,
+    reason: request.reason,
+    scopeHash: request.scopeHash,
+    querySnapshot: request.querySnapshot,
+    approvalRequired: request.approvalRequired,
+  };
+  return createHash("sha256").update(stableJson(payload)).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/routes-integrity.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import {
+  cancel,
+  canary,
+  createFixture,
+  getStatus,
+  postRequest,
+  requestContext,
+  tamperedBlobStore,
+} from "./routes-test-fixture.js";
+
+describe("用户治理导出 API 完整性与审计", () => {
+  test("取消幂等清理 Blob，授权审计失败时关闭已校验的下载流", async () => {
+    let failDownloadAudit = false;
+    const fixture = await createFixture({
+      async write(event) {
+        if (
+          failDownloadAudit &&
+          event.action === "data.governed-export.download" &&
+          event.metadata?.phase === "authorized"
+        ) {
+          throw new Error(`audit unavailable ${canary}`);
+        }
+      },
+    });
+    const first = (await (
+      await postRequest(fixture, "export-cancel")
+    ).json()) as { id: string };
+    expect(await cancel(fixture, first.id)).toMatchObject({
+      status: "cancelled",
+    });
+    expect(await cancel(fixture, first.id)).toMatchObject({
+      status: "cancelled",
+    });
+    expect(fixture.approval.cancelled).toBe(1);
+
+    const second = (await (
+      await postRequest(fixture, "export-audit")
+    ).json()) as { id: string };
+    fixture.approval.current = "approved";
+    await getStatus(fixture, second.id);
+    await fixture.jobRuntime.runNext("audit-download-worker");
+    await getStatus(fixture, second.id);
+    failDownloadAudit = true;
+    await expect(
+      fixture.app.invoke(
+        "GET",
+        "/system/users/exports/:id/download",
+        requestContext(fixture, undefined, { id: second.id }),
+      ),
+    ).rejects.toThrow("audit unavailable");
+    expect(fixture.openCount()).toBe(1);
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .filter(({ action }) => action === "data.governed-export.download")
+        .map(({ metadata }) => metadata?.phase),
+    ).toEqual(["intent", "authorized"]);
+  });
+
+  test("Blob 被篡改时在关键下载审计与打开流之前拒绝", async () => {
+    const blobFixture = tamperedBlobStore();
+    const fixture = await createFixture(undefined, blobFixture);
+    const created = (await (
+      await postRequest(fixture, "export-tampered")
+    ).json()) as { id: string };
+    fixture.approval.current = "approved";
+    await getStatus(fixture, created.id);
+    await fixture.jobRuntime.runNext("tamper-worker");
+    await getStatus(fixture, created.id);
+    blobFixture.tamper();
+
+    const response = (await fixture.app.invoke(
+      "GET",
+      "/system/users/exports/:id/download",
+      requestContext(fixture, undefined, { id: created.id }),
+    )) as Response;
+
+    expect(response.status).toBe(409);
+    expect(blobFixture.openCount()).toBe(0);
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .filter(({ action }) => action === "data.governed-export.download"),
+    ).toHaveLength(0);
+    expect(JSON.stringify(fixture.runtime.auditSink.list())).not.toContain(
+      canary,
+    );
+  });
+});

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

@@ -0,0 +1,239 @@
+import type { WorkItemStatus } from "@windy/shared";
+import {
+  MemoryBlobStore,
+  type BlobStore,
+  type PutBlobInput,
+} from "@windy/storage";
+import { createFoundationSnapshot } from "../../foundation.js";
+import type { RequestActor } from "../../guards.js";
+import { DurableArtifactService } from "../../jobs/artifact-service.js";
+import { DurableHandlerRegistry } from "../../jobs/handler-registry.js";
+import { InMemoryDurableExecutionRepository } from "../../jobs/in-memory-execution.js";
+import { DurableJobService } from "../../jobs/service.js";
+import { DurableJobWorker } from "../../jobs/worker.js";
+import { createServerRuntime, type AuditEventWriter } from "../../runtime.js";
+import { FakeRouteApp } from "../../system/route-test-app.js";
+import type { GovernedExportApprovalPort } from "./approval-port.js";
+import { GovernedExportJobRuntime } from "./job-runtime.js";
+import { InMemoryGovernedExportRepository } from "./repository.js";
+import { registerGovernedUserExportRoutes } from "./routes.js";
+import { GovernedExportService } from "./service.js";
+import type { GovernedExportSource } from "./source.js";
+import type { GovernedExportRequest } from "./types.js";
+
+export const canary = "sensitive-canary-13800138000";
+
+export async function createFixture(
+  auditWriter?: AuditEventWriter,
+  blobFixture = countingBlobStore(),
+) {
+  const policies: string[] = [];
+  const writer: AuditEventWriter = {
+    async write(event, policy) {
+      policies.push(policy || "ordinary");
+      await auditWriter?.write(event, policy);
+    },
+  };
+  const runtime = createServerRuntime(
+    { WINDY_DEV_ADMIN_TOKEN: "token" },
+    { auditWriter: writer },
+  );
+  const baseGuardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/system/users/exports", {
+      headers: { authorization: "Bearer token" },
+    }),
+  );
+  const guardContext = {
+    ...baseGuardContext,
+    actor: {
+      ...baseGuardContext.actor,
+      permissionKeys: [
+        ...baseGuardContext.actor.permissionKeys,
+        "system.user.export",
+      ],
+    },
+  };
+  const requests = new RecoverableGovernedExportRepository();
+  const durable = new InMemoryDurableExecutionRepository();
+  const durableJobs = new DurableJobService(durable);
+  const registry = new DurableHandlerRegistry();
+  const worker = new DurableJobWorker(durable, registry);
+  const approval = new FakeApproval();
+  const { blobStore, openCount } = blobFixture;
+  const source: GovernedExportSource = {
+    resourceType: "system.user",
+    async *pages() {
+      yield [{ id: "user-1", phone: canary }];
+    },
+  };
+  const jobRuntime = new GovernedExportJobRuntime(
+    requests,
+    durableJobs,
+    worker,
+    registry,
+    blobStore,
+    runtime.auditSink,
+    [source],
+    () => approval.isApproved(),
+  );
+  const service = new GovernedExportService(
+    requests,
+    jobRuntime,
+    durableJobs,
+    new DurableArtifactService(durable, blobStore),
+    approval,
+    runtime.auditSink,
+    { approvalRequired: true, retentionSeconds: 3600 },
+  );
+  const app = new FakeRouteApp();
+  registerGovernedUserExportRoutes(
+    app,
+    service,
+    runtime,
+    createFoundationSnapshot().features,
+  );
+  return {
+    app,
+    approval,
+    guardContext,
+    jobRuntime,
+    openCount,
+    policies,
+    requests,
+    runtime,
+  };
+}
+
+class FakeApproval implements GovernedExportApprovalPort {
+  current: WorkItemStatus = "pending";
+  cancelled = 0;
+  created = 0;
+  failCreateOnce = false;
+
+  async create(request: GovernedExportRequest) {
+    this.created += 1;
+    if (this.failCreateOnce) {
+      this.failCreateOnce = false;
+      throw new Error("approval unavailable");
+    }
+    return { id: `approval-${request.id}`, status: this.current };
+  }
+
+  async status() {
+    return this.current;
+  }
+
+  async cancel(_request: GovernedExportRequest, _actor: RequestActor) {
+    this.current = "cancelled";
+    this.cancelled += 1;
+  }
+
+  async isApproved() {
+    return this.current === "approved";
+  }
+}
+
+class RecoverableGovernedExportRepository extends InMemoryGovernedExportRepository {
+  failApprovalLinkOnce = false;
+
+  override update(
+    id: string,
+    patch: Parameters<InMemoryGovernedExportRepository["update"]>[1],
+  ) {
+    if (patch.approvalId && this.failApprovalLinkOnce) {
+      this.failApprovalLinkOnce = false;
+      return Promise.resolve(undefined);
+    }
+    return super.update(id, patch);
+  }
+}
+
+function countingBlobStore() {
+  const delegate = new MemoryBlobStore();
+  let opened = 0;
+  const blobStore: BlobStore = {
+    put: (input: PutBlobInput) => delegate.put(input),
+    inspect: (ref) => delegate.inspect(ref),
+    open: (ref) => {
+      opened += 1;
+      return delegate.open(ref);
+    },
+    delete: (ref) => delegate.delete(ref),
+  };
+  return { blobStore, openCount: () => opened };
+}
+
+export function tamperedBlobStore() {
+  const delegate = new MemoryBlobStore();
+  let opened = 0;
+  let tampered = false;
+  const blobStore: BlobStore = {
+    put: (input) => delegate.put(input),
+    async inspect(ref) {
+      const stored = await delegate.inspect(ref);
+      return stored && tampered
+        ? {
+            ...stored,
+            contentHash: { algorithm: "sha256", value: "0".repeat(64) },
+          }
+        : stored;
+    },
+    open: (ref) => {
+      opened += 1;
+      return delegate.open(ref);
+    },
+    delete: (ref) => delegate.delete(ref),
+  };
+  return {
+    blobStore,
+    openCount: () => opened,
+    tamper: () => {
+      tampered = true;
+    },
+  };
+}
+
+export function requestContext(
+  fixture: Awaited<ReturnType<typeof createFixture>>,
+  body?: unknown,
+  params: Record<string, string> = {},
+) {
+  return { guardContext: fixture.guardContext, body, params, query: {} };
+}
+
+export function postRequest(
+  fixture: Awaited<ReturnType<typeof createFixture>>,
+  idempotencyKey: string,
+) {
+  return fixture.app.invoke(
+    "POST",
+    "/system/users/exports",
+    requestContext(fixture, {
+      idempotencyKey,
+      reason: "安全审计复核",
+      query: { includeDeleted: false },
+    }),
+  ) as Promise<Response>;
+}
+
+export function getStatus(
+  fixture: Awaited<ReturnType<typeof createFixture>>,
+  id: string,
+) {
+  return fixture.app.invoke(
+    "GET",
+    "/system/users/exports/:id",
+    requestContext(fixture, undefined, { id }),
+  ) as Promise<Record<string, unknown>>;
+}
+
+export function cancel(
+  fixture: Awaited<ReturnType<typeof createFixture>>,
+  id: string,
+) {
+  return fixture.app.invoke(
+    "POST",
+    "/system/users/exports/:id/cancel",
+    requestContext(fixture, {}, { id }),
+  ) as Promise<Record<string, unknown>>;
+}

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

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test";
+import {
+  canary,
+  createFixture,
+  getStatus,
+  postRequest,
+  requestContext,
+} from "./routes-test-fixture.js";
+
+describe("用户治理导出 API", () => {
+  test("申请、审批、生成、状态和重复下载均走专用 Guard 与关键审计", async () => {
+    const fixture = await createFixture();
+    const injected = (await fixture.app.invoke(
+      "POST",
+      "/system/users/exports",
+      requestContext(fixture, {
+        idempotencyKey: "export-injected",
+        reason: "安全审计复核",
+        scope: "all",
+      }),
+    )) as Response;
+    expect(injected.status).toBe(400);
+
+    const created = (await postRequest(fixture, "export-1")) as Response;
+    expect(created.status).toBe(202);
+    const pending = (await created.json()) as { id: string; status: string };
+    expect(pending.status).toBe("pending-approval");
+
+    const repeated = (await (
+      await postRequest(fixture, "export-1")
+    ).json()) as { id: string };
+    expect(repeated.id).toBe(pending.id);
+    const conflict = (await fixture.app.invoke(
+      "POST",
+      "/system/users/exports",
+      requestContext(fixture, {
+        idempotencyKey: "export-1",
+        reason: "另一项安全审计复核",
+        query: { includeDeleted: false },
+      }),
+    )) as Response;
+    expect(conflict.status).toBe(409);
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .filter(({ action }) => action === "data.governed-export.request")
+        .map(({ target }) => target?.id),
+    ).toEqual([pending.id, pending.id]);
+
+    fixture.approval.current = "approved";
+    const queued = await getStatus(fixture, pending.id);
+    expect(queued).toMatchObject({ status: "queued" });
+    expect(await fixture.jobRuntime.runNext("api-export-worker")).toMatchObject(
+      {
+        status: "succeeded",
+      },
+    );
+    expect(await getStatus(fixture, pending.id)).toMatchObject({
+      status: "succeeded",
+    });
+
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const response = (await fixture.app.invoke(
+        "GET",
+        "/system/users/exports/:id/download",
+        requestContext(fixture, undefined, { id: pending.id }),
+      )) as Response;
+      expect(response.status).toBe(200);
+      expect(await response.text()).toContain(canary);
+    }
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .filter(({ action }) => action === "data.governed-export.download"),
+    ).toHaveLength(4);
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .filter(({ action }) => action === "data.governed-export.download")
+        .map(({ metadata }) => metadata?.phase),
+    ).toEqual(["intent", "authorized", "intent", "authorized"]);
+    expect(JSON.stringify(fixture.runtime.auditSink.list())).not.toContain(
+      canary,
+    );
+    expect(fixture.policies.every((policy) => policy === "critical")).toBe(
+      true,
+    );
+  });
+
+  test("owner、当前 Scope 与审批状态任一不满足都不能取得下载", async () => {
+    const fixture = await createFixture();
+    const created = (await (
+      await postRequest(fixture, "export-owner")
+    ).json()) as {
+      id: string;
+    };
+    const otherContext = {
+      ...fixture.guardContext,
+      actor: {
+        ...fixture.guardContext.actor,
+        id: "other-user",
+      },
+    };
+    const denied = (await fixture.app.invoke(
+      "GET",
+      "/system/users/exports/:id",
+      { guardContext: otherContext, params: { id: created.id }, query: {} },
+    )) as Response;
+    expect(denied.status).toBe(403);
+
+    const noExportPermission = {
+      ...fixture.guardContext,
+      actor: {
+        ...fixture.guardContext.actor,
+        permissionKeys: fixture.guardContext.actor.permissionKeys.filter(
+          (key) => key !== "system.user.export",
+        ),
+      },
+    };
+    const forbiddenRequest = (await fixture.app.invoke(
+      "POST",
+      "/system/users/exports",
+      {
+        guardContext: noExportPermission,
+        body: {
+          idempotencyKey: "export-forbidden",
+          reason: "安全审计复核",
+          query: {},
+        },
+        params: {},
+        query: {},
+      },
+    )) as Response;
+    expect(forbiddenRequest.status).toBe(403);
+
+    const notApproved = (await fixture.app.invoke(
+      "GET",
+      "/system/users/exports/:id/download",
+      requestContext(fixture, undefined, { id: created.id }),
+    )) as Response;
+    expect(notApproved.status).toBe(409);
+  });
+
+  test("同一幂等键并发提交不同载荷时仅一个申请成功", async () => {
+    const fixture = await createFixture();
+    const responses = (await Promise.all([
+      postRequest(fixture, "concurrent-conflict"),
+      fixture.app.invoke(
+        "POST",
+        "/system/users/exports",
+        requestContext(fixture, {
+          idempotencyKey: "concurrent-conflict",
+          reason: "另一项并发安全审计复核",
+          query: { includeDeleted: false },
+        }),
+      ),
+    ])) as Response[];
+    expect(responses.map(({ status }) => status).sort()).toEqual([202, 409]);
+  });
+
+  for (const failure of ["create", "link"] as const) {
+    test(`审批 ${failure} 失败时可用同一幂等键补偿恢复`, async () => {
+      const fixture = await createFixture();
+      if (failure === "create") fixture.approval.failCreateOnce = true;
+      if (failure === "link") fixture.requests.failApprovalLinkOnce = true;
+      const failed = (await postRequest(
+        fixture,
+        `approval-${failure}-recovery`,
+      )) as Response;
+      expect(failed.status).toBe(503);
+
+      const recovered = (await (
+        await postRequest(fixture, `approval-${failure}-recovery`)
+      ).json()) as { id: string; approvalId: string };
+      expect(recovered.approvalId).toBe(`approval-${recovered.id}`);
+      expect(fixture.approval.created).toBe(2);
+      expect(await fixture.requests.get(recovered.id)).toMatchObject({
+        approvalId: recovered.approvalId,
+      });
+    });
+  }
+});