create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/module-host/scoped-host.ts

@@ -1,8 +1,11 @@
 import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
 import type { ModuleManifest } from "@southwind-ai/modules";
 import {
+  MODULE_REPORT_STAGING_MAX_ENTRIES,
+  MODULE_REPORT_STAGING_MAX_SOURCES,
   requireModuleNamespace,
   type ModuleHost,
+  type ModuleReportStagingPolicyV1,
   type ModuleResourceFileAccessPolicy,
   type ModuleUploadPolicy,
 } from "@southwind-ai/server-sdk";
@@ -31,6 +34,9 @@ export interface HostCollections {
   uploadPolicies: ModuleUploadPolicy[];
   uploadPurposes: Set<string>;
   modulePurposes: Map<string, Set<string>>;
+  reportStagingPolicies: ModuleReportStagingPolicyV1[];
+  reportStagingPurposes: Set<string>;
+  moduleReportStagingPolicies: Map<string, ModuleReportStagingPolicyV1[]>;
   moduleDependencies: ReadonlyMap<string, readonly string[]>;
   resourceFileAccessPolicies: ModuleResourceFileAccessPolicy[];
   moduleResourceFileAccessPolicies: Map<
@@ -69,6 +75,7 @@ export function createScopedHost(
     moduleName,
     registerUploadPolicy(policy) {
       requireModuleNamespace("上传用途", policy.purpose, moduleName);
+      validateFileRetention(policy);
       if (state.uploadPurposes.has(policy.purpose)) {
         throw new Error(`上传用途重复注册：${policy.purpose}`);
       }
@@ -79,6 +86,18 @@ export function createScopedHost(
       purposes.add(policy.purpose);
       state.modulePurposes.set(moduleName, purposes);
     },
+    registerReportStagingPolicy(policy) {
+      requireModuleNamespace("报告暂存用途", policy.purpose, moduleName);
+      validateReportStagingPolicy(policy, moduleName, state);
+      if (state.reportStagingPurposes.has(policy.purpose)) {
+        throw new Error(`报告暂存用途重复注册：${policy.purpose}`);
+      }
+      state.reportStagingPurposes.add(policy.purpose);
+      state.reportStagingPolicies.push(policy);
+      const policies = state.moduleReportStagingPolicies.get(moduleName) ?? [];
+      policies.push(policy);
+      state.moduleReportStagingPolicies.set(moduleName, policies);
+    },
     registerResourceFileAccessPolicies(policies) {
       registerResourceFileAccessPolicies(manifest, state, policies);
     },
@@ -212,3 +231,68 @@ export function createScopedHost(
     },
   };
 }
+
+const MIN_MODULE_FILE_RETENTION_MS = 60_000;
+const MAX_MODULE_FILE_RETENTION_MS = 365 * 24 * 60 * 60_000;
+
+function validateFileRetention(policy: ModuleUploadPolicy): void {
+  if (
+    policy.fileRetentionMs !== undefined &&
+    (!Number.isSafeInteger(policy.fileRetentionMs) ||
+      policy.fileRetentionMs < MIN_MODULE_FILE_RETENTION_MS ||
+      policy.fileRetentionMs > MAX_MODULE_FILE_RETENTION_MS)
+  ) {
+    throw new Error(
+      `模块上传用途文件保留期无效：${policy.purpose}，须为 1 分钟至 365 天`,
+    );
+  }
+}
+
+const REPORT_STAGING_LIMITS = {
+  retentionMs: [60_000, 30 * 24 * 60 * 60_000],
+  claimTtlMs: [30_000, 60 * 60_000],
+  maxReadLeaseMs: [10_000, 60 * 60_000],
+  maxProcessMs: [10_000, 6 * 60 * 60_000],
+  maxSources: [1, MODULE_REPORT_STAGING_MAX_SOURCES],
+  maxArchiveBytes: [1, 16 * 1024 ** 3],
+  maxExpandedBytes: [1, 64 * 1024 ** 3],
+  maxEntryBytes: [1, 4 * 1024 ** 3],
+  maxEntries: [1, MODULE_REPORT_STAGING_MAX_ENTRIES],
+  maxCompressionRatio: [1, 10_000],
+  maxPathDepth: [1, 64],
+} as const;
+
+function validateReportStagingPolicy(
+  policy: ModuleReportStagingPolicyV1,
+  moduleName: string,
+  state: HostCollections,
+): void {
+  if (
+    policy.sourcePurposes.length === 0 ||
+    new Set(policy.sourcePurposes).size !== policy.sourcePurposes.length
+  ) {
+    throw new Error(`报告暂存源用途无效：${policy.purpose}`);
+  }
+  const ownedPurposes = state.modulePurposes.get(moduleName);
+  for (const purpose of policy.sourcePurposes) {
+    if (!ownedPurposes?.has(purpose)) {
+      throw new Error(`报告暂存源用途未由模块 ${moduleName} 注册：${purpose}`);
+    }
+  }
+  for (const [key, [minimum, maximum]] of Object.entries(
+    REPORT_STAGING_LIMITS,
+  )) {
+    const value = policy[key as keyof typeof REPORT_STAGING_LIMITS];
+    if (
+      typeof value !== "number" ||
+      !Number.isSafeInteger(value) ||
+      value < minimum ||
+      value > maximum
+    ) {
+      throw new Error(`报告暂存策略 ${policy.purpose} 的 ${key} 超出宿主上限`);
+    }
+  }
+  if (policy.maxEntryBytes > policy.maxExpandedBytes) {
+    throw new Error(`报告暂存策略 ${policy.purpose} 的字节上限关系无效`);
+  }
+}

package/template/apps/server/src/module-host/screenshot-artifact-ref.ts

@@ -0,0 +1,91 @@
+import {
+  ModuleAiArtifactError,
+  type ModuleAiArtifactRef,
+} from "@southwind-ai/server-sdk";
+
+const artifactKeys = [
+  "byteSize",
+  "expiresAt",
+  "mediaType",
+  "sha256",
+  "value",
+] as const;
+const artifactKeySet = new Set<string>(artifactKeys);
+const mediaTypePattern =
+  /^[a-z0-9][a-z0-9!#$&^_.+-]{0,63}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,63}$/i;
+
+export function parseScreenshotArtifactRef(
+  input: unknown,
+  now: Date,
+): ModuleAiArtifactRef {
+  try {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+      throw new Error();
+    const prototype = Object.getPrototypeOf(input) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) throw new Error();
+    const keys = Reflect.ownKeys(input);
+    if (
+      keys.length !== artifactKeys.length ||
+      keys.some((key) => typeof key !== "string" || !artifactKeySet.has(key))
+    )
+      throw new Error();
+    const value = dataProperty(input, "value");
+    const mediaType = dataProperty(input, "mediaType");
+    const byteSize = dataProperty(input, "byteSize");
+    const sha256 = dataProperty(input, "sha256");
+    const expiresAt = dataProperty(input, "expiresAt");
+    if (
+      typeof value !== "string" ||
+      !value ||
+      value.length > 4_096 ||
+      hasAsciiControl(value) ||
+      /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ||
+      typeof mediaType !== "string" ||
+      !mediaTypePattern.test(mediaType) ||
+      !Number.isSafeInteger(byteSize) ||
+      Number(byteSize) < 1 ||
+      typeof sha256 !== "string" ||
+      !/^[a-f0-9]{64}$/.test(sha256) ||
+      typeof expiresAt !== "string"
+    )
+      throw new Error();
+    const expiry = Date.parse(expiresAt);
+    if (
+      !Number.isFinite(expiry) ||
+      new Date(expiry).toISOString() !== expiresAt ||
+      expiry <= now.getTime()
+    )
+      throw new Error();
+    return Object.freeze({
+      value,
+      mediaType,
+      byteSize: Number(byteSize),
+      sha256,
+      expiresAt,
+    });
+  } catch {
+    throw invalidArtifact();
+  }
+}
+
+function hasAsciiControl(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 31 || code === 127) return true;
+  }
+  return false;
+}
+
+function dataProperty(input: object, key: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(input, key);
+  if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+    throw new Error();
+  return descriptor.value;
+}
+
+function invalidArtifact(): ModuleAiArtifactError {
+  return new ModuleAiArtifactError(
+    "AI_ARTIFACT_INVALID",
+    "Screenshot ArtifactRef 无效",
+  );
+}

