create-windy 0.5.2 → 0.6.0

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

@@ -5,6 +5,7 @@ import type {
 import type { RequestGuardContext } from "../guards.js";
 import type { RouteApp } from "../system/route-types.js";
 import { EmbeddingFacadeError } from "./error.js";
+import { validInternalToken } from "../agent/run-routes.js";
 import type { EmbeddingFacade } from "./facade.js";
 import type { EmbeddingFacadeItem } from "./input.js";
 
@@ -14,6 +15,38 @@ interface RouteContext {
   readonly guardContext: RequestGuardContext;
 }
 
+export function registerEmbeddingRunArtifactRoutes(
+  app: RouteApp,
+  facade: EmbeddingFacade,
+  internalToken: string,
+) {
+  app.get("/internal/embeddings/runs/:runId/artifacts/:itemId", async (raw) => {
+    const context = raw as RouteContext & {
+      params: { runId: string; itemId: string };
+    };
+    if (!validInternalToken(context.request, internalToken)) {
+      return Response.json({ code: "FORBIDDEN" }, { status: 403 });
+    }
+    try {
+      const { opened } = await facade.openRunArtifact(
+        context.params.runId,
+        context.params.itemId,
+        context.request.signal,
+      );
+      return new Response(opened.body, {
+        headers: {
+          "cache-control": "private, no-store",
+          "content-type": opened.mimeType,
+          "content-length": String(opened.byteSize),
+          "x-content-sha256": opened.sha256,
+        },
+      });
+    } catch {
+      return Response.json({ code: "ARTIFACT_UNAVAILABLE" }, { status: 404 });
+    }
+  });
+}
+
 export function registerEmbeddingRoutes(
   app: RouteApp,
   facade: EmbeddingFacade,
@@ -38,6 +71,71 @@ export function registerEmbeddingRoutes(
       return knownError(error);
     }
   });
