create-windy 0.5.2 → 0.6.1

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;
+}

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

@@ -0,0 +1,297 @@
+import { randomUUIDv7 } from "bun";
+import { createHash } from "node:crypto";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import {
+  ModuleAiArtifactError,
+  type ModuleAiArtifactRef,
+  type ModuleAiScreenshotIntakePortV1,
+} from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { RequestGuardContext } from "../guards.js";
+import { findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { parseScreenshotArtifactRef } from "./screenshot-artifact-ref.js";
+import {
+  screenshotOperationSignal,
+  settleScreenshotOperation,
+} from "./screenshot-intake-deadline.js";
+import {
+  parseScreenshotProducerPlan,
+  safeScreenshotPlanToken,
+} from "./screenshot-intake-plan.js";
+import {
+  ScreenshotIntakePlanStore,
+  type ScreenshotIntakeBinding,
+} from "./screenshot-intake-store.js";
+
+const MAX_PRODUCER_TOKEN_LENGTH = 512;
+const DEFAULT_PRODUCER_TIMEOUT_MS = 5_000;
+const DEFAULT_CLEANUP_TIMEOUT_MS = 500;
+const CLEANUP_CONCURRENCY = 8;
+
+type ServerRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "recordDecisions" | "resolveFeature"
+>;
+
+/** Host adapter for an untrusted project producer. It never exposes producer tokens. */
+export function createGovernedModuleScreenshotIntakePort(input: {
+  readonly moduleName: string;
+  readonly manifest: ModuleManifest;
+  readonly guardContext: RequestGuardContext;
+  readonly signal: AbortSignal;
+  readonly runtime: ServerRuntime;
+  readonly producer: ModuleAiScreenshotIntakePortV1;
+  readonly store: ScreenshotIntakePlanStore;
+  readonly validateArtifact: (
+    reference: ModuleAiArtifactRef,
+  ) => ModuleAiArtifactRef;
+  readonly now?: () => Date;
+  readonly producerTimeoutMs?: number;
+  readonly cleanupTimeoutMs?: number;
+}): ModuleAiScreenshotIntakePortV1 {
+  const now = input.now ?? (() => new Date());
+  const producerTimeoutMs =
+    input.producerTimeoutMs ?? DEFAULT_PRODUCER_TIMEOUT_MS;
+  const cleanupTimeoutMs = input.cleanupTimeoutMs ?? DEFAULT_CLEANUP_TIMEOUT_MS;
+
+  const port: ModuleAiScreenshotIntakePortV1 = {
+    async create({ operationKey, pageId }) {
+      await cleanupExpired();
+      if (!input.store.hasCapacity()) throw unavailable();
+      assertPageId(pageId);
+      await authorize(operationKey);
+      assertActiveSignal(input.signal);
+      const producerPlan = await callProducer(
+        () => input.producer.create({ operationKey, pageId }),
+        screenshotOperationSignal(input.signal, producerTimeoutMs),
+        async (latePlan) => {
+          const producerToken = safeScreenshotPlanToken(latePlan);
+          if (producerToken) await cancelQuietly(producerToken);
+        },
+      );
+      let plan;
+      try {
+        plan = parseScreenshotProducerPlan(producerPlan, now());
+      } catch {
+        const producerToken = safeScreenshotPlanToken(producerPlan);
+        if (producerToken) await cancelQuietly(producerToken);
+        throw unavailable();
+      }
+      try {
+        assertActiveSignal(input.signal);
+        await authorize(operationKey);
+      } catch {
+        await cancelQuietly(plan.intakeToken);
+        throw unavailable();
+      }
+
+      const intakeToken = randomUUIDv7();
+      const added = input.store.add({
+        ...requestBinding(input),
+        hostToken: intakeToken,
+        producerToken: plan.intakeToken,
+        operationKey,
+        expiresAtMs: Date.parse(plan.expiresAt),
+      });
+      if (added !== "added") {
+        if (added === "full") await cancelQuietly(plan.intakeToken);
+        throw unavailable();
+      }
+      return Object.freeze({
+        contractVersion: 1 as const,
+        intakeToken,
+        expiresAt: plan.expiresAt,
+      });
+    },
+    async bind({ intakeToken }) {
+      const record = await claim(intakeToken);
+      const artifact = await callProducer(
+        () => input.producer.bind({ intakeToken: record.producerToken }),
+        screenshotOperationSignal(input.signal, producerTimeoutMs),
+      );
+      const parsed = parseScreenshotArtifactRef(artifact, now());
+      try {
+        return input.validateArtifact(parsed);
+      } catch {
+        throw new ModuleAiArtifactError(
+          "AI_ARTIFACT_INVALID",
+          "Screenshot ArtifactRef 无效",
+        );
+      }
+    },
+    async discard({ intakeToken }) {
+      const record = await claim(intakeToken);
+      await callProducer(
+        () => input.producer.discard({ intakeToken: record.producerToken }),
+        screenshotOperationSignal(input.signal, producerTimeoutMs),
+      );
+    },
+    async cancel({ intakeToken }) {
+      const record = await claim(intakeToken);
+      await callProducer(
+        () => input.producer.cancel({ intakeToken: record.producerToken }),
+        screenshotOperationSignal(input.signal, producerTimeoutMs),
+      );
+    },
+  };
+  return Object.freeze(port);
+
+  async function authorize(
+    operationKey: string,
+  ): Promise<ModuleAiOperationDefinition> {
+    const operation =
+      input.manifest.name === input.moduleName
+        ? input.manifest.aiOperations?.find(
+            (candidate) => candidate.key === operationKey,
+          )
+        : undefined;
+    const feature = operation
+      ? findFeature([...input.manifest.features], operation.featureKey)
+      : undefined;
+    if (!operation || !feature) throw unavailable();
+    try {
+      const guards = await evaluateAccessGuards(
+        input.runtime,
+        input.guardContext,
+        {
+          permission: { permissionKey: operation.permissionKey },
+          feature,
+        },
+      );
+      if (!guards.decision.allowed) throw unavailable();
+      return operation;
+    } catch {
+      throw unavailable();
+    }
+  }
+
+  async function claim(intakeToken: string) {
+    await cleanupExpired();
+    if (!validToken(intakeToken)) throw unavailable();
+    const record = input.store.claim(intakeToken, requestBinding(input));
+    if (!record) throw unavailable();
+    // Store claim is synchronous, so concurrent terminal calls cannot reuse it.
+    if (input.signal.aborted) {
+      await cancelQuietly(record.producerToken);
+      throw unavailable();
+    }
+    try {
+      await authorize(record.operationKey);
+    } catch {
+      await cancelQuietly(record.producerToken);
+      throw unavailable();
+    }
+    if (input.signal.aborted || now().getTime() >= record.expiresAtMs) {
+      await cancelQuietly(record.producerToken);
+      throw unavailable();
+    }
+    return record;
+  }
+
+  async function cancelQuietly(
+    producerToken: string,
+    signal = AbortSignal.timeout(cleanupTimeoutMs),
+  ): Promise<void> {
+    try {
+      await callProducer(
+        () => input.producer.cancel({ intakeToken: producerToken }),
+        signal,
+      );
+    } catch {
+      // Cleanup is best effort; the module still receives one stable error.
+    }
+  }
+
+  async function cleanupExpired(): Promise<void> {
+    const expired = input.store.sweep(now().getTime());
+    if (!expired.length) return;
+    const cleanupSignal = AbortSignal.timeout(cleanupTimeoutMs);
+    let cursor = 0;
+    const worker = async () => {
+      while (!cleanupSignal.aborted) {
+        const record = expired[cursor++];
+        if (!record) return;
+        await cancelQuietly(record.producerToken, cleanupSignal);
+      }
+    };
+    await Promise.allSettled(
+      Array.from(
+        { length: Math.min(CLEANUP_CONCURRENCY, expired.length) },
+        worker,
+      ),
+    );
+  }
+}
+
+function requestBinding(input: {
+  readonly moduleName: string;
+  readonly guardContext: RequestGuardContext;
+}): ScreenshotIntakeBinding {
+  try {
+    const scope = input.guardContext.actor.scopeContext;
+    const scopeJson = JSON.stringify(
+      scope
+        ? {
+            tenantId: scope.tenantId,
+            actorId: scope.actorId,
+            departmentId: scope.departmentId,
+            grants: scope.grants,
+            roleIds: scope.roleIds,
+          }
+        : null,
+    );
+    return {
+      moduleName: input.moduleName,
+      actorId: input.guardContext.actor.id,
+      actorType: input.guardContext.actor.type,
+      scopeHash: createHash("sha256").update(scopeJson).digest("hex"),
+    };
+  } catch {
+    throw unavailable();
+  }
+}
+
+async function callProducer<T>(
+  operation: () => Promise<T>,
+  signal: AbortSignal,
+  onLateValue?: (value: T) => Promise<void> | void,
+): Promise<T> {
+  try {
+    return await settleScreenshotOperation(
+      Promise.resolve().then(operation),
+      signal,
+      onLateValue,
+    );
+  } catch {
+    throw unavailable();
+  }
+}
+
+function assertPageId(pageId: string): void {
+  if (typeof pageId !== "string" || !pageId.trim() || pageId.length > 256)
+    throw unavailable();
+}
+
+function assertActiveSignal(signal: AbortSignal): void {
+  if (signal.aborted) throw unavailable();
+}
+
+function validToken(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_PRODUCER_TOKEN_LENGTH &&
+    value.trim() === value
+  );
+}
+
+function unavailable(): ModuleAiArtifactError {
+  return new ModuleAiArtifactError(
+    "AI_ARTIFACT_UNAVAILABLE",
+    "Screenshot Intake 当前不可用",
+  );
+}