create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent-workflow/artifact-node-adapter.ts

@@ -0,0 +1,67 @@
+import type { AgentWorkflowNodeAdapter } from "./adapter-dispatch.js";
+import type { AgentWorkflowArtifactPort } from "./node-execution-ports.js";
+import {
+  directPlatformResult,
+  failedPlatformResult,
+  platformDigest,
+} from "./platform-node-adapter-support.js";
+
+export function artifactNodeAdapter(
+  artifacts: AgentWorkflowArtifactPort,
+): AgentWorkflowNodeAdapter {
+  return {
+    nodeType: "artifact",
+    async prepare(context) {
+      const node = context.node;
+      if (node.type !== "artifact") {
+        return failedPlatformResult("NODE_TYPE_MISMATCH");
+      }
+      if (
+        !(await artifacts.reauthorize({
+          artifacts: context.inputArtifacts,
+          actorId: context.run.actorId,
+          scopeDigest: context.run.scopeDigest,
+          signal: context.signal,
+        }))
+      ) {
+        return failedPlatformResult("ARTIFACT_OBJECT_FORBIDDEN");
+      }
+      const sealed = await artifacts.seal({
+        policyKey: node.policyKey,
+        artifactKind: node.artifactKind,
+        sourceArtifacts: context.inputArtifacts,
+        actorId: context.run.actorId,
+        scopeDigest: context.run.scopeDigest,
+        idempotencyKey: context.nodeRun.idempotencyKey,
+        signal: context.signal,
+      });
+      if (
+        !sealed.length ||
+        sealed.some(
+          (artifact) =>
+            artifact.kind !== node.artifactKind ||
+            artifact.retentionPolicyKey !== node.policyKey ||
+            !/^(?:sha256:)?[a-f0-9]{64}$/.test(artifact.sha256) ||
+            artifact.byteSize < 0,
+        )
+      ) {
+        return failedPlatformResult("ARTIFACT_SEAL_INVALID");
+      }
+      return directPlatformResult({
+        context,
+        result: {
+          artifactIds: sealed.map(({ artifactId }) => artifactId),
+          policyKey: node.policyKey,
+        },
+        resultDigest: platformDigest(
+          sealed.map(({ artifactId, sha256, byteSize }) => ({
+            artifactId,
+            sha256,
+            byteSize,
+          })),
+        ),
+        outputArtifacts: sealed,
+      });
+    },
+  };
+}

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

