create-windy 0.5.2 → 0.6.0

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 当前不可用",
+  );
+}

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

@@ -0,0 +1,311 @@
+import { expect, test } from "bun:test";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiScreenshotIntakePortV1,
+  ModuleAiScreenshotPlanV1,
+} from "@southwind-ai/server-sdk";
+import {
+  screenshotIntakeManifest,
+  screenshotOperationKey as operationKey,
+} from "./screenshot-intake-test-support.js";
+import type { RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { createGovernedModuleScreenshotIntakePort } from "./screenshot-intake-port.js";
+import { ScreenshotIntakePlanStore } from "./screenshot-intake-store.js";
+
+const nowIso = "2026-08-05T00:00:00.000Z";
+const expiresAt = "2026-08-05T00:01:00.000Z";
+const artifactExpiresAt = "2026-08-05T00:02:00.000Z";
+
+test("Screenshot Host store 有界且满载时不创建 producer plan", async () => {
+  const value = harness({ maxEntries: 1 });
+  await value.port.create({ operationKey, pageId: "page-1" });
+  await expect(
+    value.port.create({ operationKey, pageId: "page-2" }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  expect(value.calls.create).toBe(1);
+});
+
+test("Screenshot Host 把 plan Proxy/accessor 异常收敛为稳定错误", async () => {
+  for (const plan of [trappingPlan(), accessorPlan()]) {
+    const value = harness({ plan });
+    const error = await value.port
+      .create({ operationKey, pageId: "page" })
+      .catch((caught: unknown) => caught);
+    expect(error).toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+    expect(String(error)).not.toContain("producer-plan-secret");
+  }
+});
+
+test("Screenshot Host 只快照一次 sequential Proxy plan", async () => {
+  let tokenReads = 0;
+  let expiryReads = 0;
+  const plan = new Proxy(validPlan(), {
+    get(target, key, receiver) {
+      if (key === "intakeToken") {
+        tokenReads += 1;
+        return tokenReads === 1 ? "producer-token" : "x".repeat(600);
+      }
+      if (key === "expiresAt") {
+        expiryReads += 1;
+        return expiryReads <= 3 ? expiresAt : "2036-08-05T00:01:00.000Z";
+      }
+      return Reflect.get(target, key, receiver) as unknown;
+    },
+  });
+  const value = harness({ plan });
+  await expect(
+    value.port.create({ operationKey, pageId: "page" }),
+  ).resolves.toMatchObject({ expiresAt });
+  expect(tokenReads).toBe(0);
+  expect(expiryReads).toBe(0);
+});
+
+test("Screenshot Host 严格校验 producer ArtifactRef DTO", async () => {
+  for (const artifact of [
+    proxyArtifact(),
+    getterArtifact(),
+    extraArtifact(),
+    oversizedTokenArtifact(),
+  ]) {
+    const value = harness({ artifact });
+    const plan = await value.port.create({ operationKey, pageId: "page" });
+    const error = await value.port
+      .bind({ intakeToken: plan.intakeToken })
+      .catch((caught: unknown) => caught);
+    expect(error).toMatchObject({ code: "AI_ARTIFACT_INVALID" });
+    expect(String(error)).not.toContain("artifact-secret");
+  }
+});
+
+test("Screenshot Host 对合法 ArtifactRef 返回冻结的纯 DTO", async () => {
+  const value = harness();
+  const plan = await value.port.create({ operationKey, pageId: "page" });
+  const result = await value.port.bind({ intakeToken: plan.intakeToken });
+  expect(result).toEqual(validArtifact());
+  expect(Object.isFrozen(result)).toBe(true);
+});
+
+test("Screenshot Host 对 create/bind/cancel 强制硬 deadline", async () => {
+  const create = deferred<unknown>();
+  const creating = harness({
+    createOperation: () => create.promise,
+    producerTimeoutMs: 5,
+  });
+  await expect(
+    creating.port.create({ operationKey, pageId: "page" }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  create.resolve(validPlan());
+  await new Promise((resolve) => setTimeout(resolve, 1));
+  expect(creating.calls.cancel).toBe(1);
+
+  const bind = deferred<unknown>();
+  const binding = harness({
+    bindOperation: () => bind.promise,
+    producerTimeoutMs: 5,
+  });
+  const bindPlan = await binding.port.create({ operationKey, pageId: "page" });
+  await expect(
+    binding.port.bind({ intakeToken: bindPlan.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  bind.resolve(validArtifact());
+
+  const cancel = deferred<void>();
+  const cancelling = harness({
+    cancelOperation: () => cancel.promise,
+    producerTimeoutMs: 5,
+  });
+  const cancelPlan = await cancelling.port.create({
+    operationKey,
+    pageId: "page",
+  });
+  await expect(
+    cancelling.port.cancel({ intakeToken: cancelPlan.intakeToken }),
+  ).rejects.toMatchObject({ code: "AI_ARTIFACT_UNAVAILABLE" });
+  cancel.resolve(undefined);
+  await Promise.resolve();
+});
+
+test("Screenshot Host 清理过期 plan 时使用全局硬 deadline", async () => {
+  const current = { value: Date.parse(nowIso) };
+  const cancel = deferred<void>();
+  const value = harness({
+    current,
+    cleanupTimeoutMs: 5,
+    cancelOperation: () => cancel.promise,
+    planFactory: (call) => ({
+      contractVersion: 1,
+      intakeToken: `producer-token-${call}`,
+      expiresAt:
+        call === 1 ? "2026-08-05T00:00:10.000Z" : "2026-08-05T00:00:20.000Z",
+    }),
+  });
+  await value.port.create({ operationKey, pageId: "page-1" });
+  current.value = Date.parse("2026-08-05T00:00:11.000Z");
+  await expect(
+    value.port.create({ operationKey, pageId: "page-2" }),
+  ).resolves.toMatchObject({ contractVersion: 1 });
+  cancel.resolve(undefined);
+  await Promise.resolve();
+});
+
+test("Screenshot Host 对 claims validator 失败也只返回稳定错误", async () => {
+  const value = harness({
+    validateArtifact() {
+      throw new Error("claims-validator-secret");
+    },
+  });
+  const plan = await value.port.create({ operationKey, pageId: "page" });
+  const error = await value.port
+    .bind({ intakeToken: plan.intakeToken })
+    .catch((caught: unknown) => caught);
+  expect(error).toMatchObject({ code: "AI_ARTIFACT_INVALID" });
+  expect(String(error)).not.toContain("claims-validator-secret");
+});
+
+function harness(
+  options: {
+    maxEntries?: number;
+    plan?: unknown;
+    artifact?: unknown;
+    current?: { value: number };
+    planFactory?: (call: number) => unknown;
+    createOperation?: () => Promise<unknown>;
+    bindOperation?: () => Promise<unknown>;
+    cancelOperation?: () => Promise<void>;
+    producerTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+    validateArtifact?: (reference: ModuleAiArtifactRef) => ModuleAiArtifactRef;
+  } = {},
+) {
+  const manifest = screenshotIntakeManifest();
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    { featureCatalog: manifest.features },
+  );
+  const context = guardContext("request-1");
+  const store = new ScreenshotIntakePlanStore(options.maxEntries);
+  const calls = { create: 0, cancel: 0 };
+  const producer: ModuleAiScreenshotIntakePortV1 = {
+    async create() {
+      calls.create += 1;
+      return (
+        options.createOperation
+          ? await options.createOperation()
+          : (options.planFactory?.(calls.create) ?? options.plan ?? validPlan())
+      ) as ModuleAiScreenshotPlanV1;
+    },
+    async bind() {
+      return (
+        options.bindOperation
+          ? await options.bindOperation()
+          : (options.artifact ?? validArtifact())
+      ) as ModuleAiArtifactRef;
+    },
+    async discard() {},
+    async cancel() {
+      calls.cancel += 1;
+      await options.cancelOperation?.();
+    },
+  };
+  return {
+    calls,
+    port: createGovernedModuleScreenshotIntakePort({
+      moduleName: manifest.name,
+      manifest,
+      guardContext: context,
+      signal: new AbortController().signal,
+      runtime,
+      producer,
+      store,
+      validateArtifact: options.validateArtifact ?? ((reference) => reference),
+      now: () => new Date(options.current?.value ?? Date.parse(nowIso)),
+      producerTimeoutMs: options.producerTimeoutMs,
+      cleanupTimeoutMs: options.cleanupTimeoutMs,
+    }),
+  };
+}
+
+function guardContext(requestId: string): RequestGuardContext {
+  return {
+    requestId,
+    actor: {
+      id: "actor-1",
+      type: "user",
+      name: "截图用户",
+      roleCodes: [],
+      permissionKeys: ["evidence.document.ocr.execute"],
+    },
+    startedAt: nowIso,
+    licenseEnforced: false,
+  };
+}
+
+function validPlan(): ModuleAiScreenshotPlanV1 {
+  return { contractVersion: 1, intakeToken: "producer-token", expiresAt };
+}
+
+function trappingPlan(): ModuleAiScreenshotPlanV1 {
+  return new Proxy(validPlan(), {
+    ownKeys() {
+      throw new Error("producer-plan-secret");
+    },
+  });
+}
+
+function accessorPlan(): ModuleAiScreenshotPlanV1 {
+  const value = validPlan();
+  Object.defineProperty(value, "intakeToken", {
+    enumerable: true,
+    get() {
+      throw new Error("producer-plan-secret");
+    },
+  });
+  return value;
+}
+
+function validArtifact(): ModuleAiArtifactRef {
+  return {
+    value: "opaque-artifact-ref",
+    mediaType: "image/png",
+    byteSize: 1,
+    sha256: "a".repeat(64),
+    expiresAt: artifactExpiresAt,
+  };
+}
+
+function proxyArtifact(): ModuleAiArtifactRef {
+  return new Proxy(validArtifact(), {
+    ownKeys() {
+      throw new Error("artifact-secret");
+    },
+  });
+}
+
+function getterArtifact(): ModuleAiArtifactRef {
+  const value = validArtifact() as ModuleAiArtifactRef &
+    Record<string, unknown>;
+  Object.defineProperty(value, "value", {
+    enumerable: true,
+    get() {
+      throw new Error("artifact-secret");
+    },
+  });
+  return value;
+}
+
+function extraArtifact(): ModuleAiArtifactRef {
+  return { ...validArtifact(), dangerous: { secret: true } } as never;
+}
+
+function oversizedTokenArtifact(): ModuleAiArtifactRef {
+  return { ...validArtifact(), value: "x".repeat(4_097) };
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((settle) => {
+    resolve = settle;
+  });
+  return { promise, resolve };
+}

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

@@ -0,0 +1,76 @@
+export interface ScreenshotIntakeBinding {
+  readonly moduleName: string;
+  readonly actorId: string;
+  readonly actorType: string;
+  readonly scopeHash: string;
+}
+
+export interface ScreenshotIntakeRecord extends ScreenshotIntakeBinding {
+  readonly hostToken: string;
+  readonly producerToken: string;
+  readonly operationKey: string;
+  readonly expiresAtMs: number;
+}
+
+type AddResult = "added" | "full" | "duplicate";
+
+/** Host-lifetime bounded store; records contain no GuardContext or request data. */
+export class ScreenshotIntakePlanStore {
+  readonly #records = new Map<string, ScreenshotIntakeRecord>();
+  readonly #producerTokens = new Set<string>();
+
+  constructor(private readonly maxEntries = 1_024) {
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
+      throw new Error("Screenshot Intake store capacity is invalid");
+  }
+
+  sweep(nowMs: number): readonly ScreenshotIntakeRecord[] {
+    const expired: ScreenshotIntakeRecord[] = [];
+    for (const [token, record] of this.#records) {
+      if (record.expiresAtMs > nowMs) continue;
+      this.#records.delete(token);
+      this.#producerTokens.delete(record.producerToken);
+      expired.push(record);
+    }
+    return expired;
+  }
+
+  hasCapacity(): boolean {
+    return this.#records.size < this.maxEntries;
+  }
+
+  add(record: ScreenshotIntakeRecord): AddResult {
+    if (this.#records.size >= this.maxEntries) return "full";
+    if (
+      this.#records.has(record.hostToken) ||
+      this.#producerTokens.has(record.producerToken)
+    )
+      return "duplicate";
+    this.#records.set(record.hostToken, Object.freeze({ ...record }));
+    this.#producerTokens.add(record.producerToken);
+    return "added";
+  }
+
+  claim(
+    hostToken: string,
+    binding: ScreenshotIntakeBinding,
+  ): ScreenshotIntakeRecord | undefined {
+    const record = this.#records.get(hostToken);
+    if (!record || !sameBinding(record, binding)) return;
+    this.#records.delete(hostToken);
+    this.#producerTokens.delete(record.producerToken);
+    return record;
+  }
+}
+
+function sameBinding(
+  record: ScreenshotIntakeRecord,
+  binding: ScreenshotIntakeBinding,
+): boolean {
+  return (
+    record.moduleName === binding.moduleName &&
+    record.actorId === binding.actorId &&
+    record.actorType === binding.actorType &&
+    record.scopeHash === binding.scopeHash
+  );
+}