create-windy 0.1.0

package/template/apps/server/src/runtime.test.ts

@@ -0,0 +1,264 @@
+import { randomUUIDv7 } from "bun";
+import { describe, expect, test } from "bun:test";
+import { entitlementKey, type AuditEvent } from "@windy/shared";
+import { createFoundationSnapshot } from "./foundation.js";
+import { createServerRuntime } from "./runtime.js";
+import { AuditWriteUnavailableError } from "./audit/contracts.js";
+
+describe("server runtime", () => {
+  test("Bearer token 解析为开发管理员会话和权限", async () => {
+    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const request = new Request("http://localhost/api/foundation", {
+      headers: { authorization: "Bearer token_1" },
+    });
+
+    const context = await runtime.createGuardContext(request);
+
+    expect(context.actor.id).toBe("user_dev_admin");
+    expect(context.actor.permissionKeys).toContain("system.menu.read");
+  });
+
+  test("生产环境强制关闭开发管理员 token", async () => {
+    const runtime = createServerRuntime({
+      NODE_ENV: "production",
+      WINDY_DEV_AUTH_BYPASS: "1",
+      WINDY_DEV_ADMIN_TOKEN: "token_1",
+    });
+
+    const context = await runtime.createGuardContext(
+      new Request("http://localhost/api/foundation", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+
+    expect(context.actor.type).toBe("anonymous");
+  });
+
+  test("生产环境不会接受开发态环境变量 Entitlement", async () => {
+    const runtime = createServerRuntime({
+      NODE_ENV: "production",
+      WINDY_LICENSE_ENTITLEMENTS: "capability.audit",
+    });
+
+    const context = await runtime.createGuardContext(
+      new Request("http://localhost/api/foundation"),
+    );
+
+    expect(context.license?.entitlements).toEqual([]);
+  });
+
+  test("未知 token 保持匿名，License 可由环境变量提供 Entitlement", async () => {
+    const runtime = createServerRuntime({
+      WINDY_LICENSE_ENTITLEMENTS: "capability.ruoyi-compat, capability.agent",
+    });
+    const request = new Request("http://localhost/api/foundation", {
+      headers: { authorization: "Bearer missing" },
+    });
+
+    const context = await runtime.createGuardContext(request);
+
+    expect(context.actor.type).toBe("anonymous");
+    expect(context.license?.entitlements).toEqual([
+      entitlementKey("capability.ruoyi-compat"),
+      entitlementKey("capability.agent"),
+    ]);
+  });
+
+  test("审计 sink 保留内存事件并写穿到持久化 writer", () => {
+    const written: AuditEvent[] = [];
+    const runtime = createServerRuntime(
+      {},
+      {
+        auditWriter: {
+          write(event) {
+            written.push(event);
+          },
+        },
+      },
+    );
+    const event: AuditEvent = {
+      id: randomUUIDv7(),
+      action: "data.export",
+      outcome: "success",
+      actor: { id: "user_1", type: "user", name: "测试用户" },
+      target: { type: "roles" },
+      occurredAt: new Date().toISOString(),
+    };
+
+    runtime.auditSink.recordEvent(event);
+
+    expect(runtime.auditSink.list()).toEqual([event]);
+    expect(written).toEqual([event]);
+  });
+
+  test("生产环境缺少持久化 writer 时关键动作 fail closed", async () => {
+    const runtime = createServerRuntime({ NODE_ENV: "production" });
+    const event: AuditEvent = {
+      id: randomUUIDv7(),
+      action: "feature.update",
+      outcome: "success",
+      actor: { id: "user_1", type: "user", name: "开发人员" },
+      target: { type: "features", id: "system.audit" },
+      occurredAt: new Date().toISOString(),
+    };
+
+    await expect(
+      runtime.auditSink.recordCriticalEvent(event),
+    ).rejects.toBeInstanceOf(AuditWriteUnavailableError);
+    expect(runtime.auditSink.status()).toMatchObject({
+      state: "degraded",
+      dropped: 1,
+    });
+  });
+
+  test("生产环境普通审计缺少 writer 时业务继续但状态告警", () => {
+    const runtime = createServerRuntime({ NODE_ENV: "production" });
+
+    runtime.auditSink.recordEvent({
+      id: randomUUIDv7(),
+      action: "data.export",
+      outcome: "success",
+      actor: { id: "user_1", type: "user", name: "业务用户" },
+      target: { type: "reports" },
+      occurredAt: new Date().toISOString(),
+    });
+
+    expect(runtime.auditSink.status()).toMatchObject({
+      state: "degraded",
+      dropped: 1,
+      alert: "审计写入失败",
+    });
+  });
+
+  test("外部 actor resolver 优先提供数据库角色权限来源", async () => {
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+      {
+        actorResolver: {
+          async resolve() {
+            return {
+              id: "user_from_db",
+              type: "user",
+              name: "数据库用户",
+              roleCodes: ["operator"],
+              permissionKeys: ["system.audit.read"],
+            };
+          },
+        },
+      },
+    );
+    const request = new Request("http://localhost/api/system/audit-logs", {
+      headers: { authorization: "Bearer token_1" },
+    });
+
+    const context = await runtime.createGuardContext(request);
+
+    expect(context.actor.id).toBe("user_from_db");
+    expect(context.actor.permissionKeys).toEqual(["system.audit.read"]);
+  });
+
+  test("外部 license resolver 优先提供真实 License 授权状态", async () => {
+    const runtime = createServerRuntime(
+      { WINDY_LICENSE_ENTITLEMENTS: "" },
+      {
+        licenseResolver: {
+          async resolve() {
+            return {
+              entitlements: [entitlementKey("capability.ruoyi-compat")],
+            };
+          },
+        },
+      },
+    );
+    const request = new Request("http://localhost/api/foundation");
+
+    const context = await runtime.createGuardContext(request);
+
+    expect(context.license?.entitlements).toEqual([
+      entitlementKey("capability.ruoyi-compat"),
+    ]);
+  });
+
+  test("Feature 运行态在请求内缓存，并在下一请求重新读取", async () => {
+    const manifest = createFoundationSnapshot().features[0]!;
+    let enabled = true;
+    let resolveCount = 0;
+    const runtime = createServerRuntime(
+      {},
+      {
+        featureResolver: {
+          resolve(key) {
+            resolveCount += 1;
+            return { ...manifest, key, enabled };
+          },
+        },
+      },
+    );
+    const firstContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/users"),
+    );
+
+    const firstResolution = await runtime.resolveFeature(
+      firstContext,
+      manifest,
+    );
+    expect(firstResolution.enabled).toBe(true);
+    expect(firstResolution.requiredEntitlement).toBe(
+      manifest.requiredEntitlement,
+    );
+    enabled = false;
+    expect((await runtime.resolveFeature(firstContext, manifest)).enabled).toBe(
+      true,
+    );
+    expect(resolveCount).toBe(1);
+
+    const nextContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/users"),
+    );
+    expect((await runtime.resolveFeature(nextContext, manifest)).enabled).toBe(
+      false,
+    );
+    expect(resolveCount).toBe(2);
+  });
+
+  test("无数据库时开发回退 Manifest，生产环境 fail closed", async () => {
+    const manifest = createFoundationSnapshot().features[0]!;
+    const development = createServerRuntime({ NODE_ENV: "development" });
+    const production = createServerRuntime({ NODE_ENV: "production" });
+    const request = new Request("http://localhost/api/system/users");
+    const developmentContext = await development.createGuardContext(request);
+    const productionContext = await production.createGuardContext(request);
+
+    expect(
+      (await development.resolveFeature(developmentContext, manifest)).enabled,
+    ).toBe(manifest.enabled);
+    expect(
+      await production.resolveFeature(productionContext, manifest),
+    ).toMatchObject({
+      enabled: false,
+      visible: "hidden",
+    });
+  });
+
+  test("数据库运行态读取失败时 fail closed", async () => {
+    const manifest = createFoundationSnapshot().features[0]!;
+    const runtime = createServerRuntime(
+      {},
+      {
+        featureResolver: {
+          resolve() {
+            throw new Error("database unavailable");
+          },
+        },
+      },
+    );
+    const context = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/users"),
+    );
+
+    expect(await runtime.resolveFeature(context, manifest)).toMatchObject({
+      enabled: false,
+      visible: "hidden",
+    });
+  });
+});