@@ -0,0 +1,71 @@
+import type { AgentWorkflowArtifactRef } from "@southwind-ai/shared";
+
+export interface AgentWorkflowArtifactPolicy {
+  readonly key: string;
+  readonly allowedMediaTypes: readonly string[];
+  readonly maxArtifactBytes: number;
+  readonly allowedArtifactKinds: readonly string[];
+}
+
+export class AgentWorkflowArtifactPolicyRegistry {
+  private readonly policies = new Map<string, AgentWorkflowArtifactPolicy>();
+
+  register(policy: AgentWorkflowArtifactPolicy) {
+    if (this.policies.has(policy.key)) {
+      throw new Error(`WORKFLOW_ARTIFACT_POLICY_DUPLICATE:${policy.key}`);
+    }
+    this.policies.set(policy.key, Object.freeze(structuredClone(policy)));
+    return this;
+  }
+
+  require(key: string, artifactKind: string) {
+    const policy = this.policies.get(key);
+    if (!policy || !policy.allowedArtifactKinds.includes(artifactKind)) {
+      throw new Error("WORKFLOW_ARTIFACT_POLICY_UNAVAILABLE");
+    }
+    return policy;
+  }
+
+  assertArtifact(
+    policy: AgentWorkflowArtifactPolicy,
+    artifact: AgentWorkflowArtifactRef,
+  ) {
+    if (
+      artifact.byteSize < 0 ||
+      artifact.byteSize > policy.maxArtifactBytes ||
+      !policy.allowedMediaTypes.includes(artifact.mediaType) ||
+      !/^(?:sha256:)?[a-f0-9]{64}$/.test(artifact.sha256) ||
+      !Number.isSafeInteger(artifact.source.sequence) ||
+      artifact.source.sequence < 1
+    ) {
+      throw new Error("WORKFLOW_ARTIFACT_POLICY_REJECTED");
+    }
+  }
+}
+
+export function createProductionWorkflowArtifactPolicies() {
+  return new AgentWorkflowArtifactPolicyRegistry().register({
+    key: "workflow.artifact.default",
+    allowedArtifactKinds: [
+      "document",
+      "image",
+      "audio",
+      "structured-data",
+      "report",
+    ],
+    allowedMediaTypes: [
+      "application/json",
+      "application/pdf",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "audio/mpeg",
+      "audio/wav",
+      "image/jpeg",
+      "image/png",
+      "text/csv",
+      "text/markdown",
+      "text/plain",
+    ],
+    maxArtifactBytes: 64 * 1024 * 1024,
+  });
+}

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

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import type { AgentWorkflowArtifactRef } from "@southwind-ai/shared";
+import type { AuthorizationScopeSnapshot } from "@southwind-ai/shared";
+import type { RequestActor } from "../guards.js";
+import type { AuthoritativeSourceAccessPort } from "../agent/session-invalidation/contracts.js";
+import { requireAuthoritativeSourceRead } from "../agent/session-invalidation/read-guard.js";
+import { authorizationReadCoordinateForActor } from "../agent/session-projection-access.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { authorizationScopeContains } from "../data-access/scope-containment.js";
+
+type CausalArtifactSource = AgentWorkflowArtifactRef["source"] & {
+  readonly sequence: number;
+  readonly digest?: string;
+};
+
+export interface AgentWorkflowArtifactSourceAuthorizationPort {
+  requireCurrent(input: {
+    readonly artifact: AgentWorkflowArtifactRef;
+    readonly actorId: string;
+    readonly frozenScope: AuthorizationScopeSnapshot;
+  }): Promise<void>;
+}
+
+/** Re-resolves both the Actor authorization generation and module-owned object. */
+export class ProductionAgentWorkflowArtifactSourceAuthorization implements AgentWorkflowArtifactSourceAuthorizationPort {
+  constructor(
+    private readonly sources: AuthoritativeSourceAccessPort,
+    private readonly resolveActor: (
+      actorId: string,
+    ) => Promise<RequestActor | undefined>,
+  ) {}
+
+  async requireCurrent(input: {
+    readonly artifact: AgentWorkflowArtifactRef;
+    readonly actorId: string;
+    readonly frozenScope: AuthorizationScopeSnapshot;
+  }) {
+    try {
+      const source = causalSource(input.artifact);
+      assertSource(source);
+      const actor = await this.resolveActor(input.actorId);
+      if (!actor || actor.type === "anonymous") throw denied();
+      const currentScope = captureAuthorizationScope(actor.scopeContext);
+      if (
+        !authorizationScopeContains(currentScope.snapshot, input.frozenScope)
+      ) {
+        throw denied();
+      }
+      const authorization = authorizationReadCoordinateForActor(actor);
+      if (authorization.actorId !== input.actorId) {
+        throw denied();
+      }
+      await requireAuthoritativeSourceRead(this.sources, {
+        source: {
+          moduleKey: source.moduleKey,
+          sourceKind: source.kind,
+          sourceId: source.id,
+          version: source.version,
+          sequence: source.sequence,
+          ...(source.digest ? { digest: source.digest } : {}),
+        },
+        authorization,
+        requestId: `workflow-artifact:${randomUUID()}`,
+      });
+    } catch {
+      throw denied();
+    }
+  }
+}
+
+function causalSource(artifact: AgentWorkflowArtifactRef) {
+  return artifact.source as CausalArtifactSource;
+}
+
+function assertSource(source: CausalArtifactSource) {
+  if (
+    !source.moduleKey.trim() ||
+    !source.kind.trim() ||
+    !source.id.trim() ||
+    !source.version.trim() ||
+    !Number.isSafeInteger(source.sequence) ||
+    source.sequence < 1 ||
+    (source.digest !== undefined && !source.digest.trim())
+  ) {
+    throw denied();
+  }
+}
+
+function denied() {
+  return new Error("ARTIFACT_FORBIDDEN");
+}

