create-windy 0.6.11 → 0.6.14

package/template/apps/server/src/agent/client-session/service.test-support.ts

@@ -0,0 +1,226 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ClientAgentProviderPort,
+  ClientSessionAdmissionPort,
+  ClientSessionAuditPort,
+  ClientSessionCaller,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { digestJson } from "./digest.js";
+import { ClientAgentSessionError } from "./errors.js";
+import { InMemoryClientSessionRepository } from "./repository.js";
+import { GovernedClientAgentSessionService } from "./service.js";
+
+export const binding = `sha256:${"b".repeat(64)}` as const;
+export const hostSession = `sha256:${"e".repeat(64)}` as const;
+const deployment = `sha256:${"d".repeat(64)}` as const;
+
+export async function createFixture(
+  options: {
+    now?: number;
+    maxTtlMs?: number;
+    maxSteps?: number;
+    projectProviderResult?: boolean;
+    execute?: (
+      request: ModuleAiJsonValue,
+      signal: AbortSignal,
+    ) => Promise<ModuleAiJsonValue>;
+    providerReady?: boolean;
+  } = {},
+) {
+  const clock = { value: options.now ?? 1_000 };
+  const repository = new InMemoryClientSessionRepository();
+  const admission = new FakeAdmission(
+    options.maxSteps ?? 4,
+    options.projectProviderResult ?? true,
+  );
+  const provider = new FakeProvider(
+    options.execute,
+    options.providerReady ?? true,
+  );
+  const audits: Parameters<ClientSessionAuditPort["record"]>[0][] = [];
+  const service = new GovernedClientAgentSessionService(
+    repository,
+    admission,
+    provider,
+    {
+      record: (event) => {
+        audits.push(event);
+      },
+    },
+    "https://windy.example/api/agent/client-sessions/",
+    () => clock.value,
+    options.maxTtlMs,
+  );
+  const grant = await service.create({
+    operationKey: "support.answer",
+    input: { question: "hello" },
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+    actorId: "actor-1",
+  });
+  const caller: ClientSessionCaller = {
+    token: grant.accessToken,
+    actorId: "actor-1",
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+  };
+  return {
+    service,
+    repository,
+    admission,
+    provider,
+    audits,
+    grant,
+    caller,
+    clock,
+    complete: (body: unknown) =>
+      service.complete(grant.sessionId, body, caller),
+  };
+}
+
+class FakeAdmission implements ClientSessionAdmissionPort {
+  allowed = true;
+  constructor(
+    private readonly maxSteps: number,
+    private readonly project: boolean,
+  ) {}
+  async admit(input: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    clientBindingDigest: `sha256:${string}`;
+    actorId: string;
+  }) {
+    return {
+      actorId: input.actorId,
+      operationKey: input.operationKey,
+      releaseId: "release-1",
+      inputCommitment: digestJson(input.input),
+      authorizationDigest: digestJson({ actorId: input.actorId }),
+      clientBindingDigest: input.clientBindingDigest,
+      deploymentKey: "ai.openai-compatible",
+      providerDataPolicy: {
+        inputFields: [
+          {
+            jsonPointer: "/question",
+            classification: "internal" as const,
+            dlpAction: "redact" as const,
+          },
+        ],
+        envelopeFields: [
+          "instructions",
+          "user-prompt",
+          "tool-definitions",
+          "provider-output",
+          "tool-results",
+        ].map((field) => ({
+          field: field as "instructions",
+          classification: "internal" as const,
+          dlpAction: "redact" as const,
+        })),
+      },
+      limits: {
+        mode: "governed-session" as const,
+        maxSteps: this.maxSteps,
+        maxRequestBytes: 16_384,
+        maxResponseBytes: 16_384,
+        maxConcurrentRequests: 1,
+        maxDurationSeconds: 60,
+      },
+    };
+  }
+  async reauthorize(_session: ClientSessionRecord, _actorId: string) {
+    return this.allowed;
+  }
+  validateResult(_operationKey: string, result: ModuleAiJsonValue) {
+    if (
+      !result ||
+      typeof result !== "object" ||
+      Array.isArray(result) ||
+      typeof result.answer !== "string"
+    ) {
+      throw new ClientAgentSessionError(
+        "INVALID_INPUT",
+        "result schema invalid",
+        400,
+      );
+    }
+  }
+  projectProviderResult(_operationKey: string, response: ModuleAiJsonValue) {
+    if (
+      !this.project ||
+      !response ||
+      typeof response !== "object" ||
+      Array.isArray(response)
+    ) {
+      return undefined;
+    }
+    return { answer: "provider answer" };
+  }
+}
+
+class FakeProvider implements ClientAgentProviderPort {
+  readonly modelAlias = "windy-default";
+  readonly requests: ModuleAiJsonValue[] = [];
+  constructor(
+    private readonly handler:
+      | ((
+          request: ModuleAiJsonValue,
+          signal: AbortSignal,
+        ) => Promise<ModuleAiJsonValue>)
+      | undefined,
+    private readonly available: boolean,
+  ) {}
+  async ready() {
+    return this.available;
+  }
+  async *stream(
+    request: ModuleAiJsonValue,
+    _context: Parameters<ClientAgentProviderPort["stream"]>[1],
+    signal: AbortSignal,
+  ) {
+    this.requests.push(request);
+    const response =
+      (await this.handler?.(request, signal)) ?? providerResponse();
+    yield { type: "meta" as const, deploymentDigest: deployment };
+    yield { type: "chunk" as const, value: responseChunk(response) };
+  }
+}
+
+function responseChunk(response: ModuleAiJsonValue): ModuleAiJsonValue {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    throw new Error("fake response invalid");
+  }
+  const choice = Array.isArray(response.choices)
+    ? response.choices[0]
+    : undefined;
+  const message =
+    choice && typeof choice === "object" && !Array.isArray(choice)
+      ? choice.message
+      : undefined;
+  return {
+    choices: [
+      {
+        index: 0,
+        delta:
+          message && typeof message === "object" && !Array.isArray(message)
+            ? message
+            : {},
+        finish_reason: "stop",
+      },
+    ],
+  };
+}
+
+export function validCompletion() {
+  return {
+    model: "windy-default",
+    messages: [{ role: "user", content: "hello" }],
+  };
+}
+
+export function providerResponse(): ModuleAiJsonValue {
+  return {
+    choices: [{ message: { role: "assistant", content: "provider answer" } }],
+  };
+}

