create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/embedding/remote-runtime.ts

@@ -4,6 +4,7 @@ import {
   type EmbeddingRuntimeOperation,
   type EmbeddingRuntimePort,
 } from "./contracts.js";
+import { assertAiRuntimeReadinessPin } from "../ai-runtime-readiness/deployment-pin.js";
 
 export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
   readonly #baseUrl: string;
@@ -32,6 +33,7 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
     idempotencyKey: string,
     signal?: AbortSignal,
   ): Promise<EmbeddingBatchResponse> {
+    await this.assertReadiness(request, signal);
     const response = await this.request("/api/embeddings", {
       method: "POST",
       headers: {
@@ -49,6 +51,60 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
     return this.request("/health/ready", { signal });
   }
 
+  async start(
+    request: EmbeddingRuntimeOperation,
+    idempotencyKey: string,
+    runId: string,
+    signal?: AbortSignal,
+  ) {
+    await this.assertReadiness(request, signal);
+    const response = await this.request("/api/embeddings/runs", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": idempotencyKey,
+        "x-embedding-run-id": runId,
+      },
+      body: JSON.stringify(request),
+      signal,
+    });
+    if (!response.ok) throw await remoteError(response);
+    const body = record(await response.json());
+    if (typeof body.runId !== "string" || !body.runId)
+      throw invalidResponse("Embedding Run 响应无效");
+    return { runId: body.runId };
+  }
+  async events(runId: string, signal?: AbortSignal) {
+    return this.request(
+      `/api/embeddings/runs/${encodeURIComponent(runId)}/events`,
+      { signal },
+    );
+  }
+  async result(runId: string, signal?: AbortSignal) {
+    const response = await this.request(
+      `/api/embeddings/runs/${encodeURIComponent(runId)}/result`,
+      { signal },
+    );
+    if (!response.ok) throw await remoteError(response);
+    return parseResponse(record(await response.json()).output);
+  }
+  async cancel(
+    runId: string,
+    reason: string | undefined,
+    signal?: AbortSignal,
+  ) {
+    const response = await this.request(
+      `/api/embeddings/runs/${encodeURIComponent(runId)}/cancel`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(reason ? { reason } : {}),
+        signal,
+      },
+    );
+    if (!response.ok) throw await remoteError(response);
+  }
+
   private request(path: string, init: RequestInit = {}) {
     const timeout = AbortSignal.timeout(this.#timeoutMs);
     const signal = init.signal
@@ -72,6 +128,24 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
       return response;
     });
   }
+
+  private async assertReadiness(
+    request: EmbeddingRuntimeOperation,
+    signal?: AbortSignal,
+  ) {
+    if (!request.readinessPin) return;
+    try {
+      await assertAiRuntimeReadinessPin(request.readinessPin, () =>
+        this.health(signal),
+      );
+    } catch {
+      throw new EmbeddingRuntimeError(
+        "RUNTIME_UNAVAILABLE",
+        "Embedding Runtime readiness 已漂移",
+        true,
+      );
+    }
+  }
 }
 
 export const unavailableEmbeddingRuntime: EmbeddingRuntimePort = {
@@ -88,6 +162,30 @@ export const unavailableEmbeddingRuntime: EmbeddingRuntimePort = {
       { status: 503 },
     );
   },
