create-windy 0.6.14 → 0.6.15

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

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "bun:test";
+import { createFixture, validCompletion } from "./service.test-support.js";
+import { consumeClientAgentCompletion } from "./completion.js";
+
+describe("Client Session Provider attempt authority", () => {
+  test("普通 Session 经 Host checker 明确分类后保持原 completion 行为", async () => {
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          return "ordinary";
+        },
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).resolves.toBeDefined();
+    expect(fixture.provider.requests).toHaveLength(1);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("active");
+  });
+
+  test("每个 Workflow Session attempt 出网前复核，漂移先撤销且不调用 Provider", async () => {
+    let decision = "current" as "current" | "revoked";
+    let checks = 0;
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check(facts) {
+          checks += 1;
+          expect(facts).toMatchObject({
+            actorId: "actor-1",
+            operationKey: "support.answer",
+          });
+          return decision;
+        },
+      },
+    });
+
+    await fixture.complete(validCompletion());
+    decision = "revoked";
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+
+    expect(checks).toBe(4);
+    expect(fixture.provider.requests).toHaveLength(1);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("reserve 后 authority 漂移仍在真正 Provider 出网紧前阻断", async () => {
+    let checks = 0;
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          checks += 1;
+          return checks === 1 ? "current" : "revoked";
+        },
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(checks).toBe(2);
+    expect(fixture.provider.requests).toHaveLength(0);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("reserve 后当前授权漂移也在真正 Provider 出网紧前阻断", async () => {
+    let revokeCurrentAuthorization: () => void = () => undefined;
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          revokeCurrentAuthorization();
+          return "current";
+        },
+      },
+    });
+    revokeCurrentAuthorization = () => {
+      fixture.admission.allowed = false;
+    };
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(fixture.provider.requests).toHaveLength(0);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("reserve 后 Session 被 takeover 撤销时，generator 不得开始 Provider", async () => {
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          return "current";
+        },
+      },
+    });
+    const completion = await fixture.service.startCompletion(
+      fixture.grant.sessionId,
+      validCompletion(),
+      fixture.caller,
+    );
+    await fixture.repository.transition(
+      fixture.grant.sessionId,
+      "active",
+      "revoked",
+    );
+
+    await expect(
+      consumeClientAgentCompletion(completion.events),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+    expect(fixture.provider.requests).toHaveLength(0);
+  });
+
+  test("Provider 返回后 fence 漂移时不提交迟到 receipt", async () => {
+    let decision = "current" as "current" | "revoked";
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          return decision;
+        },
+      },
+      execute: async () => {
+        decision = "revoked";
+        return {
+          choices: [{ message: { role: "assistant", content: "late" } }],
+        };
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.receipts,
+    ).toHaveLength(0);
+    expect(fixture.provider.requests).toHaveLength(1);
+  });
+
+  test("authority checker 异常同样 fail closed 且不产生 Provider attempt", async () => {
+    const fixture = await createFixture({
+      attemptAuthority: {
+        async check() {
+          throw new Error("database unavailable");
+        },
+      },
+    });
+
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    expect(fixture.provider.requests).toHaveLength(0);
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+});

package/template/apps/server/src/agent/client-session/attempt-authority.ts