package/template/apps/server/src/agent/client-session/service.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import {
+  binding,
+  createFixture,
+  providerResponse,
+  validCompletion,
+} from "./service.test-support.js";
+
+const deployment = `sha256:${"d".repeat(64)}` as const;
+
+describe("Governed Client Agent Session", () => {
+  test("Provider 未就绪时不签发 capability 或单 Run token", async () => {
+    await expect(createFixture({ providerReady: false })).rejects.toMatchObject(
+      {
+        code: "PROVIDER_FAILED",
+      },
+    );
+  });
+
+  test("只存 token hash，并拒绝跨 Actor、Run 或 binding 重放", async () => {
+    const fixture = await createFixture();
+    const persisted = await fixture.repository.find(fixture.grant.sessionId);
+    expect(JSON.stringify(persisted)).not.toContain(fixture.grant.accessToken);
+
+    await expect(
+      fixture.service.status(fixture.grant.sessionId, {
+        ...fixture.caller,
+        actorId: "actor-2",
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await expect(
+      fixture.service.status("cas_other", fixture.caller),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await expect(
+      fixture.service.status(fixture.grant.sessionId, {
+        ...fixture.caller,
+        clientBindingDigest: `sha256:${"c".repeat(64)}`,
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await expect(
+      fixture.service.status(fixture.grant.sessionId, {
+        ...fixture.caller,
+        hostSessionDigest: `sha256:${"x".repeat(64)}`,
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+  });
+
+  test("固定 model，拒绝 URL/endpoint 覆盖并执行 envelope DLP", async () => {
+    const fixture = await createFixture();
+    await expect(
+      fixture.complete({ model: "attacker", messages: messages("hello") }),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+    await expect(
+      fixture.complete({
+        model: "windy-default",
+        messages: messages("hello"),
+        url: "https://evil.example/v1",
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+
+    await fixture.complete({
+      model: "windy-default",
+      messages: messages("联系 test@example.com"),
+    });
+    expect(JSON.stringify(fixture.provider.requests[0])).toContain(
+      "[REDACTED]",
+    );
+    expect(JSON.stringify(fixture.provider.requests[0])).not.toContain(
+      "test@example.com",
+    );
+  });
+
+  test("成功 attempt 生成 opaque receipt，finalize 优先使用 Provider 投影且幂等", async () => {
+    const fixture = await createFixture();
+    const completion = await fixture.complete(validCompletion());
+    expect(completion.receipt).toMatchObject({
+      clientRunId: fixture.grant.clientRunId,
+      attempt: 1,
+      deploymentDigest: deployment,
+    });
+    expect(JSON.stringify(completion.receipt)).not.toContain("provider answer");
+
+    const first = await fixture.service.finalize(
+      fixture.grant.sessionId,
+      fixture.caller,
+      [completion.receipt.receiptId],
+      { answer: "伪造客户端结果" },
+    );
+    expect(first.result).toMatchObject({
+      result: { answer: "provider answer" },
+      attestation: {
+        source: "provider-observed",
+        providerAttested: true,
+        clientProjected: false,
+      },
+    });
+    await expect(
+      fixture.service.finalize(
+        fixture.grant.sessionId,
+        fixture.caller,
+        [completion.receipt.receiptId],
+        { answer: "伪造客户端结果" },
+      ),
+    ).resolves.toEqual(first);
+    await expect(
+      fixture.service.finalize(
+        fixture.grant.sessionId,
+        fixture.caller,
+        [completion.receipt.receiptId],
+        { answer: "改写" },
+      ),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+  });
+
+  test("没有可用 Provider 投影时明确标记 clientProjected", async () => {
+    const fixture = await createFixture({ projectProviderResult: false });
+    const completion = await fixture.complete(validCompletion());
+    const finalized = await fixture.service.finalize(
+      fixture.grant.sessionId,
+      fixture.caller,
+      [completion.receipt.receiptId],
+      { answer: "client answer" },
+    );
+    expect(finalized.result).toMatchObject({
+      attestation: {
+        source: "client-projected",
+        providerAttested: false,
+        clientProjected: true,
+      },
+    });
+    expect(JSON.stringify(finalized)).not.toContain("runtimeVerified");
+  });
+
+  test("并发重复 finalize 收敛为同一个终态结果", async () => {
+    const fixture = await createFixture();
+    const completion = await fixture.complete(validCompletion());
+    const finalize = () =>
+      fixture.service.finalize(
+        fixture.grant.sessionId,
+        fixture.caller,
+        [completion.receipt.receiptId],
+        { answer: "same" },
+      );
+    const [left, right] = await Promise.all([finalize(), finalize()]);
+    expect(left).toEqual(right);
+    expect(left.status).toBe("completed");
+  });
+
+  test("取消会中止在途请求，迟到响应不能产生 receipt 或新状态", async () => {
+    let release!: (value: ModuleAiJsonValue) => void;
+    const fixture = await createFixture({
+      execute: (_request, signal) =>
+        new Promise((resolve) => {
+          release = resolve;
+          signal.addEventListener("abort", () => undefined);
+        }),
+    });
+    const pending = fixture.complete(validCompletion());
+    await tick();
+    const cancelled = await fixture.service.cancel(
+      fixture.grant.sessionId,
+      fixture.caller,
+      "user stopped",
+    );
+    expect(cancelled.status).toBe("cancelled");
+    release(providerResponse());
+    await expect(pending).rejects.toMatchObject({ code: "CONFLICT" });
+    const persisted = await fixture.repository.find(fixture.grant.sessionId);
+    expect(persisted?.receipts).toHaveLength(0);
+    expect(persisted?.status).toBe("cancelled");
+  });
+
+  test("权限漂移、TTL 和显式 revoke 都即时关闭会话", async () => {
+    const drift = await createFixture();
+    drift.admission.allowed = false;
+    await expect(drift.complete(validCompletion())).rejects.toMatchObject({
+      code: "NOT_FOUND",
+    });
+    expect((await drift.repository.find(drift.grant.sessionId))?.status).toBe(
+      "revoked",
+    );
+
+    const expired = await createFixture({ now: 10_000, maxTtlMs: 1 });
+    expired.clock.value = 10_002;
+    await expect(expired.complete(validCompletion())).rejects.toMatchObject({
+      code: "NOT_FOUND",
+    });
+    expect(
+      (await expired.repository.find(expired.grant.sessionId))?.status,
+    ).toBe("expired");
+
+    const revoked = await createFixture();
+    expect(await revoked.service.revokeBinding(binding, "actor-1")).toBe(1);
+    await expect(revoked.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+
+    const installation = await createFixture();
+    expect(
+      await installation.service.revokeHostSession(
+        installation.caller.hostSessionDigest,
+        "actor-1",
+      ),
+    ).toBe(1);
+    expect(
+      (await installation.repository.find(installation.grant.sessionId))
+        ?.status,
+    ).toBe("revoked");
+  });
+
+  test("在途流式调用按当前权限漂移自动撤销", async () => {
+    const fixture = await createFixture({
+      execute: (_request, signal) =>
+        new Promise((_resolve, reject) => {
+          signal.addEventListener("abort", () => reject(new Error("aborted")));
+        }),
+    });
+    const pending = fixture.complete(validCompletion());
+    const settled = pending.then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+    await tick();
+    fixture.admission.allowed = false;
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(await settled).toMatchObject({ code: "PROVIDER_FAILED" });
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("强制并发/step 上限，Provider 失败不生成 receipt", async () => {
+    let release!: (value: ModuleAiJsonValue) => void;
+    const fixture = await createFixture({
+      maxSteps: 1,
+      execute: () => new Promise((resolve) => (release = resolve)),
+    });
+    const pending = fixture.complete(validCompletion());
+    await tick();
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    release(providerResponse());
+    await pending;
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+
+    const failed = await createFixture({
+      execute: () => Promise.reject(new Error("secret provider detail")),
+    });
+    await expect(failed.complete(validCompletion())).rejects.toMatchObject({
+      code: "PROVIDER_FAILED",
+      message: "Provider 调用失败",
+    });
+    expect(
+      (await failed.repository.find(failed.grant.sessionId))?.receipts,
+    ).toHaveLength(0);
+  });
+});
+
+function messages(content: string) {
+  return [{ role: "user", content }];
+}
+function tick() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}