+  async start() {
+    throw new EmbeddingRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Embedding Runtime 未安装或未配置",
+      true,
+    );
+  },
+  async events() {
+    return Response.json({ code: "CAPABILITY_UNAVAILABLE" }, { status: 503 });
+  },
+  async result() {
+    throw new EmbeddingRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Embedding Runtime 未安装或未配置",
+      true,
+    );
+  },
+  async cancel() {
+    throw new EmbeddingRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Embedding Runtime 未安装或未配置",
+      true,
+    );
+  },
 };
 
 function parseResponse(value: unknown): EmbeddingBatchResponse {

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

@@ -0,0 +1,118 @@
+import { expect, test } from "bun:test";
+import type { RouteApp } from "../system/route-types.js";
+import type { EmbeddingFacade } from "./facade.js";
+import { EmbeddingFacadeError } from "./error.js";
+import {
+  registerEmbeddingRoutes,
+  registerEmbeddingRunArtifactRoutes,
+} from "./routes.js";
+
+test("Embedding Run 读取与取消在授权拒绝时不触达远端", async () => {
+  const app = new Harness();
+  let remote = 0;
+  registerEmbeddingRoutes(app, {
+    async authorizeRun() {
+      throw new EmbeddingFacadeError(
+        "FORBIDDEN",
+        "Embedding Run 不存在或不可访问",
+        403,
+      );
+    },
+    async remoteResult() {
+      remote += 1;
+      throw new Error("unreachable");
+    },
+    async remoteCancel() {
+      remote += 1;
+      throw new Error("unreachable");
+    },
+  } as unknown as EmbeddingFacade);
+  const context = {
+    params: { runId: "embedding_1" },
+    request: new Request("http://windy/api"),
+    guardContext: {
+      requestId: "request-1",
+      startedAt: "2026-08-06T00:00:00.000Z",
+      actor: {
+        id: "other",
+        type: "user" as const,
+        name: "其他用户",
+        roleCodes: [],
+        permissionKeys: [],
+      },
+    },
+  };
+  for (const key of [
+    "GET /embeddings/runs/:runId/result",
+    "POST /embeddings/runs/:runId/cancel",
+  ]) {
+    const response = await app.call(key, context);
+    expect(response.status).toBe(403);
+    expect(await response.json()).toMatchObject({ code: "FORBIDDEN" });
+  }
+  expect(remote).toBe(0);
+});
+
+test("Run-bound Artifact 仅允许内部 worker 在当前 Server 授权后读取", async () => {
+  const app = new Harness();
+  let opened = 0;
+  registerEmbeddingRunArtifactRoutes(
+    app,
+    {
+      async openRunArtifact(runId: string, itemId: string) {
+        opened += 1;
+        expect({ runId, itemId }).toEqual({
+          runId: "embedding_1",
+          itemId: "image",
+        });
+        return {
+          opened: {
+            body: new ReadableStream({
+              start(controller) {
+                controller.enqueue(new TextEncoder().encode("image"));
+                controller.close();
+              },
+            }),
+            mimeType: "image/png",
+            byteSize: 5,
+            sha256: "a".repeat(64),
+          },
+        };
+      },
+    } as unknown as EmbeddingFacade,
+    "internal-token",
+  );
+  const route = "GET /internal/embeddings/runs/:runId/artifacts/:itemId";
+  const denied = await app.call(route, {
+    params: { runId: "embedding_1", itemId: "image" },
+    request: new Request("http://windy/api"),
+  });
+  expect(denied.status).toBe(403);
+  expect(opened).toBe(0);
+  const accepted = await app.call(route, {
+    params: { runId: "embedding_1", itemId: "image" },
+    request: new Request("http://windy/api", {
+      headers: { authorization: "Bearer internal-token" },
+    }),
+  });
+  expect(accepted.status).toBe(200);
+  expect(accepted.headers.get("cache-control")).toBe("private, no-store");
+  expect(await accepted.text()).toBe("image");
+  expect(opened).toBe(1);
+});
+class Harness implements RouteApp {
+  readonly routes = new Map<string, (value: unknown) => unknown>();
+  get(path: string, handler: (value: unknown) => unknown) {
+    this.routes.set(`GET ${path}`, handler);
+  }
+  post(path: string, handler: (value: unknown) => unknown) {
+    this.routes.set(`POST ${path}`, handler);
+  }
+  put() {}
+  delete() {}
+  async call(key: string, value: unknown) {
+    const route = this.routes.get(key);
+    if (!route) throw new Error("route missing");
+    return (await route(value)) as Response;
+  }
+}

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