package/template/apps/server/src/agent-workflow/authorization.ts

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  featureKey as canonicalFeatureKey,
+  type AgentWorkflowRelease,
+} from "@southwind-ai/shared";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import type { WorkflowAuthorizationFence } from "./budget-validation.js";
+import type { AgentWorkflowWorkspacePolicyPort } from "./workspace-policy.js";
+import { canonicalJson } from "./canonical-json.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface AgentWorkflowAuthorizationSnapshot {
+  readonly tenantId: string;
+  readonly actorId: string;
+  readonly scopeDigest: string;
+  readonly authorizationSnapshotDigest: string;
+  readonly toolPolicyDigest: string;
+  readonly workspacePolicyDigest: string;
+  readonly executionPolicyDigest: string;
+  readonly fence: WorkflowAuthorizationFence;
+}
+
+export async function captureAgentWorkflowAuthorization(input: {
+  readonly context: RequestGuardContext;
+  readonly release: AgentWorkflowRelease;
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: ServerRuntime;
+  readonly tools: GovernedToolRegistry;
+  readonly workspacePolicies: AgentWorkflowWorkspacePolicyPort;
+  readonly now?: Date;
+}): Promise<AgentWorkflowAuthorizationSnapshot> {
+  const now = input.now ?? new Date();
+  const actor = input.context.actor;
+  if (actor.type === "anonymous") throw denied("WORKFLOW_ACTOR_REQUIRED");
+  const scope = captureAuthorizationScope(actor.scopeContext);
+  if (scope.snapshot.actorId !== actor.id) {
+    throw denied("WORKFLOW_SCOPE_ACTOR_MISMATCH");
+  }
+  const requiredPermissionKeys = unique(
+    input.release.definition.nodes.flatMap((node) =>
+      node.type === "subagent" ? node.requiredPermissionKeys : [],
+    ),
+  );
+  const requiredFeatureKeys = unique(
+    input.release.definition.nodes.flatMap((node) =>
+      node.type === "subagent" ? node.requiredFeatureKeys : [],
+    ),
+  );
+  await assertCurrentGuards({
+    ...input,
+    requiredPermissionKeys,
+    requiredFeatureKeys,
+  });
+  const toolKeys = unique(
+    input.release.definition.nodes.flatMap((node) => {
+      if (node.type === "tool") return [node.toolKey];
+      return node.type === "subagent" ? node.allowedToolKeys : [];
+    }),
+  );
+  const toolPolicies = [];
+  for (const toolKey of toolKeys) {
+    const definition = input.tools.definition(toolKey);
+    if (!definition || !(await input.tools.allowed(toolKey, input.context))) {
+      throw denied("WORKFLOW_TOOL_AUTHORIZATION_REVOKED");
+    }
+    toolPolicies.push({
+      key: definition.key,
+      permissionKey: definition.permissionKey,
+      featureKey: definition.featureKey,
+      operation: definition.operation,
+      approval: definition.approval,
+      idempotency: definition.idempotency,
+      scopeMode: definition.scopeMode,
+    });
+  }
+  const workspacePolicyKeys = unique(
+    input.release.definition.nodes.flatMap((node) =>
+      node.type === "subagent" ? [node.workspacePolicyKey] : [],
+    ),
+  );
+  const scopeDigest = `sha256:${scope.hash}`;
+  const workspaceDecisions = [];
+  for (const node of input.release.definition.nodes) {
+    if (node.type !== "subagent") continue;
+    const decision = await input.workspacePolicies.authorize({
+      workspacePolicyKey: node.workspacePolicyKey,
+      scopePolicyKey: node.scopePolicyKey,
+      parentScopeDigest: scopeDigest,
+      context: input.context,
+    });
+    if (!decision.allowed) {
+      throw denied(decision.safeCode ?? "WORKFLOW_WORKSPACE_POLICY_REVOKED");
+    }
+    workspaceDecisions.push({
+      nodeId: node.id,
+      policyDigest: decision.policyDigest,
+      narrowedScopeDigest: decision.narrowedScopeDigest,
+      scopeRelation: decision.scopeRelation,
+      workspaceId: decision.workspaceId,
+    });
+  }
+  const authorizationSnapshotDigest = digest({
+    tenantId: scope.snapshot.tenantId,
+    actorId: actor.id,
+    scopeDigest,
+    requiredPermissionKeys,
+    requiredFeatureKeys,
+    licenseVersion: licenseVersion(input.context),
+  });
+  const toolPolicyDigest = digest({
+    releaseDigest: input.release.releaseDigest,
+    toolPolicies,
+  });
+  const workspacePolicyDigest = digest({
+    releaseDigest: input.release.releaseDigest,
+    workspacePolicyKeys,
+    decisions: workspaceDecisions,
+  });
+  const executionPolicyDigest = digest({
+    releaseDigest: input.release.releaseDigest,
+    budget: input.release.definition.budget,
+    nodes: input.release.definition.nodes.map((node) => ({
+      id: node.id,
+      type: node.type,
+      failurePolicy: node.failurePolicy,
+      timeoutSeconds: node.timeoutSeconds,
+    })),
+    coordinates: input.release.coordinates,
+  });
+  const checkedAt = now.toISOString();
+  return Object.freeze({
+    tenantId: scope.snapshot.tenantId,
+    actorId: actor.id,
+    scopeDigest,
+    authorizationSnapshotDigest,
+    toolPolicyDigest,
+    workspacePolicyDigest,
+    executionPolicyDigest,
+    fence: {
+      proofId: digest({
+        requestId: input.context.requestId,
+        authorizationSnapshotDigest,
+        checkedAt,
+      }),
+      actorId: actor.id,
+      authorizationSnapshotDigest,
+      runPolicyDigest: executionPolicyDigest,
+      checkedAt,
+      expiresAt: new Date(now.getTime() + 60_000).toISOString(),
+    },
+  });
+}
+
+async function assertCurrentGuards(input: {
+  readonly context: RequestGuardContext;
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: ServerRuntime;
+  readonly requiredPermissionKeys: readonly string[];
+  readonly requiredFeatureKeys: readonly string[];
+  readonly release: AgentWorkflowRelease;
+}) {
+  const featureByKey = new Map(
+    input.modules.flatMap(({ features }) =>
+      features.map((feature) => [feature.key, feature] as const),
+    ),
+  );
+  for (const permissionKey of input.requiredPermissionKeys) {
+    const result = await evaluateAccessGuards(
+      input.runtime,
+      input.context,
+      { permission: { permissionKey } },
+      { record: false },
+    );
+    if (!result.decision.allowed) {
+      throw denied("WORKFLOW_PERMISSION_REVOKED");
+    }
+  }
+  for (const featureKey of input.requiredFeatureKeys) {
+    const feature = featureByKey.get(canonicalFeatureKey(featureKey));
+    if (!feature) throw denied("WORKFLOW_FEATURE_UNKNOWN");
+    const result = await evaluateAccessGuards(
+      input.runtime,
+      input.context,
+      {
+        permission: { permissionKey: "system.agent-workflow.manage" },
+        feature,
+      },
+      { record: false },
+    );
+    if (!result.decision.allowed) {
+      throw denied("WORKFLOW_FEATURE_OR_LICENSE_REVOKED");
+    }
+  }
+  const currentLicense = licenseVersion(input.context);
+  for (const node of input.release.definition.nodes) {
+    if (
+      node.type === "subagent" &&
+      node.allowedLicenseVersions?.length &&
+      !node.allowedLicenseVersions.includes(currentLicense)
+    ) {
+      throw denied("WORKFLOW_LICENSE_REVOKED");
+    }
+  }
+}
+
+function licenseVersion(context: RequestGuardContext) {
+  if (context.licenseEnforced === false) return "license-not-enforced";
+  return context.license?.versionKey ?? "license-missing";
+}
+
+function unique(values: readonly string[]) {
+  return [...new Set(values)].sort();
+}
+
+export function workflowDigest(value: unknown) {
+  return digest(value);
+}
+
+function digest(value: unknown) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+export class AgentWorkflowAuthorizationError extends Error {
+  constructor(readonly code: string) {
+    super(code);
+    this.name = "AgentWorkflowAuthorizationError";
+  }
+}
+
+function denied(code: string) {
+  return new AgentWorkflowAuthorizationError(code);
+}