package/template/apps/server/src/runtime.ts

@@ -0,0 +1,324 @@
+import type {
+  AuditEvent,
+  FeatureFlagDefinition,
+  PageResult,
+} from "@windy/shared";
+import {
+  createRequestGuardContext,
+  type GuardDecision,
+  type RequestActor,
+} from "./guards.js";
+import { readBearerToken } from "./auth/bearer-token.js";
+import { readDevelopmentAuthBypass } from "./auth/development-bypass.js";
+import { redactAuditEvent } from "./audit/redaction.js";
+import {
+  AuditWriteUnavailableError,
+  type AuditWritePolicy,
+  type AuditWriteStatus,
+} from "./audit/contracts.js";
+import {
+  developmentLicenseState,
+  InMemoryLicenseEntitlementStore,
+  type LicenseEntitlementResolver,
+} from "./runtime-license.js";
+import { developmentAdminActor } from "./runtime-development.js";
+
+export interface SessionRecord {
+  token: string;
+  actor: RequestActor;
+}
+
+export interface RequestActorResolver {
+  resolve(
+    request: Request,
+  ): Promise<RequestActor | undefined> | RequestActor | undefined;
+}
+
+export interface FeatureFlagRuntimeResolver {
+  resolve(
+    key: string,
+  ):
+    | Promise<FeatureFlagRuntimeState | undefined>
+    | FeatureFlagRuntimeState
+    | undefined;
+}
+
+export interface FeatureFlagRuntimeState {
+  key: string;
+  enabled: boolean;
+  visible: FeatureFlagDefinition["visible"];
+  allowedLicenseVersions?: FeatureFlagDefinition["allowedLicenseVersions"];
+}
+
+export interface AuditEventWriter {
+  write(event: AuditEvent, policy?: AuditWritePolicy): Promise<void> | void;
+  status?(): AuditWriteStatus;
+}
+
+export interface AuditEventListQuery {
+  page: number;
+  pageSize: number;
+  actorId?: string;
+  action?: string;
+  resource?: string;
+  resourceId?: string;
+  occurredAfter?: string;
+  occurredBefore?: string;
+  includeScheduler?: boolean;
+}
+
+export interface AuditEventReader {
+  list(query: AuditEventListQuery): Promise<PageResult<AuditEvent>>;
+}
+
+export interface ServerRuntimeOptions {
+  actorResolver?: RequestActorResolver;
+  licenseResolver?: LicenseEntitlementResolver;
+  featureResolver?: FeatureFlagRuntimeResolver;
+  auditWriter?: AuditEventWriter;
+  auditReader?: AuditEventReader;
+}
+
+export class InMemorySessionStore {
+  private readonly sessions = new Map<string, RequestActor>();
+
+  constructor(records: SessionRecord[] = []) {
+    for (const record of records) {
+      this.sessions.set(record.token, record.actor);
+    }
+  }
+
+  resolve(request: Request): RequestActor | undefined {
+    const token = readBearerToken(request);
+    return token ? this.sessions.get(token) : undefined;
+  }
+}
+
+export class InMemoryAuditSink {
+  private readonly events: AuditEvent[] = [];
+  private readonly fallbackStatus: AuditWriteStatus = {
+    state: "healthy",
+    attempted: 0,
+    persisted: 0,
+    failedAttempts: 0,
+    retries: 0,
+    queued: 0,
+    dropped: 0,
+  };
+
+  constructor(
+    private readonly writer?: AuditEventWriter,
+    private readonly requireCriticalWriter = false,
+  ) {}
+
+  record(decision: GuardDecision): void {
+    if (decision.auditEvent) {
+      this.recordEvent(decision.auditEvent);
+    }
+  }
+
+  recordEvent(event: AuditEvent): void {
+    const redacted = redactAuditEvent(event);
+    this.events.push(redacted);
+    this.fallbackStatus.attempted += 1;
+    if (!this.writer) {
+      if (this.requireCriticalWriter) this.markFallbackFailure();
+      else this.markFallbackSuccess();
+      return;
+    }
+    try {
+      const writeResult = this.writer.write(redacted, "ordinary");
+      if (writeResult instanceof Promise) {
+        writeResult.then(
+          () => this.markFallbackSuccess(),
+          () => this.markFallbackFailure(),
+        );
+      } else {
+        this.markFallbackSuccess();
+      }
+    } catch {
+      this.markFallbackFailure();
+    }
+  }
+
+  async recordCriticalEvent(event: AuditEvent): Promise<void> {
+    const redacted = redactAuditEvent(event);
+    this.events.push(redacted);
+    this.fallbackStatus.attempted += 1;
+    if (!this.writer && this.requireCriticalWriter) {
+      this.markFallbackFailure();
+      throw new AuditWriteUnavailableError();
+    }
+    try {
+      await this.writer?.write(redacted, "critical");
+      this.markFallbackSuccess();
+    } catch (error) {
+      this.markFallbackFailure();
+      throw error;
+    }
+  }
+
+  list(): AuditEvent[] {
+    return [...this.events];
+  }
+
+  status(): AuditWriteStatus {
+    return this.writer?.status?.() || { ...this.fallbackStatus };
+  }
+
+  private markFallbackSuccess(): void {
+    this.fallbackStatus.persisted += 1;
+    this.fallbackStatus.lastSuccessAt = new Date().toISOString();
+  }
+
+  private markFallbackFailure(): void {
+    this.fallbackStatus.failedAttempts += 1;
+    this.fallbackStatus.dropped += 1;
+    this.fallbackStatus.lastFailureAt = new Date().toISOString();
+    this.fallbackStatus.state = "degraded";
+    this.fallbackStatus.alert = "审计写入失败";
+  }
+}
+
+export function createServerRuntime(
+  env: Record<string, string | undefined> = process.env,
+  options: ServerRuntimeOptions = {},
+) {
+  const developmentAuth = readDevelopmentAuthBypass(env);
+  const sessionStore = new InMemorySessionStore(
+    developmentAuth.token
+      ? [{ token: developmentAuth.token, actor: developmentAdminActor() }]
+      : [],
+  );
+  const licenseStore = new InMemoryLicenseEntitlementStore(
+    developmentLicenseState(env),
+  );
+  const auditSink = new InMemoryAuditSink(
+    options.auditWriter,
+    env.NODE_ENV === "production",
+  );
+  const featureRequestCache = new WeakMap<
+    ReturnType<typeof createRequestGuardContext>,
+    Map<string, FeatureFlagDefinition>
+  >();
+
+  return {
+    auditSink,
+    async createGuardContext(
+      request: Request,
+      metadata: { clientIp?: string } = {},
+    ) {
+      const actor =
+        (await options.actorResolver?.resolve(request)) ||
+        sessionStore.resolve(request);
+      const license =
+        (await options.licenseResolver?.resolve()) || licenseStore.resolve();
+      return createRequestGuardContext(request, {
+        clientIp: metadata.clientIp,
+        resolveActor: () => actor,
+        resolveLicense: () => license,
+      });
+    },
+    async createGuardContextForActor(
+      request: Request,
+      actor: RequestActor,
+      metadata: { clientIp?: string } = {},
+    ) {
+      const license =
+        (await options.licenseResolver?.resolve()) || licenseStore.resolve();
+      return createRequestGuardContext(request, {
+        clientIp: metadata.clientIp,
+        resolveActor: () => actor,
+        resolveLicense: () => license,
+      });
+    },
+    async resolveFeature(
+      context: ReturnType<typeof createRequestGuardContext>,
+      manifestFeature: FeatureFlagDefinition,
+    ): Promise<FeatureFlagDefinition> {
+      let cache = featureRequestCache.get(context);
+      if (!cache) {
+        cache = new Map();
+        featureRequestCache.set(context, cache);
+      }
+      const cached = cache.get(manifestFeature.key);
+      if (cached) return cached;
+
+      let resolved: FeatureFlagDefinition;
+      if (options.featureResolver) {
+        try {
+          const state = await options.featureResolver.resolve(
+            manifestFeature.key,
+          );
+          resolved = state
+            ? {
+                ...manifestFeature,
+                enabled: state.enabled,
+                visible: state.visible,
+                ...(Object.hasOwn(state, "allowedLicenseVersions")
+                  ? {
+                      allowedLicenseVersions: state.allowedLicenseVersions,
+                    }
+                  : {}),
+              }
+            : disabledFeature(manifestFeature);
+        } catch {
+          resolved = disabledFeature(manifestFeature);
+        }
+      } else {
+        resolved =
+          env.NODE_ENV === "production"
+            ? disabledFeature(manifestFeature)
+            : manifestFeature;
+      }
+      cache.set(manifestFeature.key, resolved);
+      return resolved;
+    },
+    recordDecisions(decisions: Array<GuardDecision | undefined>) {
+      for (const decision of decisions) {
+        if (decision) {
+          auditSink.record(decision);
+        }
+      }
+    },
+    async listAuditEvents(
+      query: AuditEventListQuery,
+    ): Promise<PageResult<AuditEvent>> {
+      if (options.auditReader) {
+        return options.auditReader.list(query);
+      }
+      const events = auditSink
+        .list()
+        .filter((event) => matchesAuditQuery(event, query))
+        .reverse();
+      const start = (query.page - 1) * query.pageSize;
+      return {
+        items: events.slice(start, start + query.pageSize),
+        total: events.length,
+        page: query.page,
+        pageSize: query.pageSize,
+      };
+    },
+  };
+}
+
+function matchesAuditQuery(
+  event: AuditEvent,
+  query: AuditEventListQuery,
+): boolean {
+  return (
+    (!query.actorId || event.actor.id === query.actorId) &&
+    (!query.action || event.action === query.action) &&
+    (!query.resource || event.target?.type === query.resource) &&
+    (!query.resourceId || event.target?.id === query.resourceId) &&
+    (query.includeScheduler || event.actor.id !== "system_scheduler") &&
+    (!query.occurredAfter || event.occurredAt >= query.occurredAfter) &&
+    (!query.occurredBefore || event.occurredAt <= query.occurredBefore)
+  );
+}
+
+function disabledFeature(
+  feature: FeatureFlagDefinition,
+): FeatureFlagDefinition {
+  return { ...feature, enabled: false, visible: "hidden" };
+}

