create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent/client-workflow-artifact/session-boundary.ts

@@ -0,0 +1,39 @@
+import { ClientAgentSessionError } from "../client-session/errors.js";
+import { ClientAgentWorkflowArtifactError } from "./error.js";
+
+export async function clientWorkflowSessionCall<T>(
+  operation: Promise<T>,
+  phase: "create" | "finalize" | "revoke",
+): Promise<T> {
+  try {
+    return await operation;
+  } catch (error) {
+    if (!(error instanceof ClientAgentSessionError)) throw error;
+    if (error.code === "PROVIDER_FAILED") {
+      throw new ClientAgentWorkflowArtifactError(
+        "PROVIDER_FAILED",
+        "Browser Assistant 暂不可用",
+        503,
+      );
+    }
+    if (phase === "finalize") {
+      throw new ClientAgentWorkflowArtifactError(
+        "RECEIPT_REJECTED",
+        "Client Agent 终态回执未通过校验",
+        error.status === 400 ? 400 : 409,
+      );
+    }
+    if (error.code === "NOT_FOUND" || error.code === "FORBIDDEN") {
+      throw new ClientAgentWorkflowArtifactError(
+        "NOT_FOUND",
+        "Workflow Client Agent 任务不存在或不可访问",
+        404,
+      );
+    }
+    throw new ClientAgentWorkflowArtifactError(
+      "CONFLICT",
+      phase === "create" ? "Client Agent Session 无法签发" : "会话无法撤销",
+      409,
+    );
+  }
+}

package/template/apps/server/src/agent/client-workflow-artifact/source-access.contract.test.ts

