create-windy 0.2.33 → 0.3.0

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

@@ -17,6 +17,7 @@ import { createWorkOrderRepository } from "./work-order/repository.js";
 import { createDrizzleWorkOrderRepository } from "./work-order/drizzle-repository.js";
 import { createWorkOrderRouteDefinitions } from "./work-order/routes.js";
 import { WorkOrderSearchProvider } from "./work-order/search-provider.js";
+import { createWorkOrderOpenSearchIndex } from "./work-order/opensearch-index.js";
 import { WorkOrderService } from "./work-order/service.js";
 
 export interface WorkOrderModuleDependencies {
@@ -42,6 +43,7 @@ export interface WorkOrderModule {
  */
 export function createWorkOrderModule(): WorkOrderModule {
   let service: WorkOrderService | undefined;
+  const searchIndex = createWorkOrderOpenSearchIndex(process.env);
   const requireService = () => {
     if (!service) throw new Error("示例工单模块尚未挂载");
     return service;
@@ -52,7 +54,7 @@ export function createWorkOrderModule(): WorkOrderModule {
       requireService().operationalSnapshot(
         platformDataActor("task_work_order_snapshot", "工单运营快照任务"),
       ),
-    searchProvider: new WorkOrderSearchProvider(requireService),
+    searchProvider: new WorkOrderSearchProvider(requireService, searchIndex),
   });
   return {
     ...serverModule,
@@ -67,6 +69,7 @@ export function createWorkOrderModule(): WorkOrderModule {
             ? createDrizzleWorkOrderRepository(dependencies.db)
             : createWorkOrderRepository()),
         dependencies.departments,
+        searchIndex,
       );
     },
   };

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

@@ -1,5 +1,6 @@
 import type {
   ApiPermissionBinding,
+  AuditActor,
   AuditEvent,
   EntitlementKey,
   FeatureFlagDefinition,
@@ -33,6 +34,7 @@ export interface RequestGuardContext {
   actor: RequestActor;
   startedAt: string;
   clientIp?: string;
+  userAgent?: string;
   license?: {
     versionKey?: LicenseVersionKey;
     /** V1 兼容字段。新 License 不再包含 Entitlement。 */
@@ -61,6 +63,7 @@ export interface GuardDecision {
 
 export interface RequestGuardContextOptions {
   clientIp?: string;
+  userAgent?: string;
   resolveActor?: (request: Request) => RequestActor | undefined;
   resolveLicense?: (
     request: Request,
@@ -86,10 +89,24 @@ export function createRequestGuardContext(
     actor: options.resolveActor?.(request) || anonymousActor(),
     startedAt: new Date().toISOString(),
     clientIp: options.clientIp,
+    userAgent: options.userAgent,
     license: options.resolveLicense?.(request),
   };
 }
 
+export function auditActor(
+  context: Pick<RequestGuardContext, "actor" | "clientIp" | "userAgent">,
+): AuditActor {
+  return {
+    id: context.actor.id,
+    type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+    name: context.actor.name,
+    roleCodes: context.actor.roleCodes,
+    ip: context.clientIp,
+    userAgent: context.userAgent,
+  };
+}
+
 export function evaluatePermissionGuard(
   context: RequestGuardContext,
   binding: PermissionGuardRequirement,
@@ -207,11 +224,7 @@ function deniedDecision(
       id: randomUUIDv7(),
       action: "security.denied",
       outcome: "denied",
-      actor: {
-        id: context.actor.id,
-        type: context.actor.type === "anonymous" ? "user" : context.actor.type,
-        name: context.actor.name,
-      },
+      actor: auditActor(context),
       target: {
         type: "guard",
         id: targetId,

package/template/apps/server/src/http/request-source.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import {
+  requestSourcePolicyFromEnv,
+  resolveRequestSource,
+} from "./request-source.js";
+
+describe("平台请求来源信任边界", () => {
+  test("默认使用直接对端并忽略客户端伪造的转发头", () => {
+    const source = resolveRequestSource(
+      request("203.0.113.66"),
+      "198.51.100.10",
+      requestSourcePolicyFromEnv({}),
+    );
+
+    expect(source).toEqual({
+      clientIp: "198.51.100.10",
+      userAgent: "Windy-Test/1.0",
+    });
+  });
+
+  test("仅显式启用且直接对端受信时采用单一合法转发来源", () => {
+    const policy = requestSourcePolicyFromEnv({
+      WINDY_TRUST_PROXY: "true",
+      WINDY_TRUSTED_PROXY_IPS: "10.0.0.8",
+    });
+
+    expect(
+      resolveRequestSource(request("203.0.113.66"), "::1", policy).clientIp,
+    ).toBe("203.0.113.66");
+    expect(
+      resolveRequestSource(request("203.0.113.67"), "10.0.0.8", policy)
+        .clientIp,
+    ).toBe("203.0.113.67");
+    expect(
+      resolveRequestSource(request("203.0.113.68"), "10.0.0.9", policy)
+        .clientIp,
+    ).toBe("10.0.0.9");
+  });
+
+  test("多段或非法转发来源退回直接对端", () => {
+    const policy = requestSourcePolicyFromEnv({
+      WINDY_TRUST_PROXY: "true",
+    });
+    for (const forwardedFor of [
+      "203.0.113.66, 198.51.100.9",
+      "not-an-ip",
+      "203.0.113.66:443",
+    ]) {
+      expect(
+        resolveRequestSource(request(forwardedFor), "127.0.0.1", policy)
+          .clientIp,
+      ).toBe("127.0.0.1");
+    }
+  });
+
+  test("代理配置默认关闭且错误配置 fail closed", () => {
+    expect(requestSourcePolicyFromEnv({})).toEqual({
+      trustProxy: false,
+      trustedProxyIps: [],
+    });
+    expect(() =>
+      requestSourcePolicyFromEnv({
+        WINDY_TRUSTED_PROXY_IPS: "10.0.0.8",
+      }),
+    ).toThrow("WINDY_TRUST_PROXY=true");
+    expect(() =>
+      requestSourcePolicyFromEnv({ WINDY_TRUST_PROXY: "yes" }),
+    ).toThrow("只允许 true 或 false");
+    expect(() =>
+      requestSourcePolicyFromEnv({
+        WINDY_TRUST_PROXY: "true",
+        WINDY_TRUSTED_PROXY_IPS: "10.0.0.999",
+      }),
+    ).toThrow("无效 IP");
+  });
+});
+
+function request(forwardedFor: string): Request {
+  return new Request("https://windy.example.test/api/system/users", {
+    headers: {
+      "user-agent": "Windy-Test/1.0",
+      "x-forwarded-for": forwardedFor,
+    },
+  });
+}

package/template/apps/server/src/http/request-source.ts

@@ -0,0 +1,90 @@
+import { isIP } from "node:net";
+
+export interface RequestSourcePolicy {
+  trustProxy: boolean;
+  trustedProxyIps: readonly string[];
+}
+
+export interface RequestSource {
+  clientIp?: string;
+  userAgent?: string;
+}
+
+export function requestSourcePolicyFromEnv(
+  env: Record<string, string | undefined>,
+): RequestSourcePolicy {
+  const trustProxy = readBoolean(env.WINDY_TRUST_PROXY);
+  const configuredIps = (env.WINDY_TRUSTED_PROXY_IPS || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (!trustProxy && configuredIps.length) {
+    throw new Error(
+      "配置 WINDY_TRUSTED_PROXY_IPS 时必须显式设置 WINDY_TRUST_PROXY=true",
+    );
+  }
+  return {
+    trustProxy,
+    trustedProxyIps: configuredIps.map((value) => {
+      const normalized = normalizeIp(value);
+      if (!normalized) {
+        throw new Error(`WINDY_TRUSTED_PROXY_IPS 包含无效 IP：${value}`);
+      }
+      return normalized;
+    }),
+  };
+}
+
+export function resolveRequestSource(
+  request: Request,
+  peerIp: string | undefined,
+  policy: RequestSourcePolicy,
+): RequestSource {
+  const normalizedPeerIp = normalizeIp(peerIp);
+  const forwardedIp = resolveForwardedIp(request, normalizedPeerIp, policy);
+  return {
+    clientIp: forwardedIp || normalizedPeerIp,
+    userAgent: normalizeUserAgent(request.headers.get("user-agent")),
+  };
+}
+
+function resolveForwardedIp(
+  request: Request,
+  peerIp: string | undefined,
+  policy: RequestSourcePolicy,
+): string | undefined {
+  if (!policy.trustProxy || !peerIp || !isTrustedProxy(peerIp, policy)) {
+    return undefined;
+  }
+  const header = request.headers.get("x-forwarded-for")?.trim();
+  if (!header || header.includes(",")) return undefined;
+  return normalizeIp(header);
+}
+
+function isTrustedProxy(peerIp: string, policy: RequestSourcePolicy): boolean {
+  if (isLoopback(peerIp)) return true;
+  return policy.trustedProxyIps.some((value) => normalizeIp(value) === peerIp);
+}
+
+function isLoopback(ip: string): boolean {
+  return ip === "::1" || (isIP(ip) === 4 && ip.startsWith("127."));
+}
+
+function normalizeIp(value: string | undefined): string | undefined {
+  const candidate = value?.trim().toLowerCase();
+  if (!candidate) return undefined;
+  const mapped = candidate.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+  const normalized = mapped && isIP(mapped) === 4 ? mapped : candidate;
+  return isIP(normalized) ? normalized : undefined;
+}
+
+function normalizeUserAgent(value: string | null): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized.slice(0, 1_024) : undefined;
+}
+
+function readBoolean(value: string | undefined): boolean {
+  if (value === undefined || value === "" || value === "false") return false;
+  if (value === "true") return true;
+  throw new Error("WINDY_TRUST_PROXY 只允许 true 或 false");
+}

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

@@ -104,6 +104,7 @@ const {
   moduleHosts,
   systemRepositories,
 } = await bootstrapServerModules(platformConfig, persistence);
+const features = foundationSnapshot.features;
 // @windy-module system.license begin
 const platformLicenseOptions = createPlatformLicenseRuntimeOptions(process.env);
 const platformLicenseRuntime = new PlatformLicenseRuntime(
@@ -121,7 +122,7 @@ const runtime = createServerRuntime(process.env, {
     : persistence?.licenseResolver,
   // @windy-module system.license end
   featureResolver: persistence ? systemRepositories.features : undefined,
-  featureCatalog: foundationSnapshot.features,
+  featureCatalog: features,
   // @windy-module system.audit begin
   auditReader: persistence?.auditReader,
   auditWriter: persistence?.auditWriter,
@@ -140,7 +141,11 @@ platformLicenseRuntime.setAuditSink(runtime.auditSink);
 // @windy-module system.license end
 const { authRepository, authService } = createAuthRuntime({
   repository: persistence?.authRepository,
-  sessionTtlSeconds: platformConfig.security.sessionTtlSeconds,
+  sessionTtlSeconds: () => platformConfig.security.sessionTtlSeconds,
+  passwordPolicy: () => ({
+    minLength: platformConfig.security.passwordMinLength,
+    maxLength: platformConfig.security.passwordMaxLength,
+  }),
   auditWriter: (event) => runtime.auditSink.recordCriticalEvent(event),
   // @windy-module system.audit begin
   auditReader: persistence?.auditReader,
@@ -152,12 +157,17 @@ const storageRuntime = createStorageRuntime(
   persistence?.db,
   moduleHosts.uploadPolicies,
 );
+configurationRuntime.bindStorage(storageRuntime.uploads);
 // @windy-module system.storage end
 // @windy-module system.settings begin
-const platformSettings = createPlatformSettingsRuntime(persistence?.db, {
-  softwareName: platformConfig.name,
-  logoUrl: platformConfig.logoUrl,
-});
+const platformSettings = createPlatformSettingsRuntime(
+  persistence?.db,
+  {
+    softwareName: platformConfig.name,
+    logoUrl: platformConfig.logoUrl,
+  },
+  () => ({ timeZone: platformConfig.regional.timeZone }),
+);
 // @windy-module system.settings end
 // @windy-module system.search begin
 const searchHost = createSearchHost(
@@ -169,13 +179,14 @@ const searchHost = createSearchHost(
 // @windy-module system.scheduler begin
 const moduleTaskDefinitions = createModuleTaskDefinitions(
   moduleHosts,
-  foundationSnapshot.features,
+  features,
 );
 const {
   bulkDataService,
   scheduler,
   taskDefinitions: scheduledTaskDefinitions,
   notifications: notificationRepository,
+  notificationService,
   workflow: workflowService,
   governedExportService,
   durable: durableJobRuntime,
@@ -187,6 +198,7 @@ const {
   storage: storageRuntime,
   moduleTasks: moduleTaskDefinitions,
   bulkRetentionDays: readPositiveInt(process.env.BULK_DATA_RETENTION_DAYS, 7),
+  mailConfig: platformConfig.mail,
   installModuleDurableHandlers: moduleHosts.installDurableHandlers,
 });
 const schedulerWorker = new SchedulerWorker(
@@ -209,33 +221,29 @@ registerAuthRoutes(app, authService, {
   sessionCookieName: platformConfig.security.sessionCookieName,
   secureCookie: process.env.NODE_ENV === "production",
 });
-registerProfileRoutes(
-  app,
-  authRepository,
-  runtime,
-  foundationSnapshot.features,
-);
+registerProfileRoutes(app, authRepository, runtime, features);
 
 // @windy-module system.license begin
 registerPlatformLicenseRoutes(app, platformLicenseRuntime);
 // @windy-module system.license end
 
 // @windy-module system.settings begin
-platformSettings.register(app, runtime, foundationSnapshot.features);
+platformSettings.register(app, runtime, features);
 // @windy-module system.settings end
 // @windy-module system.notification begin
 registerNotificationRoutes(
   app,
   notificationRepository,
   runtime,
-  foundationSnapshot.features,
+  features,
+  notificationService,
 );
 // @windy-module system.notification end
 // @windy-module system.workflow begin
 registerWorkflowRoutes(app, workflowService, runtime);
 // @windy-module system.workflow end
 // @windy-module system.configuration begin
-configurationRuntime.register(app, runtime, foundationSnapshot.features);
+configurationRuntime.register(app, runtime, features);
 // @windy-module system.configuration end
 // @windy-module system.storage begin
 registerStorageRoutes(
@@ -248,7 +256,7 @@ registerStorageRoutes(
       `/api/platform/files/${fileId}`,
   },
   runtime,
-  foundationSnapshot.features,
+  features,
 );
 // @windy-module system.storage end
 // @windy-module system.search begin
@@ -260,27 +268,18 @@ registerAdminBootstrapRoute(app, runtime, {
   snapshot: foundationSnapshot,
   loadMenus: () => systemRepositories.menuRegistry.tree(),
 });
-registerSessionContextRoute(app, runtime, foundationSnapshot.features);
+registerSessionContextRoute(app, runtime, features);
 
 registerFoundationRoute(app, runtime, foundationSnapshot, systemRepositories);
 
 // @windy-module system.data-governance begin
-registerGovernedUserExportRoutes(
-  app,
-  governedExportService,
-  runtime,
-  foundationSnapshot.features,
-);
+registerGovernedUserExportRoutes(app, governedExportService, runtime, features);
 // @windy-module system.data-governance end
-registerSystemRoutes(
-  app,
-  systemRepositories,
-  runtime,
-  foundationSnapshot.features,
-  { authRepository: persistence?.authRepository },
-);
+registerSystemRoutes(app, systemRepositories, runtime, features, {
+  authRepository: persistence?.authRepository,
+});
 // @windy-module system.operations begin
-registerSystemOperationRoutes(app, runtime, foundationSnapshot.features, {
+registerSystemOperationRoutes(app, runtime, features, {
   redisHealthProbe: configurationRuntime.redisHealthProbe,
   onlineUserProvider: () =>
     persistence?.authRepository.listActiveSessions(
@@ -293,7 +292,13 @@ registerSystemOperationRoutes(app, runtime, foundationSnapshot.features, {
 // @windy-module system.agent begin
 const toolHandlers = new Map([
   ...createSystemToolHandlers(systemRepositories, runtime),
-  ...createModuleToolHandlerMap(moduleHosts),
+  ...createModuleToolHandlerMap(moduleHosts, {
+    runtime,
+    features: foundationSnapshot.features,
+    // @windy-module system.storage begin
+    storage: storageRuntime,
+    // @windy-module system.storage end
+  }),
 ]);
 const toolRegistry = new GovernedToolRegistry(
   foundationModules,
@@ -301,10 +306,7 @@ const toolRegistry = new GovernedToolRegistry(
   runtime,
 );
 registerAgentRoutes(app, toolRegistry);
-registerMcpRoutes(
-  app,
-  new PlatformMcpAdapter(toolRegistry, runtime, foundationSnapshot.features),
-);
+registerMcpRoutes(app, new PlatformMcpAdapter(toolRegistry, runtime, features));
 registerAgentPlatformRuntime({
   app,
   platformConfig,
@@ -315,19 +317,14 @@ registerAgentPlatformRuntime({
 });
 // @windy-module system.agent end
 // @windy-module system.scheduler begin
-registerSchedulerRoutes(app, scheduler, runtime, foundationSnapshot.features);
+registerSchedulerRoutes(app, scheduler, runtime, features);
 // @windy-module system.scheduler end
 // @windy-module system.bulk-data begin
-registerBulkDataRoutes(
-  app,
-  bulkDataService,
-  runtime,
-  foundationSnapshot.features,
-);
+registerBulkDataRoutes(app, bulkDataService, runtime, features);
 // @windy-module system.bulk-data end
 installModuleRoutes(moduleHosts, app, {
   runtime,
-  features: foundationSnapshot.features,
+  features,
   // @windy-module system.scheduler begin
   jobs: durableJobRuntime.service,
   // @windy-module system.scheduler end
@@ -337,6 +334,9 @@ installModuleRoutes(moduleHosts, app, {
     files: storageRuntime.files,
   },
   // @windy-module system.storage end
+  userDirectory: {
+    repositories: systemRepositories,
+  },
 });
 
 validateInstalledRuntime({

package/template/apps/server/src/license/routes.ts

@@ -52,6 +52,8 @@ export function registerPlatformLicenseRoutes(
       const installed = await licenseRuntime.install(rawLicense, {
         actor: context.guardContext.actor,
         requestId: context.guardContext.requestId,
+        clientIp: context.guardContext.clientIp,
+        userAgent: context.guardContext.userAgent,
       });
       if (installed.result.status === "rejected") {
         return Response.json(

package/template/apps/server/src/license/runtime-service.ts

@@ -17,7 +17,11 @@ import type {
   LicenseFailureReason,
   SignedLicense,
 } from "@southwind-ai/shared";
-import type { RequestActor } from "../guards.js";
+import {
+  auditActor,
+  type RequestActor,
+  type RequestGuardContext,
+} from "../guards.js";
 import type { InMemoryAuditSink } from "../runtime.js";
 import type {
   LicenseEntitlementResolver,
@@ -57,10 +61,10 @@ export interface PlatformLicenseRuntimeOptions {
   now?: () => Date;
 }
 
-export interface LicenseInstallActorContext {
-  actor: RequestActor;
-  requestId: string;
-}
+export type LicenseInstallActorContext = Pick<
+  RequestGuardContext,
+  "actor" | "requestId" | "clientIp" | "userAgent"
+>;
 
 export class PlatformLicenseRuntime implements LicenseEntitlementResolver {
   private readonly stateStorage: LicenseStorage;
@@ -285,12 +289,7 @@ function installAuditEvent(
     id: crypto.randomUUID(),
     action: "license.update",
     outcome: success ? "success" : "failure",
-    actor: {
-      id: context.actor.id,
-      type: "user",
-      name: context.actor.name,
-      roleCodes: context.actor.roleCodes,
-    },
+    actor: auditActor(context),
     target: {
       type: "runtime-license",
       id: result.license?.claims.licenseId || candidate?.claims.licenseId,

package/template/apps/server/src/module-bootstrap.ts

@@ -17,7 +17,7 @@ import {
 } from "./module-host.js";
 import type { ServerPersistence } from "./persistence.js";
 // @windy-module system.storage begin
-import { platformUploadPolicies } from "./storage/runtime.js";
+import { createPlatformUploadPolicies } from "./storage/runtime.js";
 // @windy-module system.storage end
 import {
   createSystemRepositories,
@@ -51,7 +51,7 @@ export async function bootstrapServerModules(
     installations: installedBusinessModules,
     baseUploadPolicies: [
       // @windy-module system.storage begin
-      ...platformUploadPolicies,
+      ...createPlatformUploadPolicies(platformConfig),
       // @windy-module system.storage end
     ],
   });

package/template/apps/server/src/module-host/initialize-contracts.ts

@@ -5,6 +5,7 @@ import type {
   ModuleAiOperationHandlerRegistration,
   ModuleInitializer,
   ModuleRolePreset,
+  ModuleResourceFileAccessPolicy,
   ModuleRouteDefinition,
   ModuleSearchProvider,
   ModuleTaskHandlerRegistration,
@@ -54,6 +55,7 @@ export interface InitializeModuleHostsInput {
 export interface InitializedModuleHosts {
   readonly manifests: readonly ModuleManifest[];
   readonly uploadPolicies: readonly ModuleUploadPolicy[];
+  readonly resourceFileAccessPolicies: readonly ModuleResourceFileAccessPolicy[];
   readonly routes: readonly RegisteredModuleRoute[];
   readonly taskHandlers: readonly RegisteredModuleTaskHandler[];
   readonly toolHandlers: readonly RegisteredModuleToolHandler[];
@@ -63,5 +65,9 @@ export interface InitializedModuleHosts {
   manifestOf(moduleName: string): ModuleManifest;
   /** 该模块经 Host 注册的上传用途集合（不含平台基础用途）。 */
   uploadPurposesOf(moduleName: string): ReadonlySet<string>;
+  /** 该模块注册的资源文件读取策略。 */
+  resourceFileAccessPoliciesOf(
+    moduleName: string,
+  ): readonly ModuleResourceFileAccessPolicy[];
   installDurableHandlers(registry: DurableHandlerRegistry): void;
 }