package/template/apps/server/src/agent-workflow/budget-ledger.ts

@@ -0,0 +1,118 @@
+import type {
+  AgentWorkflowBudget,
+  AgentWorkflowUsage,
+} from "@southwind-ai/shared";
+import type { WorkflowAuthorizationFence } from "./budget-validation.js";
+
+export interface WorkflowBudgetReservationRecord {
+  readonly reservationId: string;
+  readonly parentRunId: string;
+  readonly parentNodeRunId: string;
+  readonly delegationId: string;
+  readonly idempotencyKey: string;
+  readonly authorizationProofId: string;
+  readonly authorizationSnapshotDigest: string;
+  readonly runPolicyDigest: string;
+  readonly requested: AgentWorkflowBudget;
+  readonly consumed: AgentWorkflowUsage;
+  readonly status: "active" | "settled" | "released";
+  readonly version: number;
+  readonly createdAt: string;
+  readonly settledAt?: string;
+  readonly usageReceiptId?: string;
+  readonly reasonCode?: string;
+}
+
+export interface WorkflowBudgetLedgerSnapshot {
+  readonly parentRunId: string;
+  readonly budget: AgentWorkflowBudget;
+  readonly consumed: AgentWorkflowUsage;
+  readonly activeReservations: readonly WorkflowBudgetReservationRecord[];
+  readonly remaining: AgentWorkflowBudget;
+  readonly version: number;
+}
+
+export type WorkflowBudgetReservationResult =
+  | {
+      readonly outcome: "reserved" | "replayed";
+      readonly reservation: WorkflowBudgetReservationRecord;
+      readonly ledger: WorkflowBudgetLedgerSnapshot;
+    }
+  | {
+      readonly outcome:
+        | "conflict"
+        | "budget-exceeded"
+        | "authorization-stale"
+        | "run-terminal";
+      readonly safeCode: string;
+    };
+
+/**
+ * The implementation is the atomic authority. It must lock/CAS the parent
+ * ledger, verify the current Host authorization fence against the parent Run,
+ * recompute current usage plus every active parallel reservation, and insert
+ * the reservation in one serialized admission operation. Callers never submit
+ * a precomputed "remaining" or authorize from a stale snapshot.
+ */
+export interface WorkflowBudgetLedgerPort {
+  read(parentRunId: string): Promise<WorkflowBudgetLedgerSnapshot | undefined>;
+  reserve(input: {
+    readonly reservationId: string;
+    readonly parentRunId: string;
+    readonly parentNodeRunId: string;
+    readonly delegationId: string;
+    readonly requested: AgentWorkflowBudget;
+    readonly expectedLedgerVersion: number;
+    readonly idempotencyKey: string;
+    readonly authorizationFence: WorkflowAuthorizationFence;
+    readonly deadlineAt: string;
+  }): Promise<WorkflowBudgetReservationResult>;
+  settle(input: {
+    readonly reservationId: string;
+    readonly parentRunId: string;
+    readonly expectedReservationVersion: number;
+    readonly consumed: AgentWorkflowUsage;
+    readonly usageReceiptId: string;
+    readonly authorizationSnapshotDigest: string;
+    readonly runPolicyDigest: string;
+    readonly settledAt: string;
+  }): Promise<
+    | {
+        readonly outcome: "settled" | "replayed";
+        readonly reservation: WorkflowBudgetReservationRecord;
+        readonly ledger: WorkflowBudgetLedgerSnapshot;
+      }
+    | {
+        readonly outcome: "conflict" | "budget-exceeded" | "usage-unknown";
+        readonly safeCode: string;
+      }
+  >;
+  release(input: {
+    readonly reservationId: string;
+    readonly parentRunId: string;
+    readonly expectedReservationVersion: number;
+    readonly reasonCode: string;
+    readonly authorizationSnapshotDigest: string;
+    readonly runPolicyDigest: string;
+    readonly releasedAt: string;
+  }): Promise<
+    | {
+        readonly outcome: "released" | "replayed";
+        readonly reservation: WorkflowBudgetReservationRecord;
+        readonly ledger: WorkflowBudgetLedgerSnapshot;
+      }
+    | { readonly outcome: "conflict" }
+  >;
+}
+
+export type { WorkflowAuthorizationFence } from "./budget-validation.js";
+export {
+  assertBudgetLedgerSnapshot,
+  assertReservation,
+  assertReservationFits,
+  assertSettlementWithinReservation,
+  assertWorkflowAuthorizationFence,
+  calculateRemainingBudget,
+  WorkflowBudgetError,
+  WORKFLOW_BUDGET_KEYS,
+} from "./budget-validation.js";