@@ -0,0 +1,98 @@
+import { expect, test } from "bun:test";
+import type { DurableJobService } from "../../jobs/service.js";
+import { buildScopeContext } from "../../data-access/context.js";
+import { captureAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import { authorizationReadCoordinateForActor } from "../session-projection-access.js";
+import type { CausalSourceReference } from "../session-invalidation/contracts.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import { ClientAgentWorkflowArtifactSourceAccess } from "./source-access.js";
+import { workflowRecord } from "./workflow-artifact.test-support.js";
+
+test("来源读取允许当前多案 scope 包含冻结单案 scope，撤权或角色漂移拒绝", async () => {
+  const frozenContext = scope(["case-1"]);
+  const frozen = captureAuthorizationScope(frozenContext);
+  const record = workflowRecord({
+    scopeDigest: `sha256:${frozen.hash}`,
+    status: "completed",
+    terminalReceiptId: "receipt-1",
+    terminalReceiptDigest: `sha256:${"d".repeat(64)}`,
+    historySequence: 3,
+  });
+  const access = new ClientAgentWorkflowArtifactSourceAccess(
+    {
+      find: async () => record,
+    } as unknown as ClientAgentWorkflowArtifactRepository,
+    {
+      get: async () => ({
+        job: {
+          id: record.durableJobId,
+          handlerKey: record.taskKey,
+          requestedBy: record.actorId,
+          authorizationScope: frozen.snapshot,
+        },
+      }),
+    } as unknown as DurableJobService,
+  );
+  const version = record.terminalReceiptId;
+  const digest = record.terminalReceiptDigest;
+  if (!version || !digest) throw new Error("terminal source fixture missing");
+  const source: CausalSourceReference = {
+    moduleKey: "system.agent-workflow",
+    sourceKind: "client-agent-artifact",
+    sourceId: record.workId,
+    version,
+    sequence: record.historySequence,
+    digest,
+  };
+
+  await expect(
+    access.authorizeCurrent({
+      source,
+      authorization: authorization(["case-1", "case-2"]),
+      requestId: "request-containing",
+    }),
+  ).resolves.toMatchObject({ outcome: "allowed" });
+  await expect(
+    access.authorizeCurrent({
+      source,
+      authorization: authorization(["case-2"]),
+      requestId: "request-revoked",
+    }),
+  ).resolves.toEqual({ outcome: "denied", reason: "object-forbidden" });
+  await expect(
+    access.authorizeCurrent({
+      source,
+      authorization: authorization(["case-1"], "role-reviewer"),
+      requestId: "request-role-drift",
+    }),
+  ).resolves.toEqual({ outcome: "denied", reason: "object-forbidden" });
+});
+
+function authorization(values: string[], roleId = "role-analyst") {
+  const scopeContext = scope(values, roleId);
+  return authorizationReadCoordinateForActor({
+    id: "actor-1",
+    type: "user",
+    name: "Analyst",
+    roleCodes: [roleId],
+    permissionKeys: ["system.agent-workflow.manage"],
+    dataAccess: scopeContext,
+    scopeContext,
+  });
+}
+
+function scope(values: string[], roleId = "role-analyst") {
+  return buildScopeContext(
+    "actor-1",
+    undefined,
+    [
+      {
+        id: roleId,
+        code: roleId,
+        dataScope: "custom",
+        departmentIds: values,
+      },
+    ],
+    [{ scope: "custom", dimension: "caseId", values }],
+  );
+}

package/template/apps/server/src/agent/client-workflow-artifact/source-access.ts

@@ -0,0 +1,80 @@
+import type {
+  AuthoritativeSourceAccessDecision,
+  AuthoritativeSourceAccessPort,
+  AuthoritativeSourceAccessQuery,
+} from "../session-invalidation/contracts.js";
+import type { DurableJobService } from "../../jobs/service.js";
+import { hashAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import {
+  clientAgentWorkflowArtifactSourceKind,
+  clientAgentWorkflowArtifactSourceModule,
+} from "./contracts.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import {
+  currentClientWorkflowScopeContains,
+  requireClientWorkflowFrozenScope,
+} from "./scope-authority.js";
+
+export class ClientAgentWorkflowArtifactSourceAccess implements AuthoritativeSourceAccessPort {
+  constructor(
+    private readonly repository: ClientAgentWorkflowArtifactRepository,
+    private readonly jobs: DurableJobService,
+  ) {}
+
+  async authorizeCurrent(
+    query: AuthoritativeSourceAccessQuery,
+  ): Promise<AuthoritativeSourceAccessDecision> {
+    if (
+      query.source.moduleKey !== clientAgentWorkflowArtifactSourceModule ||
+      query.source.sourceKind !== clientAgentWorkflowArtifactSourceKind ||
+      query.authorization.actorId.trim() === ""
+    ) {
+      return denied();
+    }
+    const record = await this.repository.find(query.source.sourceId);
+    const currentScope = query.authorization.scopeSnapshot;
+    if (
+      !record ||
+      !currentScope ||
+      record.status !== "completed" ||
+      record.actorId !== query.authorization.actorId ||
+      record.terminalReceiptId !== query.source.version ||
+      record.historySequence !== query.source.sequence ||
+      !record.terminalReceiptDigest ||
+      (query.source.digest !== undefined &&
+        record.terminalReceiptDigest !== query.source.digest)
+    ) {
+      return denied();
+    }
+    try {
+      const frozenScope = requireClientWorkflowFrozenScope(
+        record,
+        await this.jobs.get(record.durableJobId),
+      );
+      if (
+        `sha256:${hashAuthorizationScope(currentScope)}` !==
+          query.authorization.scopeDigest ||
+        !currentClientWorkflowScopeContains({
+          current: currentScope,
+          currentDigest: query.authorization.scopeDigest,
+          frozen: frozenScope,
+          frozenDigest: record.scopeDigest,
+        })
+      ) {
+        return denied();
+      }
+    } catch {
+      return denied();
+    }
+    return {
+      outcome: "allowed",
+      sourceVersion: record.terminalReceiptId,
+      sourceSequence: record.historySequence,
+      authorizationGeneration: query.authorization.generation,
+    };
+  }
+}
+
+function denied(): AuthoritativeSourceAccessDecision {
+  return { outcome: "denied", reason: "object-forbidden" };
+}

package/template/apps/server/src/agent/client-workflow-artifact/takeover.ts

@@ -0,0 +1,122 @@
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import { workflowArtifactConflict } from "./service-support.js";
+import { clientWorkflowSessionCall } from "./session-boundary.js";
+
+export async function reconcileClientWorkflowTakeover(input: {
+  previousClientSessionId?: string;
+  workId: string;
+  sessions: GovernedClientAgentSessionService;
+  sessionRepository: ClientSessionRepository;
+  repository: ClientAgentWorkflowArtifactRepository;
+  now: number;
+}) {
+  if (!input.previousClientSessionId) return;
+  const previous = await input.sessionRepository.find(
+    input.previousClientSessionId,
+  );
+  if (previous && (previous.attemptCount > 0 || previous.receipts.length)) {
+    const record = await input.repository.find(input.workId);
+    if (record) {
+      await input.repository.requestCancel({
+        workId: record.workId,
+        now: input.now,
+      });
+    }
+    await clientWorkflowSessionCall(
+      input.sessions.revokeSession(
+        input.previousClientSessionId,
+        "workflow-unsafe-takeover",
+      ),
+      "revoke",
+    );
+    if (record) {
+      await input.repository.finalizeCancel({
+        workId: record.workId,
+        now: input.now,
+      });
+    }
+    throw workflowArtifactConflict("旧领取已产生页面副作用，不能在新宿主重放");
+  }
+  await clientWorkflowSessionCall(
+    input.sessions.revokeSession(
+      input.previousClientSessionId,
+      "workflow-takeover",
+    ),
+    "revoke",
+  );
+}
+
+export async function canResumeClientWorkflowClaim(input: {
+  record: ClientAgentWorkflowArtifactRecord;
+  binding: {
+    clientBindingDigest: string;
+    installationId: string;
+    hostSessionDigest: string;
+  };
+  sessionRepository: ClientSessionRepository;
+}) {
+  const { record, binding } = input;
+  if (
+    record.status !== "claimed" ||
+    record.clientBindingDigest !== binding.clientBindingDigest ||
+    record.installationId !== binding.installationId ||
+    record.hostSessionDigest !== binding.hostSessionDigest
+  ) {
+    return false;
+  }
+  if (!record.clientSessionId) return true;
+  const session = await input.sessionRepository.find(record.clientSessionId);
+  return Boolean(
+    !session ||
+    (session.attemptCount === 0 &&
+      session.activeRequests === 0 &&
+      session.receipts.length === 0),
+  );
+}
+
+export async function fenceResumableClientWorkflowClaim(
+  input: Parameters<typeof canResumeClientWorkflowClaim>[0] & {
+    sessions: GovernedClientAgentSessionService;
+    repository: ClientAgentWorkflowArtifactRepository;
+    now: number;
+  },
+) {
+  const resumable = await canResumeClientWorkflowClaim(input);
+  const expired =
+    input.record.status === "claimed" &&
+    Boolean(
+      input.record.claimExpiresAt && input.record.claimExpiresAt <= input.now,
+    );
+  if (!resumable && !expired) return false;
+  if (input.record.clientSessionId) {
+    await clientWorkflowSessionCall(
+      input.sessions.revokeSession(
+        input.record.clientSessionId,
+        "workflow-takeover-fence",
+      ),
+      "revoke",
+    );
+    const fenced = await input.sessionRepository.find(
+      input.record.clientSessionId,
+    );
+    if (fenced && (fenced.attemptCount > 0 || fenced.receipts.length)) {
+      const requested = await input.repository.requestCancel({
+        workId: input.record.workId,
+        now: input.now,
+      });
+      if (requested) {
+        await input.repository.finalizeCancel({
+          workId: requested.workId,
+          now: input.now,
+        });
+      }
+      throw workflowArtifactConflict(
+        "旧领取已产生页面副作用，不能在新宿主重放",
+      );
+    }
+  }
+  return true;
+}

package/template/apps/server/src/agent/client-workflow-artifact/task-authority.contract.test.ts

@@ -0,0 +1,97 @@
+import { expect, test } from "bun:test";
+import type { AgentWorkflowArtifactPort } from "../../agent-workflow/node-execution-ports.js";
+import { ClientAgentWorkflowTaskAuthority } from "./task-authority.js";
+import { captureAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import {
+  guardContext,
+  workflowBinding,
+  workflowInput,
+  workflowRecord,
+  workflowSignal,
+} from "./workflow-artifact.test-support.js";
+
+test("claim task 只投影 project canonical input，不公开已重授权 raw Artifact", async () => {
+  const raw = new TextEncoder().encode(
+    JSON.stringify({ sourceId: "source-1", secretEvidence: "raw" }),
+  );
+  const artifact = {
+    artifactId: "artifact-1",
+    kind: "case-input",
+    mediaType: "application/json",
+    byteSize: raw.byteLength,
+    sha256: "a".repeat(64),
+    retentionPolicyKey: "case-analysis",
+    source: {
+      moduleKey: "sharp-full-case",
+      kind: "case-source",
+      id: "source-1",
+      version: "1",
+      sequence: 1,
+    },
+  } as const;
+  const tasks = new ClientAgentWorkflowTaskAuthority();
+  let authorized = true;
+  const artifactPort: AgentWorkflowArtifactPort = {
+    async seal() {
+      return [];
+    },
+    async reauthorize() {
+      return authorized;
+    },
+    async resolve() {
+      return {
+        artifact,
+        token: "token-1",
+        expiresAt: "2026-08-28T00:01:00.000Z",
+      };
+    },
+    async open() {
+      return {
+        artifact,
+        body: new Blob([raw]).stream(),
+        filename: "input.json",
+        contentType: "application/json",
+      };
+    },
+  };
+  tasks.bind(artifactPort);
+  const task = await tasks.build({
+    facts: {
+      record: workflowRecord(),
+      input: workflowInput,
+      inputArtifacts: [artifact],
+      frozenScope: captureAuthorizationScope(guardContext.actor.scopeContext)
+        .snapshot,
+      binding: {
+        ...workflowBinding,
+        clientTaskAuthority: {
+          ...workflowBinding.clientTaskAuthority,
+          async build({ inputArtifacts }) {
+            const value = inputArtifacts[0]?.value;
+            if (!value || typeof value !== "object" || Array.isArray(value)) {
+              throw new Error("test artifact invalid");
+            }
+            return {
+              taskKey: "sharp.full-case",
+              input: { sourceId: value.sourceId as string },
+            };
+          },
+        },
+      },
+    },
+    actorId: "actor-1",
+    scopeDigest: workflowRecord().scopeDigest,
+    signal: workflowSignal,
+  });
+  expect(task.input).toEqual({ sourceId: "source-1" });
+  expect(JSON.stringify(task)).not.toContain("secretEvidence");
+  authorized = false;
+  await expect(
+    tasks.openInputArtifacts({
+      artifacts: [artifact],
+      actorId: "actor-1",
+      scopeDigest: workflowRecord().scopeDigest,
+      signal: workflowSignal,
+    }),
+  ).rejects.toMatchObject({ code: "PROVIDER_FAILED" });
+});

package/template/apps/server/src/agent/client-workflow-artifact/task-authority.ts

@@ -0,0 +1,147 @@
+import { CLIENT_AGENT_WORKFLOW_ARTIFACT_BINDING_LIMITS as limits } from "@southwind-ai/server-sdk";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { ModuleClientAgentWorkflowTaskInputArtifact } from "@southwind-ai/server-sdk";
+import type { AgentWorkflowArtifactPort } from "../../agent-workflow/node-execution-ports.js";
+import { canonicalJson as canonicalArtifact } from "../../agent-workflow/canonical-json.js";
+import { digestJson } from "../client-session/digest.js";
+import type {
+  ClientAgentWorkflowBeginFacts,
+  ClientAgentWorkflowExecutionTask,
+} from "./contracts.js";
+import { ClientAgentWorkflowArtifactError } from "./error.js";
+
+/** Startup-bound Host Seam; a claim cannot proceed before Workflow Artifact runtime is ready. */
+export class ClientAgentWorkflowTaskAuthority {
+  #artifacts?: AgentWorkflowArtifactPort;
+
+  bind(artifacts: AgentWorkflowArtifactPort) {
+    if (this.#artifacts && this.#artifacts !== artifacts) {
+      throw new Error("CLIENT_WORKFLOW_TASK_ARTIFACT_PORT_ALREADY_BOUND");
+    }
+    this.#artifacts = artifacts;
+  }
+
+  async build(input: {
+    readonly facts: ClientAgentWorkflowBeginFacts;
+    readonly actorId: string;
+    readonly scopeDigest: `sha256:${string}`;
+    readonly signal: AbortSignal;
+  }): Promise<ClientAgentWorkflowExecutionTask> {
+    const opened = await this.openInputArtifacts({
+      artifacts: input.facts.inputArtifacts,
+      actorId: input.actorId,
+      scopeDigest: input.scopeDigest,
+      signal: input.signal,
+    });
+    let projected;
+    try {
+      projected = await input.facts.binding.clientTaskAuthority.build({
+        workflowInput: input.facts.input,
+        inputArtifacts: opened,
+        actorId: input.actorId,
+        scopeDigest: input.scopeDigest,
+        signal: input.signal,
+      });
+    } catch {
+      throw unavailable();
+    }
+    if (!validTaskKey(projected.taskKey)) throw unavailable();
+    const taskInput = canonicalJson(projected.input);
+    return {
+      schemaVersion: 1,
+      taskKey: projected.taskKey,
+      input: taskInput,
+      inputDigest: digestJson(taskInput),
+    };
+  }
+
+  async openInputArtifacts(input: {
+    readonly artifacts: ClientAgentWorkflowBeginFacts["inputArtifacts"];
+    readonly actorId: string;
+    readonly scopeDigest: `sha256:${string}`;
+    readonly signal: AbortSignal;
+  }): Promise<readonly ModuleClientAgentWorkflowTaskInputArtifact[]> {
+    const artifacts = this.#artifacts;
+    if (!artifacts && input.artifacts.length) throw unavailable();
+    if (
+      artifacts &&
+      !(await artifacts.reauthorize({
+        artifacts: input.artifacts,
+        actorId: input.actorId,
+        scopeDigest: input.scopeDigest,
+        signal: input.signal,
+      }))
+    ) {
+      throw unavailable();
+    }
+    const opened = [];
+    let totalBytes = 0;
+    for (const artifact of input.artifacts) {
+      totalBytes += artifact.byteSize;
+      if (totalBytes > limits.clientTaskInputArtifactMaxBytes) {
+        throw unavailable();
+      }
+      const resolved = await artifacts!.resolve({
+        artifactId: artifact.artifactId,
+        actorId: input.actorId,
+        scopeDigest: input.scopeDigest,
+        signal: input.signal,
+      });
+      const value = await artifacts!.open({
+        token: resolved.token,
+        actorId: input.actorId,
+        scopeDigest: input.scopeDigest,
+        signal: input.signal,
+      });
+      if (
+        value.contentType !== "application/json" ||
+        canonicalArtifact(resolved.artifact) !== canonicalArtifact(artifact) ||
+        canonicalArtifact(value.artifact) !== canonicalArtifact(artifact)
+      ) {
+        throw unavailable();
+      }
+      const bytes = new Uint8Array(
+        await new Response(value.body).arrayBuffer(),
+      );
+      if (bytes.byteLength !== artifact.byteSize) throw unavailable();
+      opened.push({ artifact, value: parseJson(bytes) });
+    }
+    return opened;
+  }
+}
+
+function parseJson(bytes: Uint8Array): ModuleAiJsonValue {
+  try {
+    return canonicalJson(JSON.parse(new TextDecoder().decode(bytes)));
+  } catch {
+    throw unavailable();
+  }
+}
+
+function canonicalJson(value: ModuleAiJsonValue): ModuleAiJsonValue {
+  const encoded = JSON.stringify(value);
+  if (
+    encoded === undefined ||
+    new TextEncoder().encode(encoded).byteLength > limits.clientTaskMaxBytes
+  ) {
+    throw unavailable();
+  }
+  return JSON.parse(encoded) as ModuleAiJsonValue;
+}
+
+function validTaskKey(value: string) {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= limits.clientTaskKey &&
+    /^[a-z0-9][a-z0-9._-]*$/u.test(value)
+  );
+}
+
+function unavailable() {
+  return new ClientAgentWorkflowArtifactError(
+    "PROVIDER_FAILED",
+    "Client Agent canonical task authority unavailable",
+    503,
+  );
+}

package/template/apps/server/src/agent/client-workflow-artifact/terminal-authority.contract.test.ts

@@ -0,0 +1,100 @@
+import { expect, test } from "bun:test";
+import { MemoryBlobStore } from "@southwind-ai/storage";
+import {
+  createFixture,
+  validCompletion,
+} from "../client-session/service.test-support.js";
+import { hostSessionDigest } from "../client-session/host-auth.js";
+import { InMemoryClientAgentWorkflowArtifactRepository } from "./in-memory-repository.js";
+import { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+import { ClientAgentWorkflowTaskAuthority } from "./task-authority.js";
+import {
+  clientBindingDigest,
+  guardContext,
+  principal,
+  workflowLoader,
+  workflowRecord,
+  workflowSignal,
+} from "./workflow-artifact.test-support.js";
+
+test("project terminal authority 拒绝时 Session 与 Artifact 均不完成", async () => {
+  const repository = new InMemoryClientAgentWorkflowArtifactRepository();
+  const sessions = await createFixture({
+    attemptAuthority: {
+      async check(facts) {
+        const current = await repository.findForActorRun({
+          actorId: facts.actorId,
+          runId: "run-1",
+        });
+        return current?.status === "claimed" &&
+          current.clientSessionId === facts.sessionId
+          ? "current"
+          : "revoked";
+      },
+    },
+  });
+  const blobs = new MemoryBlobStore();
+  const service = new GovernedClientAgentWorkflowArtifactService(
+    repository,
+    workflowLoader({
+      canonicalize: async () => {
+        throw new Error("PROJECT_RESULT_PROVENANCE_REJECTED");
+      },
+    }),
+    sessions.service,
+    sessions.repository,
+    blobs,
+    new ClientAgentWorkflowTaskAuthority(),
+    () => sessions.clock.value,
+  );
+  await service.begin({
+    jobId: "job-1",
+    payload: {
+      commandId: "command-1",
+      runId: "run-1",
+      nodeRunId: "node-run-1",
+      effectGeneration: 1,
+      requestDigest: workflowRecord().requestDigest,
+    },
+    signal: workflowSignal,
+  });
+  const claimed = await service.claim({
+    workflowRunId: "run-1",
+    clientBindingDigest,
+    principal,
+    guardContext,
+    signal: workflowSignal,
+  });
+  if (!("sessionGrant" in claimed) || !("claimToken" in claimed)) {
+    throw new Error("claim grant missing");
+  }
+  const completion = await sessions.service.complete(
+    claimed.sessionGrant.sessionId,
+    validCompletion(),
+    {
+      token: claimed.sessionGrant.accessToken,
+      actorId: principal.actorId,
+      clientBindingDigest,
+      hostSessionDigest: hostSessionDigest(principal),
+    },
+  );
+  await expect(
+    service.advance({
+      workId: claimed.workId,
+      claimVersion: claimed.claimVersion,
+      claimToken: claimed.claimToken,
+      receiptIds: [completion.receipt.receiptId],
+      result: { answer: "未经来源校验的结果" },
+      principal,
+      guardContext,
+      signal: workflowSignal,
+    }),
+  ).rejects.toMatchObject({ code: "RECEIPT_REJECTED", status: 400 });
+  expect(
+    (await sessions.repository.find(claimed.sessionGrant.sessionId))?.status,
+  ).toBe("active");
+  const rejected = await repository.find(claimed.workId);
+  expect(rejected?.status).toBe("claimed");
+  expect(rejected?.artifact).toBeUndefined();
+  expect(blobs.size).toBe(0);
+});