package/template/apps/server/src/module-host/screenshot-intake-composition.test.ts

@@ -0,0 +1,292 @@
+import { expect, test } from "bun:test";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiScreenshotIntakePortV1,
+} from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import {
+  screenshotIntakeManifest,
+  screenshotOperationKey as operationKey,
+} from "./screenshot-intake-test-support.js";
+import { buildModuleRequestContext } from "./request-context.js";
+import { createGovernedModuleScreenshotIntakePort } from "./screenshot-intake-port.js";
+import { ScreenshotIntakePlanStore } from "./screenshot-intake-store.js";
+
+const modulePortHasAttach: "attach" extends keyof ModuleAiScreenshotIntakePortV1
+  ? true
+  : false = false;
+
+test("Module Screenshot Port 不暴露 producer attach", () => {
+  expect(modulePortHasAttach).toBe(false);
+  const producerPort = {
+    async create() {
+      return {
+        contractVersion: 1 as const,
+        intakeToken: "intake",
+        expiresAt: "2026-08-05T00:01:00.000Z",
+      };
+    },
+    async attach() {
+      throw new Error("Module 不得调用");
+    },
+    async bind() {
+      throw new Error("测试不调用 bind");
+    },
+    async discard() {},
+    async cancel() {},
+  };
+  const context = buildContext(producerPort);
+  expect(
+    (context.screenshots as unknown as Record<string, unknown>).attach,
+  ).toBeUndefined();
+  expect(Object.isFrozen(context.screenshots)).toBe(true);
+});
+
+test("未配置 project-owned producer 时 Screenshot Intake 失败关闭", async () => {
+  const context = buildContext();
+  expect(context.screenshots).toBeUndefined();
+  expect(Object.hasOwn(context, "screenshots")).toBe(false);
+});
+
+test("Host 在 create 前拒绝非本模块 Operation 与缺少 Permission", async () => {
+  const foreign = fixture();
+  await expect(
+    foreign.port.create({ operationKey: "foreign.image.inspect", pageId: "p" }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(foreign.calls.create).toBe(0);
+
+  const denied = fixture({ permissionKeys: [] });
+  await expect(
+    denied.port.create({ operationKey, pageId: "p" }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(denied.calls.create).toBe(0);
+
+  for (const guarded of [
+    fixture({ featureEnabled: false }),
+    fixture({ licenseRestricted: true }),
+  ]) {
+    await expect(
+      guarded.port.create({ operationKey, pageId: "p" }),
+    ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+    expect(guarded.calls.create).toBe(0);
+  }
+});
+
+test("Host 拒绝超过 60 秒的 producer plan 并 bounded cancel", async () => {
+  const value = fixture({
+    producerExpiresAt: "2026-08-05T00:05:00.000Z",
+  });
+  await expect(
+    value.port.create({ operationKey, pageId: "page-1" }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(value.calls.cancel).toEqual(["producer-token"]);
+});
+
+test("Host 签发独立短时 token，过期后取消 producer plan", async () => {
+  const current = { value: Date.parse("2026-08-05T00:00:00.000Z") };
+  const value = fixture({
+    current,
+    producerExpiresAt: "2026-08-05T00:00:30.000Z",
+  });
+  const plan = await value.port.create({ operationKey, pageId: "page-1" });
+  expect(plan.intakeToken).not.toBe("producer-token");
+  expect(plan.expiresAt).toBe("2026-08-05T00:00:30.000Z");
+
+  current.value = Date.parse(plan.expiresAt);
+  await expect(
+    value.port.bind({ intakeToken: plan.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(value.calls.cancel).toEqual(["producer-token"]);
+  expect(value.calls.bind).toBe(0);
+});
+
+test("Host 对 bind/discard/cancel 共享一次性消费语义", async () => {
+  const value = fixture();
+  const plan = await value.port.create({ operationKey, pageId: "page-1" });
+  await expect(
+    value.port.bind({ intakeToken: plan.intakeToken }),
+  ).resolves.toEqual(artifact);
+  await expect(
+    value.port.bind({ intakeToken: plan.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  await expect(
+    value.port.discard({ intakeToken: plan.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(value.calls.bind).toBe(1);
+
+  const cancelled = await value.port.create({
+    operationKey,
+    pageId: "page-2",
+  });
+  await value.port.cancel({ intakeToken: cancelled.intakeToken });
+  await expect(
+    value.port.bind({ intakeToken: cancelled.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(value.calls.cancel).toEqual(["producer-token"]);
+});
+
+test("Host token 可跨 HTTP Request 使用且不绑定 requestId", async () => {
+  const value = fixture();
+  const plan = await value.port.create({ operationKey, pageId: "page-1" });
+  const nextContext: RequestGuardContext = {
+    ...value.context,
+    requestId: "request-screenshot-next",
+    actor: { ...value.context.actor },
+  };
+  await expect(
+    value.createPort(nextContext).bind({ intakeToken: plan.intakeToken }),
+  ).resolves.toEqual(artifact);
+  expect(value.calls.facades).toBe(2);
+});
+
+test("Host 在终态操作前重新执行 Guard 并绑定 Actor/Scope", async () => {
+  const guardDenied = fixture();
+  const deniedPlan = await guardDenied.port.create({
+    operationKey,
+    pageId: "page-1",
+  });
+  guardDenied.context.actor.permissionKeys.length = 0;
+  await expect(
+    guardDenied.port.bind({ intakeToken: deniedPlan.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(guardDenied.calls.cancel).toEqual(["producer-token"]);
+
+  const actorChanged = fixture();
+  const scopedPlan = await actorChanged.port.create({
+    operationKey,
+    pageId: "page-2",
+  });
+  actorChanged.context.actor.id = "other-actor";
+  await expect(
+    actorChanged.port.bind({ intakeToken: scopedPlan.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(actorChanged.calls.bind).toBe(0);
+});
+
+function buildContext(screenshots?: ModuleAiScreenshotIntakePortV1) {
+  return buildModuleRequestContext({
+    moduleName: "evidence",
+    manifest: screenshotIntakeManifest(),
+    guardContext: {
+      requestId: "request-screenshot",
+      actor: {
+        id: "user-screenshot",
+        type: "user",
+        name: "截图用户",
+        roleCodes: [],
+        permissionKeys: [],
+      },
+      startedAt: "2026-08-05T00:00:00.000Z",
+    },
+    params: {},
+    query: {},
+    runtime: createServerRuntime(),
+    screenshots,
+  });
+}
+
+const artifact: ModuleAiArtifactRef = {
+  value: "artifact-ref",
+  mediaType: "image/png",
+  byteSize: 1,
+  sha256: "a".repeat(64),
+  expiresAt: "2026-08-05T00:02:00.000Z",
+};
+
+function fixture(
+  options: {
+    permissionKeys?: string[];
+    current?: { value: number };
+    producerExpiresAt?: string;
+    featureEnabled?: boolean;
+    licenseRestricted?: boolean;
+  } = {},
+) {
+  const current = options.current ?? {
+    value: Date.parse("2026-08-05T00:00:00.000Z"),
+  };
+  const calls = {
+    create: 0,
+    bind: 0,
+    cancel: [] as string[],
+    facades: 0,
+  };
+  const context: RequestGuardContext = {
+    requestId: "request-screenshot",
+    actor: {
+      id: "actor-1",
+      type: "user",
+      name: "截图用户",
+      roleCodes: [],
+      permissionKeys: options.permissionKeys ?? [
+        "evidence.document.ocr.execute",
+      ],
+    },
+    startedAt: new Date(current.value).toISOString(),
+    ...(options.licenseRestricted
+      ? {
+          licenseEnforced: true,
+          license: { status: "invalid" as const, restricted: true },
+        }
+      : { licenseEnforced: false }),
+  };
+  const producerPort = (): ModuleAiScreenshotIntakePortV1 => {
+    calls.facades += 1;
+    return {
+      async create() {
+        calls.create += 1;
+        return {
+          contractVersion: 1,
+          intakeToken: "producer-token",
+          expiresAt: options.producerExpiresAt ?? "2026-08-05T00:00:30.000Z",
+        };
+      },
+      async bind() {
+        calls.bind += 1;
+        return artifact;
+      },
+      async discard() {},
+      async cancel({ intakeToken }) {
+        calls.cancel.push(intakeToken);
+      },
+    };
+  };
+  const manifest = screenshotIntakeManifest();
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    {
+      featureCatalog: manifest.features,
+      ...(options.featureEnabled === false
+        ? {
+            featureResolver: {
+              resolve: (key: string) => ({
+                key,
+                enabled: false,
+                visible: "hidden" as const,
+              }),
+            },
+          }
+        : {}),
+    },
+  );
+  const store = new ScreenshotIntakePlanStore();
+  const createPort = (guardContext: RequestGuardContext) =>
+    createGovernedModuleScreenshotIntakePort({
+      moduleName: manifest.name,
+      manifest,
+      guardContext,
+      signal: new AbortController().signal,
+      runtime,
+      producer: producerPort(),
+      store,
+      validateArtifact: (reference) => reference,
+      now: () => new Date(current.value),
+    });
+  return {
+    context,
+    calls,
+    createPort,
+    port: createPort(context),
+  };
+}

package/template/apps/server/src/module-host/screenshot-intake-deadline.ts

@@ -0,0 +1,38 @@
+export function screenshotOperationSignal(
+  signal: AbortSignal,
+  timeoutMs: number,
+): AbortSignal {
+  return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+}
+
+/** Hard deadline with handlers left attached to safely consume late settlement. */
+export function settleScreenshotOperation<T>(
+  operation: Promise<T>,
+  signal: AbortSignal,
+  onLateValue?: (value: T) => Promise<void> | void,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const finish = (next: () => void) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", abort);
+      next();
+    };
+    const abort = () => finish(() => reject(new Error("deadline")));
+    operation.then(
+      (value) => {
+        if (settled) {
+          void Promise.resolve()
+            .then(() => onLateValue?.(value))
+            .catch(() => undefined);
+          return;
+        }
+        finish(() => resolve(value));
+      },
+      (error: unknown) => finish(() => reject(error)),
+    );
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+  });
+}

package/template/apps/server/src/module-host/screenshot-intake-plan.ts

@@ -0,0 +1,75 @@
+import type { ModuleAiScreenshotPlanV1 } from "@southwind-ai/server-sdk";
+
+const MAX_PLAN_TTL_MS = 60_000;
+const MAX_PRODUCER_TOKEN_LENGTH = 512;
+const planKeys = ["contractVersion", "expiresAt", "intakeToken"] as const;
+const planKeySet = new Set<string>(planKeys);
+
+export function parseScreenshotProducerPlan(
+  value: unknown,
+  now: Date,
+): ModuleAiScreenshotPlanV1 {
+  try {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error();
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) throw new Error();
+    const keys = Reflect.ownKeys(value);
+    if (
+      keys.length !== planKeys.length ||
+      keys.some((key) => typeof key !== "string" || !planKeySet.has(key))
+    )
+      throw new Error();
+
+    const contractVersion = dataProperty(value, "contractVersion");
+    const expiresAt = dataProperty(value, "expiresAt");
+    const intakeToken = dataProperty(value, "intakeToken");
+    if (
+      contractVersion !== 1 ||
+      typeof expiresAt !== "string" ||
+      !validProducerToken(intakeToken)
+    )
+      throw new Error();
+    const producerExpiry = Date.parse(expiresAt);
+    if (
+      !Number.isFinite(producerExpiry) ||
+      new Date(producerExpiry).toISOString() !== expiresAt ||
+      producerExpiry <= now.getTime() ||
+      producerExpiry - now.getTime() > MAX_PLAN_TTL_MS
+    )
+      throw new Error();
+    return Object.freeze({ contractVersion: 1, intakeToken, expiresAt });
+  } catch {
+    throw new Error("invalid screenshot plan");
+  }
+}
+
+export function safeScreenshotPlanToken(value: unknown): string | undefined {
+  try {
+    if (!value || typeof value !== "object") return;
+    const descriptor = Object.getOwnPropertyDescriptor(value, "intakeToken");
+    return descriptor &&
+      "value" in descriptor &&
+      validProducerToken(descriptor.value)
+      ? descriptor.value
+      : undefined;
+  } catch {
+    return;
+  }
+}
+
+function validProducerToken(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_PRODUCER_TOKEN_LENGTH &&
+    value.trim() === value
+  );
+}
+
+function dataProperty(input: object, key: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(input, key);
+  if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+    throw new Error();
+  return descriptor.value;
+}