create-windy 0.8.3 → 0.10.0

package/template/apps/server/src/settings/watermark-routes.ts

@@ -1,3 +1,4 @@
+import { systemApiPermissionBindings } from "@southwind-ai/modules";
 import type {
   ApiPermissionBinding,
   FeatureFlagDefinition,
@@ -15,6 +16,15 @@ import { resourceEvent, routeContext } from "../system/route-helpers.js";
 import type { RouteApp } from "../system/route-types.js";
 import type { WatermarkPolicyRepository } from "./watermark-repository.js";
 
+import {
+  exportWatermark,
+  readWatermarkTransfer,
+  watermarkPreview,
+} from "./watermark-transfer.js";
+
+const YAML_PATH = "/system/settings/watermark/yaml";
+const PREVIEW_PATH = `${YAML_PATH}/preview`;
+
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
 const READ_BINDING = watermarkBinding("GET", "system.watermark.read");
@@ -28,6 +38,80 @@ export function registerWatermarkPolicyRoutes(
 ): void {
   const feature = findFeature(features, "system.watermark");
 
+  const exportBinding = yamlBinding("GET", YAML_PATH);
+  const previewBinding = yamlBinding("POST", PREVIEW_PATH);
+  const importBinding = yamlBinding("POST", YAML_PATH);
+
+  app.get(YAML_PATH, async (rawContext) => {
+    const { guardContext } = routeContext(rawContext);
+    const denied = await guard(runtime, guardContext, exportBinding, feature);
+    if (denied) return denied;
+    const yaml = exportWatermark(await repository.get());
+    return new Response(yaml, {
+      headers: {
+        "Content-Type": "application/yaml; charset=utf-8",
+        "Content-Disposition":
+          'attachment; filename="windy-admin-settings.yaml"',
+        "Cache-Control": "no-store",
+      },
+    });
+  });
+
+  async function transfer(rawContext: unknown, apply: boolean) {
+    const { body, guardContext } = routeContext(rawContext);
+    const denied = await guard(
+      runtime,
+      guardContext,
+      apply ? importBinding : previewBinding,
+      feature,
+    );
+    if (denied) return denied;
+
+    const request = body as { yaml?: unknown; revision?: unknown } | null;
+    const yaml = readWatermarkTransfer(request?.yaml);
+    if (!yaml)
+      return invalidYaml(
+        "文件须为 8 KiB 以内的版本 1 配置，且只能包含支持的字段",
+      );
+
+    const before = await repository.get();
+    const parsed = parseWatermarkPolicy({
+      ...yaml,
+      businessPagesEnabled: yaml.enabled,
+      customContent: before.customContent,
+    });
+    if (!parsed.ok) return invalidYaml(parsed.message);
+
+    const next = { ...parsed.value, customContent: before.customContent };
+    const preview = watermarkPreview(before, next, guardContext.actor.id);
+    if (!apply) return preview;
+    if (request?.revision !== preview.revision) return stalePreview();
+    if (!preview.changes.length) return before;
+
+    const updated = await repository.updateIfCurrent(
+      before,
+      next,
+      guardContext.actor.id,
+    );
+    if (!updated) return stalePreview();
+    await runtime.auditSink.recordCriticalEvent(
+      resourceEvent(
+        guardContext,
+        "config.update",
+        "platform-watermark",
+        "platform",
+        {
+          source: "yaml",
+          changedFields: changedFields(before, updated),
+        },
+      ),
+    );
+    return updated;
+  }
+
+  app.post(PREVIEW_PATH, (context) => transfer(context, false));
+  app.post(YAML_PATH, (context) => transfer(context, true));
+
   app.get("/platform/watermark-policy", () => repository.get());
 
   app.get("/system/settings/watermark", async (rawContext) => {
@@ -67,6 +151,31 @@ export function registerWatermarkPolicyRoutes(
   });
 }
 
+function yamlBinding(method: "GET" | "POST", path: string) {
+  const binding = systemApiPermissionBindings().find(
+    (entry) => entry.method === method && entry.path === `/api${path}`,
+  );
+  if (!binding) throw new Error(`水印 YAML API 未注册：${method} ${path}`);
+  return binding;
+}
+
+function invalidYaml(message: string) {
+  return Response.json(
+    { error: "INVALID_ADMIN_CONFIG_YAML", message },
+    { status: 400 },
+  );
+}
+
+function stalePreview() {
+  return Response.json(
+    {
+      error: "STALE_ADMIN_CONFIG_PREVIEW",
+      message: "配置或文件已变化，请重新预览",
+    },
+    { status: 409 },
+  );
+}
+
 async function guard(
   runtime: ServerRuntime,
   context: ReturnType<typeof routeContext>["guardContext"],

package/template/apps/server/src/settings/watermark-transfer.ts

@@ -0,0 +1,79 @@
+import { createHash } from "node:crypto";
+import type { PlatformWatermarkPolicy } from "@southwind-ai/shared";
+import { parseDocument, stringify, visit } from "yaml";
+
+const fields = [
+  "enabled",
+  "density",
+  "contentFields",
+  "opacityPercent",
+  "fontSize",
+] as const;
+
+export function portableWatermark(policy: PlatformWatermarkPolicy) {
+  return {
+    enabled: policy.enabled,
+    density: policy.density,
+    contentFields: policy.contentFields,
+    opacityPercent: policy.opacityPercent,
+    fontSize: policy.fontSize,
+  };
+}
+
+export function exportWatermark(policy: PlatformWatermarkPolicy) {
+  return stringify({ version: 1, watermark: portableWatermark(policy) });
+}
+
+export function readWatermarkTransfer(input: unknown) {
+  if (typeof input !== "string" || Buffer.byteLength(input) > 8192) return;
+  try {
+    const doc = parseDocument(input, { schema: "core", uniqueKeys: true });
+    if (doc.errors.length || doc.warnings.length) return;
+    let safe = true;
+    visit(doc, {
+      Alias() {
+        safe = false;
+      },
+      Node(_key, node) {
+        if (node.tag || node.anchor) safe = false;
+      },
+    });
+    if (!safe) return;
+    const value: unknown = doc.toJS({ maxAliasCount: 0 });
+    if (!hasFields(value, ["version", "watermark"]) || value.version !== 1)
+      return;
+    if (!hasFields(value.watermark, fields)) return;
+    return value.watermark;
+  } catch {
+    return;
+  }
+}
+
+function hasFields(
+  value: unknown,
+  keys: readonly string[],
+): value is Record<string, unknown> {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === keys.length &&
+    keys.every((key) => Object.hasOwn(value, key))
+  );
+}
+
+export function watermarkPreview(
+  before: PlatformWatermarkPolicy,
+  after: PlatformWatermarkPolicy,
+  actorId: string,
+) {
+  const current = portableWatermark(before);
+  const next = portableWatermark(after);
+  const changes = fields
+    .filter((key) => JSON.stringify(current[key]) !== JSON.stringify(next[key]))
+    .map((key) => ({ key, before: current[key], after: next[key] }));
+  const revision = createHash("sha256")
+    .update(JSON.stringify([actorId, current, next]))
+    .digest("hex");
+  return { changes, revision };
+}

package/template/apps/server/src/speech/facade-validation.ts

@@ -9,7 +9,7 @@ import type { RequestGuardContext } from "../guards.js";
 import {
   governProviderInput,
   ProviderInputGovernanceError,
-} from "../agent/provider-input-governance.js";
+} from "../ai-runtime-security/provider-input-governance.js";
 import { SpeechRuntimeError, type SpeechRuntimePort } from "./contracts.js";
 import { SpeechFacadeError } from "./errors.js";
 import { legacySpeechCapabilities } from "./facade-contract.js";

package/template/apps/server/src/speech/facade.ts

@@ -8,8 +8,8 @@ import type {
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
-import { ExecutionGrantStore } from "../agent/execution-grants.js";
-import { scopedRuntimeIdempotencyKey } from "../agent/idempotency-key.js";
+import { ExecutionGrantStore } from "../ai-runtime-security/execution-grants.js";
+import { scopedRuntimeIdempotencyKey } from "../ai-runtime-security/idempotency-key.js";
 import { auditActor, type RequestGuardContext } from "../guards.js";
 import type { InitializedModuleHosts } from "../module-host.js";
 import { toModuleActor } from "../module-host.js";

package/template/apps/server/src/startup-composition-validation.test.ts

@@ -2,6 +2,38 @@ import { describe, expect, test } from "bun:test";
 import { validateCompositionBeforeStartup } from "./startup-composition-validation.js";
 
 describe("完整 Server Composition 启动前门禁", () => {
+  test("生产启动的真实装配子进程隔离审计存储且不改变父进程环境", () => {
+    const moduleUrl = new URL(
+      "./startup-composition-validation.ts",
+      import.meta.url,
+    );
+    const result = Bun.spawnSync({
+      cmd: [
+        process.execPath,
+        "--eval",
+        `
+        const { validateCompositionBeforeStartup } = await import(${JSON.stringify(moduleUrl.href)});
+        validateCompositionBeforeStartup(["bun", "src/index.ts"]);
+        if (process.env.NODE_ENV !== "production") throw new Error("parent environment changed");
+        if (process.env.DATABASE_URL !== "postgres://unreachable.invalid/validation-must-not-connect")
+          throw new Error("parent database configuration changed");
+      `,
+      ],
+      env: {
+        ...process.env,
+        NODE_ENV: "production",
+        DATABASE_URL:
+          "postgres://unreachable.invalid/validation-must-not-connect",
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    expect(new TextDecoder().decode(result.stderr)).not.toContain(
+      "AuditWriteUnavailableError",
+    );
+    expect(result.exitCode).toBe(0);
+  }, 15000);
+
   test("正常启动先执行无数据库验证子进程", () => {
     let databaseUrlSeen = "not-called";
     validateCompositionBeforeStartup(

package/template/apps/server/src/startup-finalization.ts

@@ -11,6 +11,7 @@ import { installPlatformShutdown } from "./startup-shutdown.js";
 export function finalizePlatformStartup(input: {
   app: Parameters<typeof listenPlatformServer>[0];
   modules: ModuleManifest[];
+  disabledFeatureKeys?: ReadonlySet<string>;
   hosts: InitializedModuleHosts;
   tasks?: readonly { key: string }[];
   tools?: ReadonlyMap<string, unknown>;
@@ -24,6 +25,7 @@ export function finalizePlatformStartup(input: {
 }): void {
   validateInstalledRuntime({
     modules: input.modules,
+    disabledFeatureKeys: input.disabledFeatureKeys,
     routes: input.app.routes,
     tasks: input.tasks ?? [],
     tools: input.tools ?? new Map(),

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

@@ -0,0 +1,77 @@
+import type { bootstrapServerModules } from "./module-bootstrap.js";
+import { createComposedAuthRuntime } from "./auth/composition.js";
+import { createServerRuntime } from "./runtime.js";
+import { createHttpObservability } from "./platform-http-runtime.js";
+import { resolveAiRuntimeConfiguration } from "./system/ai-runtime-configuration.js";
+import { createAuthorizationInvalidationComposition } from "./system/authorization-invalidation-composition.js";
+// @windy-module system.license begin
+import { createLicenseRuntimeActivation } from "./license/activation.js";
+// @windy-module system.license end
+
+type ModuleBootstrap = Awaited<ReturnType<typeof bootstrapServerModules>>;
+interface StartupRuntimeInput {
+  platformConfig: Parameters<typeof bootstrapServerModules>[0];
+  persistence: Parameters<typeof bootstrapServerModules>[1];
+  logger: Parameters<typeof createHttpObservability>[2];
+}
+
+/** Bind runtime policy and audit before constructing services or registering routes. */
+export async function createStartupRuntime(
+  { platformConfig, persistence, logger }: StartupRuntimeInput,
+  {
+    foundationSnapshot,
+    systemRepositories,
+  }: Pick<ModuleBootstrap, "foundationSnapshot" | "systemRepositories">,
+) {
+  const features = foundationSnapshot.features;
+  // @windy-module system.license begin
+  const licenseActivation = createLicenseRuntimeActivation(
+    process.env,
+    foundationSnapshot.platform.licenseEnabled,
+    persistence?.licenseResolver,
+  );
+  // @windy-module system.license end
+  const { aiRuntimeSwitches, disabledAiFeatures } =
+    await resolveAiRuntimeConfiguration(platformConfig.enableAI, features);
+  const runtime = createServerRuntime(process.env, {
+    actorResolver: persistence?.actorResolver,
+    // @windy-module system.license begin
+    licenseResolver: licenseActivation.resolver,
+    licenseEnforced: licenseActivation.enforced,
+    // @windy-module system.license end
+    featureResolver: persistence ? systemRepositories.features : undefined,
+    featureCatalog: features,
+    disabledFeatureKeys: disabledAiFeatures,
+    disabledModuleNames: new Set(foundationSnapshot.disabledModuleNames),
+    // @windy-module system.audit begin
+    auditReader: persistence?.auditReader,
+    auditWriter: persistence?.auditWriter,
+    // @windy-module system.audit end
+  });
+  const observability = createHttpObservability(runtime, persistence, logger);
+  const authorizationInvalidation = createAuthorizationInvalidationComposition({
+    platformConfig,
+    persistence,
+    repositories: systemRepositories,
+  });
+  // @windy-module system.license begin
+  licenseActivation.runtime.setAuditSink(runtime.auditSink);
+  // @windy-module system.license end
+  const auth = createComposedAuthRuntime({
+    repositories: systemRepositories,
+    platformConfig,
+    persistence,
+    runtime,
+  });
+  return {
+    ...auth,
+    runtime,
+    observability,
+    authorizationInvalidation,
+    aiRuntimeSwitches,
+    disabledAiFeatures,
+    // @windy-module system.license begin
+    licenseActivation,
+    // @windy-module system.license end
+  };
+}

package/template/apps/server/src/system/ai-runtime-build.ts

@@ -0,0 +1,3 @@
+import type { AiRuntimeKind } from "@southwind-ai/shared";
+
+export const excludedAiRuntimes: readonly AiRuntimeKind[] = [];

package/template/apps/server/src/system/ai-runtime-configuration.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from "bun:test";
+import {
+  featureKey,
+  parseEnvironmentPolicy,
+  type FeatureFlagDefinition,
+} from "@southwind-ai/shared";
+import { applyAiRuntimePolicy } from "./ai-runtime-configuration.js";
+
+const document: FeatureFlagDefinition = {
+  key: featureKey("system.document"),
+  module: "system.media-runtime",
+  label: "OCR",
+  enabled: true,
+  visible: "visible",
+  stage: "stable",
+};
+const profile = parseEnvironmentPolicy({
+  schemaVersion: 1,
+  build: { modules: ["system.media-runtime"] },
+  runtime: { agent: false, document: true, speech: false, embedding: false },
+  features: [],
+});
+
+test("YAML 显式启用 OCR 时拒绝关闭总开关的冲突配置", () => {
+  expect(() => applyAiRuntimePolicy(false, [document], profile)).toThrow(
+    "PLATFORM_ENABLE_AI_RUNTIME",
+  );
+  const enabled = applyAiRuntimePolicy(true, [document], profile);
+  expect(enabled.aiRuntimeSwitches.document).toBe(true);
+  expect(enabled.disabledAiFeatures.has("system.document")).toBe(false);
+});
+
+test("缺省预设时保留旧总开关行为", () => {
+  const disabled = applyAiRuntimePolicy(false, [document], undefined);
+  expect(disabled.disabledAiFeatures.has("system.document")).toBe(true);
+});

package/template/apps/server/src/system/ai-runtime-configuration.ts

@@ -0,0 +1,58 @@
+import { configureProjectAntivirus } from "../app/antivirus-composition.js";
+import { excludedAiRuntimes } from "./ai-runtime-build.js";
+import {
+  AI_RUNTIME_KINDS,
+  type FeatureFlagDefinition,
+  type EnvironmentPolicy,
+} from "@southwind-ai/shared";
+import { createEnvironmentPolicyReader } from "./environment-policy-reader.js";
+
+export async function resolveAiRuntimeConfiguration(
+  enableAI: boolean,
+  features: readonly FeatureFlagDefinition[],
+) {
+  const environmentPolicy = await createEnvironmentPolicyReader()();
+  if (environmentPolicy.status === "invalid")
+    throw new Error(environmentPolicy.message);
+  const policy =
+    environmentPolicy.status === "available"
+      ? environmentPolicy.policy
+      : undefined;
+  const settings = applyAiRuntimePolicy(enableAI, features, policy);
+  await configureProjectAntivirus(policy?.antivirus);
+  return settings;
+}
+
+export function applyAiRuntimePolicy(
+  enableAI: boolean,
+  features: readonly FeatureFlagDefinition[],
+  policy: EnvironmentPolicy | undefined,
+) {
+  const aiRuntimeSwitches = { ...policy?.runtime };
+  for (const kind of AI_RUNTIME_KINDS) {
+    const omitted =
+      excludedAiRuntimes.includes(kind) ||
+      !features.some(({ key }) => key === `system.${kind}`);
+    if (omitted && aiRuntimeSwitches[kind] === true) {
+      throw new Error(`环境预设启用了未随包交付的运行时：${kind}`);
+    }
+    if (!enableAI && aiRuntimeSwitches[kind] === true) {
+      throw new Error(
+        `环境预设启用了 ${kind}，但 PLATFORM_ENABLE_AI_RUNTIME 已关闭`,
+      );
+    }
+    if (omitted || policy?.build.runtimes?.[kind] === false)
+      aiRuntimeSwitches[kind] = false;
+  }
+  const disabledAiFeatures = new Set(
+    AI_RUNTIME_KINDS.filter(
+      (kind) => !enableAI || aiRuntimeSwitches?.[kind] === false,
+    ).map((kind) => `system.${kind}`),
+  );
+  if (
+    !enableAI ||
+    AI_RUNTIME_KINDS.every((kind) => aiRuntimeSwitches?.[kind] === false)
+  )
+    disabledAiFeatures.add("system.ai-artifact");
+  return { aiRuntimeSwitches, disabledAiFeatures };
+}

package/template/apps/server/src/system/diagnostic-routes.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import {
+  createDiagnosticIndex,
+  diagnosticRecord,
+  newDiagnosticId,
+} from "../observability/diagnostic-index.js";
+import { FakeRouteApp } from "./route-test-app.js";
+import { registerDiagnosticRoutes } from "./diagnostic-routes.js";
+
+describe("diagnostic lookup", () => {
+  test("只允许 diagnostics.read 查询，并为查询留下审计", async () => {
+    const runtime = createServerRuntime({
+      WINDY_DEV_ADMIN_TOKEN: "admin-token",
+    });
+    const index = createDiagnosticIndex();
+    const id = newDiagnosticId();
+    await index.record(
+      diagnosticRecord({
+        diagnosticId: id,
+        requestId: "internal-req",
+        service: "server",
+        stage: "http",
+        method: "GET",
+        route: "/api/resources/:id",
+        statusCode: 500,
+        errorCode: "UNEXPECTED_FAILURE",
+      }),
+    );
+    const app = new FakeRouteApp();
+    registerDiagnosticRoutes(
+      app,
+      runtime,
+      createFoundationSnapshot().features,
+      index,
+    );
+    const route = "/system/diagnostics/:diagnosticId";
+    const anonymous = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/diagnostics/" + id),
+    );
+    const denied = (await app.invoke("GET", route, {
+      guardContext: anonymous,
+      params: { diagnosticId: id },
+      query: {},
+    })) as Response;
+    expect(denied.status).toBe(403);
+    expect(JSON.stringify(await denied.json())).not.toContain("internal-req");
+
+    const admin = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/diagnostics/" + id, {
+        headers: { authorization: "Bearer admin-token" },
+      }),
+    );
+    const found = (await app.invoke("GET", route, {
+      guardContext: admin,
+      params: { diagnosticId: id },
+      query: {},
+    })) as Response;
+    expect(found.status).toBe(200);
+    expect(found.headers.get("cache-control")).toBe("no-store");
+    expect(await found.json()).toMatchObject({
+      requestId: "internal-req",
+      errorCode: "UNEXPECTED_FAILURE",
+    });
+    expect(runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({ action: "diagnostic.read" }),
+    );
+
+    const list = (query: Record<string, string>, guardContext = admin) =>
+      app.invoke("GET", "/system/diagnostics", {
+        guardContext,
+        params: {},
+        query,
+      }) as Promise<Response>;
+    expect((await list({}, anonymous)).status).toBe(403);
+    expect((await list({ pageSize: "0" })).status).toBe(400);
+    const older = diagnosticRecord(
+      {
+        diagnosticId: newDiagnosticId(),
+        requestId: "older",
+        service: "server",
+        stage: "http",
+        method: "GET",
+        route: "/api/resources",
+        statusCode: 503,
+        errorCode: "RUNTIME_UNAVAILABLE",
+      },
+      new Date(Date.now() - 1_000),
+    );
+    await index.record(older);
+    await index.record({
+      ...older,
+      diagnosticId: newDiagnosticId(),
+      expiresAt: older.occurredAt,
+    });
+    const firstPage = await list({ page: "1", pageSize: "1" });
+    expect(firstPage.headers.get("cache-control")).toBe("no-store");
+    expect(await firstPage.json()).toMatchObject({
+      total: 2,
+      items: [{ diagnosticId: id }],
+    });
+    const secondPage = await list({ page: "2", pageSize: "1" });
+    expect(await secondPage.json()).toMatchObject({
+      total: 2,
+      items: [{ requestId: "older" }],
+    });
+    expect(runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "diagnostic.read",
+        metadata: expect.objectContaining({ page: 2, pageSize: 1 }),
+      }),
+    );
+
+    const expired = (await app.invoke("GET", route, {
+      guardContext: admin,
+      params: { diagnosticId: "diag-00000000-0000-7000-8000-000000000000" },
+      query: {},
+    })) as Response;
+    expect(expired.status).toBe(410);
+    expect(await expired.json()).toEqual({ error: "DIAGNOSTIC_EXPIRED" });
+  });
+});