+  app.post("/embeddings/runs", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const request = parseRequest(context.body);
+      const key = context.request.headers.get("idempotency-key");
+      if (!key?.trim()) throw invalid("幂等键不能为空");
+      return Response.json(
+        await facade.start(
+          request.operationKey,
+          request.items,
+          request.options,
+          key,
+          context.guardContext,
+          context.request.signal,
+        ),
+        { status: 202 },
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+  app.get("/embeddings/runs/:runId/result", async (raw) => {
+    const context = raw as RouteContext & { params: { runId: string } };
+    try {
+      await facade.authorizeRun(context.params.runId, context.guardContext);
+      return Response.json(
+        await facade.remoteResult(
+          context.params.runId,
+          context.guardContext,
+          context.request.signal,
+        ),
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+  app.get("/embeddings/runs/:runId/events", async (raw) => {
+    const context = raw as RouteContext & { params: { runId: string } };
+    try {
+      return await facade.remoteEvents(
+        context.params.runId,
+        context.guardContext,
+        context.request.signal,
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+  app.post("/embeddings/runs/:runId/cancel", async (raw) => {
+    const context = raw as RouteContext & { params: { runId: string } };
+    try {
+      await facade.authorizeRun(context.params.runId, context.guardContext);
+      await facade.remoteCancel(
+        context.params.runId,
+        context.guardContext,
+        context.request.signal,
+      );
+      return Response.json({
+        runId: context.params.runId,
+        status: "cancelled",
+      });
+    } catch (error) {
+      return knownError(error);
+    }
+  });
 }
 
 function parseRequest(value: unknown): {

package/template/apps/server/src/embedding/run-artifact.ts

@@ -0,0 +1,18 @@
+import type { EmbeddingRunArtifact } from "@southwind-ai/database";
+import type { EmbeddingRuntimeItem } from "./contracts.js";
+import { EmbeddingFacadeError } from "./error.js";
+
+export function runArtifact(
+  item: EmbeddingRuntimeItem,
+): EmbeddingRunArtifact[] {
+  if (!("source" in item)) return [];
+  return [{ itemId: item.id, ...item.source }];
+}
+
+export function unavailableArtifact() {
+  return new EmbeddingFacadeError(
+    "FORBIDDEN",
+    "Embedding Artifact 当前授权已失效",
+    403,
+  );
+}

package/template/apps/server/src/embedding/run-authorization.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from "bun:test";
+import { EmbeddingRunAuthorizations } from "./run-authorization.js";
+import { InMemoryEmbeddingRunBindingRepository } from "./run-binding-repository.js";
+import { buildScopeContext } from "../data-access/context.js";
+
+const scope = (dataScope: "tenant" | "self") =>
+  buildScopeContext("user-1", undefined, [
+    { id: "role", code: "role", dataScope, departmentIds: [] },
+  ]);
+const context = (scopeContext = scope("tenant")) => ({
+  requestId: "req",
+  startedAt: "2026-08-06T00:00:00.000Z",
+  actor: {
+    id: "user-1",
+    type: "user" as const,
+    name: "用户",
+    roleCodes: [],
+    permissionKeys: [],
+    scopeContext,
+  },
+});
+
+describe("EmbeddingRunAuthorizations", () => {
+  test("安全重放相同指纹，拒绝语义或 Scope 漂移", async () => {
+    const store = new EmbeddingRunAuthorizations(
+      new InMemoryEmbeddingRunBindingRepository(),
+      "x".repeat(32),
+    );
+    const first = await store.issue({
+      operationKey: "analysis.embedding",
+      moduleName: "analysis",
+      idempotencyKey: "same",
+      fingerprint: "a".repeat(64),
+      artifactRefs: [],
+      context: context(),
+    });
+    const replay = await store.issue({
+      operationKey: "analysis.embedding",
+      moduleName: "analysis",
+      idempotencyKey: "same",
+      fingerprint: "a".repeat(64),
+      artifactRefs: [],
+      context: context(),
+    });
+    expect(replay.bindingId).toBe(first.bindingId);
+    await expect(
+      store.issue({
+        operationKey: "analysis.embedding",
+        moduleName: "analysis",
+        idempotencyKey: "same",
+        fingerprint: "b".repeat(64),
+        artifactRefs: [],
+        context: context(),
+      }),
+    ).rejects.toThrow();
+    await store.bind(first, "embedding_1");
+    await expect(
+      store.require("embedding_1", context(scope("self"))),
+    ).rejects.toThrow();
+  });
+
+  test("重启后的并发终态审计只有一个 claim", async () => {
+    const repository = new InMemoryEmbeddingRunBindingRepository();
+    const first = new EmbeddingRunAuthorizations(repository, "x".repeat(32));
+    const binding = await first.issue({
+      operationKey: "analysis.embedding",
+      moduleName: "analysis",
+      idempotencyKey: "audit",
+      fingerprint: "a".repeat(64),
+      artifactRefs: [],
+      context: context(),
+    });
+    await first.bind(binding, "embedding_audit");
+    const afterRestart = new EmbeddingRunAuthorizations(
+      repository,
+      "x".repeat(32),
+    );
+    const claims = await Promise.all([
+      first.claimTerminalAudit("embedding_audit"),
+      afterRestart.claimTerminalAudit("embedding_audit"),
+    ]);
+    expect(claims.filter(Boolean)).toHaveLength(1);
+  });
+
+  test("旋转 Artifact token 改变时，稳定 fingerprint 仍允许安全重试", async () => {
+    const store = new EmbeddingRunAuthorizations(
+      new InMemoryEmbeddingRunBindingRepository(),
+      "x".repeat(32),
+    );
+    const issue = (token: string) =>
+      store.issue({
+        operationKey: "analysis.embedding",
+        moduleName: "analysis",
+        idempotencyKey: "rotated-artifact",
+        fingerprint: "a".repeat(64),
+        artifactRefs: [
+          {
+            itemId: "image-1",
+            value: token,
+            mediaType: "image/png",
+            byteSize: 1,
+            sha256: "b".repeat(64),
+          },
+        ],
+        context: context(),
+      });
+    const first = await issue("rotated-token-one");
+    const retry = await issue("rotated-token-two");
+    expect(retry.bindingId).toBe(first.bindingId);
+  });
+
+  test("审计写入抛错时释放 claim，后续可信观察可以重试", async () => {
+    const store = new EmbeddingRunAuthorizations(
+      new InMemoryEmbeddingRunBindingRepository(),
+      "x".repeat(32),
+    );
+    const binding = await store.issue({
+      operationKey: "analysis.embedding",
+      moduleName: "analysis",
+      idempotencyKey: "release-audit",
+      fingerprint: "a".repeat(64),
+      artifactRefs: [],
+      context: context(),
+    });
+    await store.bind(binding, "embedding_release_audit");
+    const claim = await store.claimTerminalAudit("embedding_release_audit");
+    expect(claim).toEqual(expect.any(Number));
+    await store.releaseTerminalAudit("embedding_release_audit", claim!);
+    await expect(
+      store.claimTerminalAudit("embedding_release_audit"),
+    ).resolves.toEqual(expect.any(Number));
+  });
+});

package/template/apps/server/src/embedding/run-authorization.ts

@@ -0,0 +1,91 @@
+import { createHmac } from "node:crypto";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { EmbeddingRunArtifact } from "@southwind-ai/database";
+import type {
+  EmbeddingRunBinding,
+  EmbeddingRunBindingRepository,
+} from "./run-binding-repository.js";
+
+export class EmbeddingRunAuthorizations {
+  constructor(
+    private readonly repository: EmbeddingRunBindingRepository,
+    private readonly secret: string,
+    private readonly now: () => number = Date.now,
+  ) {}
+  async issue(input: {
+    operationKey: string;
+    moduleName: string;
+    idempotencyKey: string;
+    fingerprint: string;
+    artifactRefs: readonly EmbeddingRunArtifact[];
+    context: RequestGuardContext;
+  }) {
+    const now = this.now();
+    await this.repository.prune(now);
+    const scope = captureAuthorizationScope(input.context.actor.scopeContext);
+    const coordinate = [
+      input.context.actor.id,
+      input.operationKey,
+      input.idempotencyKey,
+    ].join("\u0000");
+    const candidate: EmbeddingRunBinding = {
+      bindingId: `embedding_${this.hash(coordinate).slice(0, 40)}`,
+      operationKey: input.operationKey,
+      moduleName: input.moduleName,
+      actorId: input.context.actor.id,
+      idempotencyHash: this.hash(`idempotency\u0000${coordinate}`),
+      fingerprint: input.fingerprint,
+      scopeHash: scope.hash,
+      scopeSnapshot: scope.snapshot,
+      artifactRefs: input.artifactRefs,
+      createdAt: now,
+      expiresAt: now + 7 * 24 * 60 * 60 * 1_000,
+    };
+    const binding = await this.repository.createOrGet(candidate);
+    if (
+      binding.fingerprint !== candidate.fingerprint ||
+      binding.actorId !== candidate.actorId ||
+      binding.scopeHash !== candidate.scopeHash
+    )
+      throw new EmbeddingRunAuthorizationError();
+    return binding;
+  }
+  async bind(binding: EmbeddingRunBinding, runId: string) {
+    const value = await this.repository.bind(binding.bindingId, runId);
+    if (!value) throw new EmbeddingRunAuthorizationError();
+    return value;
+  }
+  async require(runId: string, context: RequestGuardContext) {
+    const binding = await this.repository.find(runId);
+    const scope = captureAuthorizationScope(context.actor.scopeContext);
+    if (
+      !binding ||
+      binding.expiresAt <= this.now() ||
+      binding.actorId !== context.actor.id ||
+      binding.scopeHash !== scope.hash
+    )
+      throw new EmbeddingRunAuthorizationError();
+    return binding;
+  }
+  find(runId: string) {
+    return this.repository.find(runId);
+  }
+  async claimTerminalAudit(runId: string) {
+    const at = this.now();
+    return (await this.repository.claimTerminalAudit(runId, at))
+      ? at
+      : undefined;
+  }
+  releaseTerminalAudit(runId: string, at: number) {
+    return this.repository.releaseTerminalAudit(runId, at);
+  }
+  private hash(value: string) {
+    return createHmac("sha256", this.secret).update(value).digest("hex");
+  }
+}
+export class EmbeddingRunAuthorizationError extends Error {
+  constructor() {
+    super("Embedding Run 不存在或不可访问");
+  }
+}

package/template/apps/server/src/embedding/run-binding-repository.ts

@@ -0,0 +1,75 @@
+import type { AuthorizationScopeSnapshot } from "@southwind-ai/shared";
+import type { EmbeddingRunArtifact } from "@southwind-ai/database";
+
+export interface EmbeddingRunBinding {
+  readonly bindingId: string;
+  readonly runId?: string;
+  readonly operationKey: string;
+  readonly moduleName: string;
+  readonly actorId: string;
+  readonly idempotencyHash: string;
+  readonly fingerprint: string;
+  readonly scopeHash: string;
+  readonly scopeSnapshot: AuthorizationScopeSnapshot;
+  readonly deploymentPin?: Record<string, string | number | boolean>;
+  readonly artifactRefs: readonly EmbeddingRunArtifact[];
+  readonly createdAt: number;
+  readonly expiresAt: number;
+  readonly terminalAuditAt?: number;
+}
+
+export interface EmbeddingRunBindingRepository {
+  createOrGet(value: EmbeddingRunBinding): Promise<EmbeddingRunBinding>;
+  bind(id: string, runId: string): Promise<EmbeddingRunBinding | undefined>;
+  find(runId: string): Promise<EmbeddingRunBinding | undefined>;
+  claimTerminalAudit(runId: string, at: number): Promise<boolean>;
+  releaseTerminalAudit(runId: string, at: number): Promise<void>;
+  prune(now: number): Promise<void>;
+}
+
+export class InMemoryEmbeddingRunBindingRepository implements EmbeddingRunBindingRepository {
+  readonly #values = new Map<string, EmbeddingRunBinding>();
+  async createOrGet(value: EmbeddingRunBinding) {
+    const found = [...this.#values.values()].find(
+      (item) => item.idempotencyHash === value.idempotencyHash,
+    );
+    if (found) return structuredClone(found);
+    this.#values.set(value.bindingId, structuredClone(value));
+    return structuredClone(value);
+  }
+  async bind(id: string, runId: string) {
+    const value = this.#values.get(id);
+    if (!value || (value.runId && value.runId !== runId)) return undefined;
+    const next = { ...value, runId };
+    this.#values.set(id, next);
+    return structuredClone(next);
+  }
+  async find(runId: string) {
+    const found = [...this.#values.values()].find(
+      (item) => item.runId === runId,
+    );
+    return found ? structuredClone(found) : undefined;
+  }
+  async claimTerminalAudit(runId: string, at: number) {
+    const found = [...this.#values.values()].find(
+      (item) => item.runId === runId,
+    );
+    if (!found || found.terminalAuditAt) return false;
+    this.#values.set(found.bindingId, { ...found, terminalAuditAt: at });
+    return true;
+  }
+  async releaseTerminalAudit(runId: string, at: number) {
+    const found = [...this.#values.values()].find(
+      (item) => item.runId === runId,
+    );
+    if (found?.terminalAuditAt === at)
+      this.#values.set(found.bindingId, {
+        ...found,
+        terminalAuditAt: undefined,
+      });
+  }
+  async prune(now: number) {
+    for (const [id, value] of this.#values)
+      if (value.expiresAt <= now) this.#values.delete(id);
+  }
+}

package/template/apps/server/src/embedding/run-fingerprint.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import { embeddingRunFingerprint } from "./run-fingerprint.js";
+
+test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与 options", async () => {
+  const first = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-one",
+          mediaType: "image/png",
+          byteSize: 12,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+  );
+  const retry = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-two",
+          mediaType: "image/png",
+          byteSize: 12,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+  );
+  const changed = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-three",
+          mediaType: "image/png",
+          byteSize: 13,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+  );
+  expect(retry).toBe(first);
+  expect(changed).not.toBe(first);
+});

package/template/apps/server/src/embedding/run-fingerprint.ts

@@ -0,0 +1,39 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { EmbeddingRuntimeItem } from "./contracts.js";
+
+export async function embeddingRunFingerprint(
+  operationKey: string,
+  items: readonly EmbeddingRuntimeItem[],
+  options: ModuleAiJsonValue,
+) {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(
+      stableJson({ operationKey, items: items.map(stableItem), options }),
+    ),
+  );
+  return [...new Uint8Array(digest)]
+    .map((item) => item.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function stableItem(item: EmbeddingRuntimeItem) {
+  if ("text" in item) return { id: item.id, text: item.text };
+  return {
+    id: item.id,
+    mediaType: item.source.mediaType,
+    byteSize: item.source.byteSize,
+    sha256: item.source.sha256,
+  };
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/template/apps/server/src/embedding/terminal-observer.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import { observeEmbeddingTerminal } from "./terminal-observer.js";
+
+test("终态 events 在失败时触发受信审计，不请求结果向量", async () => {
+  const audited: string[] = [];
+  let resultCalls = 0;
+  await observeEmbeddingTerminal({
+    response: new Response(
+      'data: {"type":"run.started"}\n\ndata: {"type":"run.failed"}\n\n',
+    ),
+    binding: { runId: "embedding_1" } as never,
+    context: {} as never,
+    signal: new AbortController().signal,
+    remote: {
+      async result() {
+        resultCalls += 1;
+        throw new Error("failed run must not fetch result");
+      },
+    } as never,
+    async audit(status) {
+      audited.push(status);
+    },
+  });
+  expect(audited).toEqual(["failed"]);
+  expect(resultCalls).toBe(0);
+});

package/template/apps/server/src/embedding/terminal-observer.ts

@@ -0,0 +1,44 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { EmbeddingRuntimePort } from "./contracts.js";
+import type { EmbeddingRunBinding } from "./run-binding-repository.js";
+
+export async function observeEmbeddingTerminal(input: {
+  response: Response;
+  binding: EmbeddingRunBinding;
+  context: RequestGuardContext;
+  signal: AbortSignal;
+  remote: EmbeddingRuntimePort;
+  audit: (
+    status: "completed" | "failed" | "cancelled",
+    result?: Awaited<ReturnType<EmbeddingRuntimePort["result"]>>,
+  ) => Promise<void>;
+}) {
+  try {
+    const terminal = terminalEvent(await input.response.text());
+    if (terminal === "completed") {
+      await input.audit(
+        terminal,
+        await input.remote.result(input.binding.runId!, input.signal),
+      );
+    } else if (terminal) await input.audit(terminal);
+  } catch {
+    // 事件读取或审计不可影响 SSE；下次可信观察会重试未完成的 claim。
+  }
+}
+
+function terminalEvent(
+  value: string,
+): "completed" | "failed" | "cancelled" | undefined {
+  for (const line of value.split("\n")) {
+    if (!line.startsWith("data: ")) continue;
+    try {
+      const event = JSON.parse(line.slice(6)) as { type?: string };
+      if (event.type === "run.completed") return "completed";
+      if (event.type === "run.failed") return "failed";
+      if (event.type === "run.cancelled") return "cancelled";
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}