@@ -0,0 +1,191 @@
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
+  ClientSessionAttemptAuthorityDecision,
+  ClientSessionRecord,
+} from "./contracts.js";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { clientSessionConflict } from "./errors.js";
+import type { ClientSessionRepository } from "./repository.js";
+
+export type ClientSessionAttemptRevocationCause =
+  | "authorization-drift"
+  | "authorization-check-failed"
+  | "ttl"
+  | "workflow-authority"
+  | "workflow-authority-check-failed";
+
+export interface ClientSessionAttemptAuthorityHostChecker extends ClientSessionAttemptAuthorityChecker {
+  checkTransaction?(
+    transaction: NodePgDatabase,
+    facts: Parameters<ClientSessionAttemptAuthorityChecker["check"]>[0],
+    now: number,
+  ): Promise<ClientSessionAttemptAuthorityDecision>;
+}
+
+/** 启动时先创建 binding，Workflow runtime 完成装配后再绑定唯一 Host checker。 */
+export class ClientSessionAttemptAuthorityBinding implements ClientSessionAttemptAuthorityChecker {
+  #checker?: ClientSessionAttemptAuthorityHostChecker;
+
+  bind(checker: ClientSessionAttemptAuthorityHostChecker): () => void {
+    if (this.#checker) {
+      throw new Error("Client Session attempt authority checker 重复绑定");
+    }
+    this.#checker = checker;
+    return () => {
+      if (this.#checker === checker) this.#checker = undefined;
+    };
+  }
+
+  check(
+    facts: Parameters<ClientSessionAttemptAuthorityChecker["check"]>[0],
+    signal?: AbortSignal,
+  ): Promise<ClientSessionAttemptAuthorityDecision> {
+    return this.#checker?.check(facts, signal) ?? Promise.resolve("ordinary");
+  }
+
+  checkTransaction(
+    transaction: NodePgDatabase,
+    facts: Parameters<ClientSessionAttemptAuthorityChecker["check"]>[0],
+    now: number,
+  ) {
+    return this.#checker?.checkTransaction
+      ? this.#checker.checkTransaction(transaction, facts, now)
+      : (this.#checker?.check(facts) ?? Promise.resolve("ordinary" as const));
+  }
+}
+
+export async function enforceClientSessionAttemptAuthority(input: {
+  checker: ClientSessionAttemptAuthorityChecker;
+  record: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  signal?: AbortSignal;
+  workflowOwned: boolean;
+  audit(
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ): Promise<void> | void;
+}): Promise<boolean> {
+  let decision: ClientSessionAttemptAuthorityDecision;
+  try {
+    decision = await input.checker.check(
+      clientSessionAttemptAuthorityFacts(input.record),
+      input.signal,
+    );
+  } catch {
+    await revoke(input, "workflow-authority-check-failed");
+    throw clientSessionConflict("Client Agent 会话 authority 校验失败");
+  }
+  if (decision === "current") return true;
+  if (decision === "ordinary" && !input.workflowOwned) return false;
+  await revoke(input, "workflow-authority");
+  throw clientSessionConflict("Client Agent 会话 authority 已失效");
+}
+
+export async function enforceClientSessionCurrentAuthorization(input: {
+  admission: ClientSessionAdmissionPort;
+  record: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  attempt?: number;
+  now: number;
+  audit(
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ): Promise<void> | void;
+}) {
+  const canonical = await input.repository.find(input.record.sessionId);
+  if (!canonical || canonical.status !== "active") {
+    throw clientSessionConflict("Client Agent 会话已关闭");
+  }
+  if (
+    input.attempt !== undefined &&
+    !canonical.pendingAttempts.includes(input.attempt)
+  ) {
+    await revokeCurrentAuthorization(input, canonical);
+    throw clientSessionConflict("Client Agent attempt 已失效");
+  }
+  let cause: ClientSessionAttemptRevocationCause | undefined;
+  if (canonical.expiresAt <= input.now) {
+    cause = "ttl";
+  } else {
+    try {
+      cause = (await input.admission.reauthorize(canonical, canonical.actorId))
+        ? undefined
+        : "authorization-drift";
+    } catch {
+      cause = "authorization-check-failed";
+    }
+  }
+  if (!cause) return;
+  const status = cause === "ttl" ? "expired" : "revoked";
+  const closed = await input.repository.transition(
+    canonical.sessionId,
+    "active",
+    status,
+  );
+  if (closed) await input.audit(closed, cause);
+  throw clientSessionConflict("Client Agent 会话当前授权已失效");
+}
+
+export async function enforceClientSessionProviderBoundary(input: {
+  admission: ClientSessionAdmissionPort;
+  checker: ClientSessionAttemptAuthorityChecker;
+  record: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  attempt?: number;
+  now: number;
+  signal?: AbortSignal;
+  workflowOwned: boolean;
+  audit(
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ): Promise<void> | void;
+}) {
+  await enforceClientSessionCurrentAuthorization(input);
+  if (!input.workflowOwned) return;
+  await enforceClientSessionAttemptAuthority({
+    checker: input.checker,
+    record: input.record,
+    repository: input.repository,
+    ...(input.signal ? { signal: input.signal } : {}),
+    workflowOwned: true,
+    audit: input.audit,
+  });
+}
+
+async function revokeCurrentAuthorization(
+  input: Parameters<typeof enforceClientSessionCurrentAuthorization>[0],
+  canonical: ClientSessionRecord,
+) {
+  const revoked = await input.repository.transition(
+    canonical.sessionId,
+    "active",
+    "revoked",
+  );
+  if (revoked) await input.audit(revoked, "authorization-check-failed");
+}
+
+export function clientSessionAttemptAuthorityFacts(
+  record: ClientSessionRecord,
+) {
+  return {
+    sessionId: record.sessionId,
+    clientRunId: record.clientRunId,
+    actorId: record.actorId,
+    operationKey: record.operationKey,
+    clientBindingDigest: record.clientBindingDigest,
+    hostSessionDigest: record.hostSessionDigest,
+  };
+}
+
+async function revoke(
+  input: Parameters<typeof enforceClientSessionAttemptAuthority>[0],
+  cause: ClientSessionAttemptRevocationCause,
+) {
+  const revoked = await input.repository.transition(
+    input.record.sessionId,
+    "active",
+    "revoked",
+  );
+  if (revoked) await input.audit(revoked, cause);
+}

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

@@ -21,6 +21,7 @@ import {
   createClientAgentHostAuthRouteApp,
   hostSessionDigest,
 } from "./host-auth.js";
+import { ClientSessionAttemptAuthorityBinding } from "./attempt-authority.js";
 
 export function createClientAgentSessionRuntime(input: {
   app: RouteApp;
@@ -38,12 +39,21 @@ export function createClientAgentSessionRuntime(input: {
     registerUnavailableClientAgentSessionRoutes(
       createManifestAuthorizedRouteApp(input.app, input.routeAuthorizer),
     );
-    return { service: undefined, dispose: undefined };
+    return {
+      service: undefined,
+      repository: undefined,
+      hostApp: undefined,
+      attemptAuthority: undefined,
+      revokeHost: undefined,
+      dispose: undefined,
+    };
   }
+  const attemptAuthority = new ClientSessionAttemptAuthorityBinding();
+  const repository = input.db
+    ? new DrizzleClientSessionRepository(input.db, attemptAuthority)
+    : new InMemoryClientSessionRepository();
   const service = new GovernedClientAgentSessionService(
-    input.db
-      ? new DrizzleClientSessionRepository(input.db)
-      : new InMemoryClientSessionRepository(),
+    repository,
     new ManifestClientSessionAdmission(
       input.modules,
       input.hosts,
@@ -64,6 +74,7 @@ export function createClientAgentSessionRuntime(input: {
     }),
     new RuntimeClientSessionAudit(input.runtime),
     trustedBaseUrl(),
+    attemptAuthority,
   );
   const hostApp = createClientAgentHostAuthRouteApp({
     app: input.app,
@@ -75,13 +86,18 @@ export function createClientAgentSessionRuntime(input: {
     createManifestAuthorizedRouteApp(hostApp, input.routeAuthorizer),
     service,
   );
-  const unbind = input.hostAuth.bindRevocations(async (principal) => {
-    await service.revokeHostSession(
-      hostSessionDigest(principal),
-      principal.actorId,
-    );
-  });
-  return { service, dispose: unbind };
+  return {
+    service,
+    repository,
+    hostApp,
+    attemptAuthority,
+    revokeHost: (principal: Parameters<typeof hostSessionDigest>[0]) =>
+      service.revokeHostSession(
+        hostSessionDigest(principal),
+        principal.actorId,
+      ),
+    dispose: undefined,
+  };
 }
 
 function trustedBaseUrl(): string {

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

@@ -3,6 +3,7 @@ import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type {
   ClientAgentProviderPort,
   ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
   ClientSessionCaller,
   ClientSessionRecord,
   ClientSessionReceiptRecord,
@@ -21,6 +22,11 @@ import {
   parseClientAgentCompletion,
 } from "./request.js";
 import { ProviderInputGovernanceError } from "../provider-input-governance.js";
+import {
+  enforceClientSessionAttemptAuthority,
+  enforceClientSessionProviderBoundary,
+  type ClientSessionAttemptRevocationCause,
+} from "./attempt-authority.js";
 
 export type ClientAgentCompletionEvent =
   | { readonly type: "chunk"; readonly value: ModuleAiJsonValue }
@@ -45,6 +51,7 @@ export async function runClientAgentCompletion(input: {
   caller: ClientSessionCaller;
   signal?: AbortSignal;
   current: ClientSessionRecord;
+  attemptAuthority: ClientSessionAttemptAuthorityChecker;
   repository: ClientSessionRepository;
   admission: ClientSessionAdmissionPort;
   provider: ClientAgentProviderPort;
@@ -57,10 +64,18 @@ export async function runClientAgentCompletion(input: {
   ) => Promise<void> | void;
   revokeAudit: (
     record: ClientSessionRecord,
-    cause: "authorization-drift" | "ttl",
+    cause: ClientSessionAttemptRevocationCause,
   ) => Promise<void> | void;
 }) {
   const parsed = parseCompletion(input.body, input.current);
+  const workflowOwned = await enforceClientSessionAttemptAuthority({
+    checker: input.attemptAuthority,
+    record: input.current,
+    repository: input.repository,
+    ...(input.signal ? { signal: input.signal } : {}),
+    workflowOwned: false,
+    audit: input.revokeAudit,
+  });
   const reserved = await input.repository.reserveAttempt({
     sessionId: input.sessionId,
     tokenHash: digestText(input.caller.token),
@@ -83,24 +98,16 @@ export async function runClientAgentCompletion(input: {
     if (checking || controller.signal.aborted) return;
     checking = true;
     try {
-      const cause =
-        input.current.expiresAt <= input.now()
-          ? "ttl"
-          : (await input.admission.reauthorize(
-                input.current,
-                input.caller.actorId,
-              ))
-            ? undefined
-            : "authorization-drift";
-      if (!cause) return;
-      const status = cause === "ttl" ? "expired" : "revoked";
-      const closed = await input.repository.transition(
-        input.sessionId,
-        "active",
-        status,
-      );
-      if (closed) await input.revokeAudit(closed, cause);
-      controller.abort(cause);
+      await enforceClientSessionProviderBoundary({
+        admission: input.admission,
+        checker: input.attemptAuthority,
+        record: reserved,
+        repository: input.repository,
+        now: input.now(),
+        signal: controller.signal,
+        workflowOwned,
+        audit: input.revokeAudit,
+      });
     } catch {
       controller.abort("authorization-check-failed");
     } finally {
@@ -112,6 +119,7 @@ export async function runClientAgentCompletion(input: {
     abort: () => controller.abort(),
     events: completionEvents({
       ...input,
+      workflowOwned,
       parsed,
       reserved,
       attempt,
@@ -135,6 +143,8 @@ async function* completionEvents(input: {
   watcher: ReturnType<typeof setInterval>;
   repository: ClientSessionRepository;
   admission: ClientSessionAdmissionPort;
+  attemptAuthority: ClientSessionAttemptAuthorityChecker;
+  workflowOwned: boolean;
   provider: ClientAgentProviderPort;
   controllers: Map<string, AbortController>;
   now: () => number;
@@ -143,6 +153,10 @@ async function* completionEvents(input: {
     outcome: "success" | "failure",
     metadata: Readonly<Record<string, string | number | boolean>>,
   ) => Promise<void> | void;
+  revokeAudit: (
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ) => Promise<void> | void;
 }): AsyncGenerator<ClientAgentCompletionEvent> {
   let settled = false;
   let audited = false;
@@ -151,6 +165,17 @@ async function* completionEvents(input: {
     let deploymentDigest: `sha256:${string}` | undefined;
     let responseBytes = 0;
     let usage: Readonly<Record<string, number>> = {};
+    await enforceClientSessionProviderBoundary({
+      admission: input.admission,
+      checker: input.attemptAuthority,
+      record: input.reserved,
+      repository: input.repository,
+      attempt: input.attempt,
+      now: input.now(),
+      signal: input.controller.signal,
+      workflowOwned: input.workflowOwned,
+      audit: input.revokeAudit,
+    });
     for await (const event of input.provider.stream(
       input.parsed.request,
       {
@@ -187,6 +212,21 @@ async function* completionEvents(input: {
     }
     if (!deploymentDigest) throw new Error("Provider meta 缺失");
     const response = accumulator.result();
+    await enforceClientSessionProviderBoundary({
+      admission: input.admission,
+      checker: input.attemptAuthority,
+      record: input.reserved,
+      repository: input.repository,
+      attempt: input.attempt,
+      now: input.now(),
+      signal: input.controller.signal,
+      workflowOwned: input.workflowOwned,
+      audit: input.revokeAudit,
+    });
+    const canonicalResult = await input.admission.projectProviderResult(
+      input.reserved.operationKey,
+      response,
+    );
     const receipt: ClientSessionReceiptRecord = {
       receiptId: `receipt_${randomUUID()}`,
       clientRunId: input.reserved.clientRunId,
@@ -199,12 +239,23 @@ async function* completionEvents(input: {
       responseDigest: digestJson(response),
       deploymentDigest,
       issuedAt: input.now(),
-      canonicalResult: await input.admission.projectProviderResult(
-        input.reserved.operationKey,
-        response,
-      ),
+      canonicalResult,
     };
-    if (!(await input.repository.completeAttempt(input.sessionId, receipt))) {
+    const committed = await input.repository.completeAttempt(
+      input.sessionId,
+      receipt,
+    );
+    if (!committed) {
+      if (input.workflowOwned) {
+        await enforceClientSessionAttemptAuthority({
+          checker: input.attemptAuthority,
+          record: input.reserved,
+          repository: input.repository,
+          signal: input.controller.signal,
+          workflowOwned: true,
+          audit: input.revokeAudit,
+        });
+      }
       throw clientSessionConflict("模型响应到达时会话已关闭");
     }
     settled = true;

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

@@ -76,6 +76,28 @@ export interface ClientSessionCaller {
   readonly hostSessionDigest: `sha256:${string}`;
 }
 
+export type ClientSessionAttemptAuthorityDecision =
+  | "ordinary"
+  | "current"
+  | "revoked";
+
+export interface ClientSessionAttemptAuthorityFacts {
+  readonly sessionId: string;
+  readonly clientRunId: string;
+  readonly actorId: string;
+  readonly operationKey: string;
+  readonly clientBindingDigest: `sha256:${string}`;
+  readonly hostSessionDigest: `sha256:${string}`;
+}
+
+/** Host checker 必须从 canonical Workflow/command/fence 事实判定，不接受浏览器声明。 */
+export interface ClientSessionAttemptAuthorityChecker {
+  check(
+    facts: ClientSessionAttemptAuthorityFacts,
+    signal?: AbortSignal,
+  ): Promise<ClientSessionAttemptAuthorityDecision>;
+}
+
 export interface ClientAgentProviderPort {
   readonly modelAlias: string;
   ready(signal?: AbortSignal): Promise<boolean>;
@@ -105,6 +127,7 @@ export interface ClientSessionAdmissionPort {
     readonly input: ModuleAiJsonValue;
     readonly clientBindingDigest: `sha256:${string}`;
     readonly actorId: string;
+    readonly launchAuthority: "direct" | "workflow-artifact";
   }): Promise<ClientSessionAdmission>;
   reauthorize(session: ClientSessionRecord, actorId: string): Promise<boolean>;
   validateResult(