package/template/apps/server/src/scheduler/audit.ts

@@ -0,0 +1,38 @@
+import { randomUUIDv7 } from "bun";
+import type { AuditEvent } from "@windy/shared";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { ScheduledTaskRun } from "./types.js";
+
+export function schedulerAuditEvent(
+  context: RequestGuardContext,
+  run: ScheduledTaskRun,
+  action: "task.trigger" | "task.execute",
+  outcome: AuditEvent["outcome"],
+  occurredAt: Date,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action,
+    outcome,
+    actor: auditActor(context.actor),
+    target: { type: "scheduled-task", id: run.taskKey },
+    requestId: context.requestId,
+    metadata: {
+      runId: run.id,
+      trigger: run.trigger,
+      attempt: run.attempt,
+      status: run.status,
+      ...(run.error ? { reason: run.error } : {}),
+    },
+    occurredAt: occurredAt.toISOString(),
+  };
+}
+
+function auditActor(actor: RequestActor): AuditEvent["actor"] {
+  return {
+    id: actor.id,
+    type: actor.type === "anonymous" ? "user" : actor.type,
+    name: actor.name,
+    roleCodes: actor.roleCodes,
+  };
+}

package/template/apps/server/src/scheduler/definitions.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { systemFoundationModule } from "@windy/modules";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createPlatformTaskDefinitions } from "./definitions.js";
+
+describe("平台任务 Manifest Adapter", () => {
+  test("运行时任务元数据与 Manifest 声明一一对应", () => {
+    const definitions = createPlatformTaskDefinitions(
+      createFoundationSnapshot().features,
+      {
+        bulkDataDispatch: () => ({ claimed: false }),
+        bulkDataCleanup: () => ({ deleted: 0 }),
+        storageCleanup: () => ({ deleted: 0 }),
+        workflowTimeoutDispatch: () => ({ claimed: false }),
+        governedExportDispatch: () => ({ claimed: false }),
+      },
+    );
+
+    expect(definitions.map(({ key }) => key).sort()).toEqual(
+      systemFoundationModule()
+        .tasks.map(({ key }) => key)
+        .sort(),
+    );
+    expect(
+      definitions
+        .find(({ key }) => key === "system.bulk-data.dispatch")
+        ?.isIdleResult?.({ claimed: false }),
+    ).toBe(true);
+    expect(
+      definitions
+        .find(({ key }) => key === "system.governed-export.dispatch")
+        ?.isIdleResult?.({ claimed: false }),
+    ).toBe(true);
+  });
+});