@opengeni/core 0.28.0 → 1.0.0

package/src/access/service-initiator.ts

@@ -0,0 +1,50 @@
+import { ServiceTurnInitiatorContext, type AccessGrant } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+
+/** Validated provenance only. The API key remains the authenticated principal. */
+export function serviceInitiatorFromHeaders(
+  headers: Headers,
+): Pick<AccessGrant, "serviceInitiator" | "serviceInitiatorContext"> | null {
+  const name = headers.get("x-opengeni-service-initiator");
+  const rawContext = headers.get("x-opengeni-service-context");
+  if (name === null && rawContext === null) return null;
+  if (headers.has("x-opengeni-external-actor")) {
+    throw new HTTPException(422, {
+      message: "service initiator and external actor (asUser) are mutually exclusive",
+    });
+  }
+  if (name === null || !/^[a-z0-9][a-z0-9:._-]{0,63}$/.test(name)) {
+    throw new HTTPException(422, {
+      message: "x-opengeni-service-initiator must match ^[a-z0-9][a-z0-9:._-]{0,63}$",
+    });
+  }
+  let context: Record<string, string | number | boolean> = {};
+  if (rawContext !== null) {
+    try {
+      if (new TextEncoder().encode(rawContext).byteLength > 2048) throw new Error("oversize");
+      const parsed: unknown = JSON.parse(rawContext);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("object");
+      if (
+        !Object.values(parsed).every(
+          (value) =>
+            typeof value === "string" ||
+            typeof value === "boolean" ||
+            (typeof value === "number" && Number.isFinite(value)),
+        )
+      )
+        throw new Error("flat");
+      context = parsed as typeof context;
+      // Keep delegated provenance's reserved, OpenGeni-owned lineage fields.
+      if (!ServiceTurnInitiatorContext.safeParse(context).success) throw new Error("reserved");
+    } catch {
+      throw new HTTPException(422, {
+        message:
+          "x-opengeni-service-context must be a JSON object of flat string/number/boolean values, at most 2048 UTF-8 bytes, without reserved Opengeni provenance fields",
+      });
+    }
+  }
+  return {
+    serviceInitiator: { kind: "service", subjectId: name },
+    serviceInitiatorContext: context,
+  };
+}

package/src/application/api-integration-servers.ts

@@ -0,0 +1,215 @@
+import {
+  createGraphqlMcpServer,
+  createOpenApiMcpServer,
+  createPinnedIntegrationTransport,
+  directIntegrationTransport,
+  IntegrationInvocationError,
+  type IntegrationCredentialResolver,
+  type IntegrationInvocationAuthority,
+  type IntegrationTransport,
+} from "@opengeni/capabilities";
+import type { Settings } from "@opengeni/config";
+import type { ToolAuthNeededPayload } from "@opengeni/contracts";
+import type {
+  ApiIntegrationRuntime,
+  ResolveConnectionCredentialInput,
+  ResolveConnectionCredentialResult,
+} from "@opengeni/db";
+import type { FetchLike } from "@opengeni/network";
+import type { LocalMcpServerRegistration } from "@opengeni/runtime";
+
+export type BuildApiIntegrationServersInput = {
+  settings: Settings;
+  integrations: readonly ApiIntegrationRuntime[];
+  authority: Omit<IntegrationInvocationAuthority, "connectionRef">;
+  resolveCredential: (
+    input: ResolveConnectionCredentialInput,
+  ) => Promise<ResolveConnectionCredentialResult>;
+  onAuthNeeded?: (payload: ToolAuthNeededPayload) => Promise<void> | void;
+  fetchImpl?: FetchLike;
+};
+
+/**
+ * Compile active persisted API facets into ordinary in-process MCP providers.
+ * The caller supplies its authority resolver, so agent attempts and current
+ * humans use the same provider assembly without sharing credentials or policy.
+ */
+export function buildApiIntegrationMcpServers(
+  input: BuildApiIntegrationServersInput,
+): LocalMcpServerRegistration[] {
+  const transport = createPinnedIntegrationTransport({
+    network: input.settings,
+    ...(input.fetchImpl ? { fetchImpl: input.fetchImpl } : {}),
+  });
+  return input.integrations.map((integration) => {
+    const authority: IntegrationInvocationAuthority = {
+      ...input.authority,
+      ...(integration.connectionRef?.connectionId
+        ? { connectionRef: integration.connectionRef.connectionId }
+        : {}),
+    };
+    const credentialResolver = integration.connectionRef
+      ? integrationCredentialResolver(input, integration, "execution")
+      : undefined;
+    const buildServer = (
+      serverTransport: IntegrationTransport,
+      serverCredentialResolver = credentialResolver,
+    ) =>
+      integration.revision.protocol === "openapi"
+        ? createOpenApiMcpServer({
+            revision: integration.revision,
+            transport: serverTransport,
+            authority,
+            ...(serverCredentialResolver ? { credentialResolver: serverCredentialResolver } : {}),
+          })
+        : createGraphqlMcpServer({
+            revision: integration.revision,
+            endpoint: integration.baseUrl,
+            transport: serverTransport,
+            authority,
+            ...(serverCredentialResolver ? { credentialResolver: serverCredentialResolver } : {}),
+          });
+    const server = buildServer(transport);
+    const preflightCredentialResolver = integration.connectionRef
+      ? integrationCredentialResolver(input, integration, "preflight")
+      : undefined;
+    const preflightServer = preflightCredentialResolver
+      ? buildServer(providerBlockingPreflightTransport, preflightCredentialResolver)
+      : null;
+    return {
+      id: integration.serverId,
+      server,
+      approvalAuthority: {
+        kind: "api_integration",
+        capabilityId: integration.capabilityId,
+        pluginKey: integration.pluginKey,
+        pluginInstallationId: integration.pluginInstallationId,
+        installationVersion: integration.installationVersion,
+        instanceId: integration.instanceId,
+        instanceKey: integration.instanceKey,
+        instanceVersion: integration.instanceVersion,
+        definitionId: integration.definitionId,
+        definitionProvenance: integration.definitionProvenance,
+        revisionId: integration.revision.id,
+        baseUrl: integration.baseUrl,
+        providerDomain: integration.providerDomain,
+        connectionRef: integration.connectionRef,
+        connectionAuthorityGeneration: integration.connectionAuthorityGeneration,
+      },
+      ...(integration.connectionRef?.connectionId
+        ? { resolvedConnectionId: integration.connectionRef.connectionId }
+        : {}),
+      ...(credentialResolver
+        ? {
+            preflightCall: async (
+              toolName: string,
+              args: Record<string, unknown>,
+              options?: { signal?: AbortSignal },
+            ) => await preflightApiIntegrationCall(preflightServer!, toolName, args, options),
+          }
+        : {}),
+    };
+  });
+}
+
+const providerBlockingPreflightTransport = directIntegrationTransport(async () => {
+  throw new Error("integration provider request blocked by preflight");
+});
+
+async function preflightApiIntegrationCall(
+  server: LocalMcpServerRegistration["server"],
+  toolName: string,
+  args: Record<string, unknown>,
+  options?: { signal?: AbortSignal },
+): Promise<void> {
+  try {
+    await server.callTool(toolName, args, null, options);
+  } catch (error) {
+    if (error instanceof IntegrationInvocationError && error.code === "request_failed") return;
+    throw error;
+  }
+  throw new Error("integration preflight unexpectedly crossed the provider request boundary");
+}
+
+function integrationCredentialResolver(
+  input: BuildApiIntegrationServersInput,
+  integration: ApiIntegrationRuntime,
+  credentialResolutionMode: "execution" | "preflight",
+): IntegrationCredentialResolver {
+  const connectionRef = integration.connectionRef;
+  if (!connectionRef) throw new Error("Integration credential resolver requires a connection");
+  const expectedAuthorityGeneration = integration.connectionAuthorityGeneration;
+  if (expectedAuthorityGeneration === null) {
+    throw new Error("Integration credential resolver requires a connection authority generation");
+  }
+  return {
+    resolve: async (request) => {
+      const result = await input.resolveCredential({
+        workspaceId: input.authority.workspaceId,
+        serverId: integration.serverId,
+        toolName: request.operationKey,
+        connectionRef,
+        destinationUrl: request.destinationUrl,
+        credentialTarget: "http_api",
+        forceRefresh: request.forceRefresh === true,
+        credentialResolutionMode,
+        expectedAuthorityGeneration,
+      });
+      if (result.status === "auth_needed") {
+        await publishAuthNeeded(
+          input,
+          integration.serverId,
+          request.operationKey,
+          result,
+          connectionRef,
+        );
+        return null;
+      }
+      const destination = new URL(request.destinationUrl);
+      return {
+        audience: { origin: destination.origin, pathPrefix: "/" },
+        placements:
+          result.placements ??
+          Object.entries(result.headers).map(([name, value]) => ({
+            carrier: "header" as const,
+            name,
+            value,
+          })),
+        ...(result.authorizeProviderRequest
+          ? { authorizeProviderRequest: result.authorizeProviderRequest }
+          : {}),
+        ...(result.expiresAt ? { expiresAt: result.expiresAt.toISOString() } : {}),
+        ...(connectionRef.scopes ? { scope: [...connectionRef.scopes] } : {}),
+      };
+    },
+  };
+}
+
+async function publishAuthNeeded(
+  input: BuildApiIntegrationServersInput,
+  serverId: string,
+  toolName: string,
+  result: Extract<ResolveConnectionCredentialResult, { status: "auth_needed" }>,
+  connectionRef: NonNullable<ApiIntegrationRuntime["connectionRef"]>,
+): Promise<void> {
+  try {
+    await input.onAuthNeeded?.({
+      serverId,
+      toolName,
+      providerDomain: result.providerDomain,
+      ...(result.provider ? { provider: result.provider } : {}),
+      reason: result.reason,
+      ...(result.connectionId ? { connectionId: result.connectionId } : {}),
+      ...(result.authoritySource === "host" || connectionRef.authoritySource === "host"
+        ? { authoritySource: "host" as const }
+        : {}),
+      ...(result.scopes ? { scopes: result.scopes } : {}),
+      ...(result.resource ? { resource: result.resource } : {}),
+      ...(result.selectedResources ? { selectedResources: result.selectedResources } : {}),
+      ...(result.authorizationUrl ? { authorizationUrl: result.authorizationUrl } : {}),
+    });
+  } catch {
+    // Authentication notices are advisory UI/audit signals. The local tool
+    // still returns the fixed connection-required result when publication fails.
+  }
+}

package/src/application/archived-session-imports.ts

@@ -0,0 +1,161 @@
+import {
+  AppendArchivedSessionEventsRequest,
+  AppendArchivedSessionEventsResponse,
+  ImportArchivedSessionRequest,
+  ImportArchivedSessionResponse,
+  type Permission,
+  type SessionEvent,
+} from "@opengeni/contracts";
+import {
+  ArchivedSessionImportError,
+  appendArchivedSessionEvents,
+  getArchivedSessionImportId,
+  importArchivedSession,
+  withSessionRlsActorContext,
+} from "@opengeni/db";
+import { publishDurableSessionEvents } from "@opengeni/events";
+import { HTTPException } from "hono/http-exception";
+import {
+  hasVerifiedOwningUserAuthorization,
+  requirePermission,
+  requireResolvedAccessGrantAuthorization,
+  type AccessGrantAuthorization,
+} from "../access";
+import type { ApiRouteDeps } from "../dependencies";
+import { creationInitiatorForGrant } from "../domain/sessions";
+import { fileOwnerContextForAccess } from "../domain/file-owner";
+import {
+  grantHasAgentAttemptAuthority,
+  requireSessionAuthorization,
+} from "../session-authorization";
+import { externalContinuationCommitAuthorizer } from "./external-continuation";
+import { requireManagedHumanPrivateSessionCreate } from "./session-tenancy";
+
+export { ArchivedSessionImportError } from "@opengeni/db";
+
+function requireImportAuthorization(
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  permission: Permission,
+) {
+  const grant = requireResolvedAccessGrantAuthorization(authorization, workspaceId);
+  requirePermission(grant, permission);
+  if (grantHasAgentAttemptAuthority(grant)) {
+    throw new HTTPException(403, {
+      message: "Session history imports require a user or service request",
+    });
+  }
+  return grant;
+}
+
+function importerScope(
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  permission: Permission,
+  fileOwnerSubjectId: string | null,
+) {
+  const grant = authorization.grant;
+  const apiKeyId =
+    grant.principalKind === "api_key" && grant.subjectId.startsWith("api_key:")
+      ? grant.subjectId.slice("api_key:".length)
+      : undefined;
+  const beforeCommit = externalContinuationCommitAuthorizer(authorization);
+  return {
+    accountId: grant.accountId,
+    workspaceId,
+    subjectId: grant.subjectId,
+    fileOwnerSubjectId,
+    requiredPermission: permission,
+    requireLiveSubject:
+      hasVerifiedOwningUserAuthorization(authorization) || authorization.canonicalLocalHumanSession,
+    ...(apiKeyId ? { apiKeyId } : {}),
+    ...(beforeCommit ? { beforeCommit } : {}),
+  };
+}
+
+/** Committed import truth survives unavailable fanout; SSE catch-up repairs it.
+ * Never make a known committed append look failed and invite an unsafe retry. */
+async function publishImportedEvents(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  sessionId: string,
+  events: SessionEvent[],
+): Promise<void> {
+  if (!events.length) return;
+  try {
+    await publishDurableSessionEvents(deps.bus, workspaceId, sessionId, events);
+  } catch {
+    console.warn("[session-import] committed timeline fanout deferred to replay", { sessionId });
+  }
+}
+
+export async function importArchivedSessionForRequest(
+  deps: ApiRouteDeps,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  rawPayload: unknown,
+): Promise<ImportArchivedSessionResponse> {
+  const grant = requireImportAuthorization(authorization, workspaceId, "sessions:create");
+  const payload = ImportArchivedSessionRequest.parse(rawPayload);
+  if (payload.visibility === "user_private") {
+    await requireManagedHumanPrivateSessionCreate(deps, authorization, workspaceId);
+  }
+  const creator = creationInitiatorForGrant(grant);
+  if (!creator.initiator)
+    throw new HTTPException(403, { message: "Import creator is unavailable" });
+  const actor = await fileOwnerContextForAccess(deps, authorization, "sessions:create");
+  const result = await withSessionRlsActorContext(actor, () =>
+    importArchivedSession(deps.db, {
+      ...importerScope(
+        authorization,
+        workspaceId,
+        "sessions:create",
+        actor.privateFileOwnerSubjectId ?? null,
+      ),
+      payload,
+      createdBy: creator.initiator!,
+      createdByContext: creator.context ?? {},
+    }),
+  );
+  await publishImportedEvents(deps, workspaceId, result.session.id, result.events);
+  return ImportArchivedSessionResponse.parse(result);
+}
+
+export async function appendArchivedSessionEventsForRequest(
+  deps: ApiRouteDeps,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  importId: string,
+  rawPayload: unknown,
+): Promise<AppendArchivedSessionEventsResponse> {
+  const grant = requireImportAuthorization(authorization, workspaceId, "sessions:control");
+  const payload = AppendArchivedSessionEventsRequest.parse(rawPayload);
+  const actor = await fileOwnerContextForAccess(deps, authorization, "sessions:control");
+  const result = await withSessionRlsActorContext(actor, async () => {
+    const sessionId = await getArchivedSessionImportId(
+      deps.db,
+      workspaceId,
+      grant.subjectId,
+      importId,
+    );
+    if (!sessionId) throw new ArchivedSessionImportError("SESSION_IMPORT_NOT_FOUND");
+    await requireSessionAuthorization(deps, grant, {
+      sessionId,
+      operation: "session.append",
+      surface: "core",
+    });
+    return appendArchivedSessionEvents(deps.db, {
+      ...importerScope(
+        authorization,
+        workspaceId,
+        "sessions:control",
+        actor.privateFileOwnerSubjectId ?? null,
+      ),
+      importId,
+      sessionId,
+      payload,
+    });
+  });
+  await publishImportedEvents(deps, workspaceId, result.sessionId, result.events);
+  return AppendArchivedSessionEventsResponse.parse(result);
+}

package/src/application/composer-submit.ts

@@ -0,0 +1,77 @@
+import type {
+  AccessGrant,
+  ResourceRef,
+  SubmitComposerDraftRequest,
+  SubmitComposerDraftResponse,
+} from "@opengeni/contracts";
+import type { AccessGrantAuthorization } from "../access";
+import type { AcceptSessionUserMessageDependencies } from "../dependencies";
+import { acceptSessionUserMessageWithOutcome } from "../domain/sessions";
+
+export type SubmitComposerDraftForRequestOptions = {
+  authorization?: AccessGrantAuthorization | undefined;
+  /**
+   * Trusted host-owned resources admitted with this command without writing
+   * them into the actor's browser-visible draft first. The saved draft remains
+   * the exact content fence for actor-owned text, annotations, resources, and
+   * execution policy; these resources participate in the accepted command's
+   * idempotency hash, validation, turn, and durable session resource set.
+   */
+  additionalResources?: ResourceRef[] | undefined;
+};
+
+/**
+ * Atomically accept one established-session composer draft.
+ *
+ * This is the application boundary shared by the stock HTTP adapter and an
+ * in-process embedding host. A host may prepare its own durable business state
+ * before calling this function and project the returned receipt afterward, but
+ * OpenGeni remains the sole authority for draft validation/rotation, event
+ * append, turn creation, routing, and idempotent replay.
+ */
+export async function submitComposerDraftForRequest(
+  deps: AcceptSessionUserMessageDependencies,
+  grant: AccessGrant,
+  workspaceId: string,
+  sessionId: string,
+  input: SubmitComposerDraftRequest,
+  options: SubmitComposerDraftForRequestOptions = {},
+): Promise<SubmitComposerDraftResponse> {
+  const additionalResources = options.additionalResources ?? [];
+  const result = await acceptSessionUserMessageWithOutcome(deps, grant, workspaceId, sessionId, {
+    text: input.text,
+    annotations: input.annotations,
+    modelContext: input.modelContext ?? null,
+    resources: [...input.resources, ...additionalResources],
+    ...(additionalResources.length > 0 ? { composerDraftResources: input.resources } : {}),
+    model: input.model,
+    reasoningEffort: input.reasoningEffort,
+    latencyMode: input.latencyMode,
+    mcpCredentialUpdates: input.mcpCredentialUpdates ?? [],
+    connectionAccounts: input.connectionAccounts,
+
+    ...(input.personalResourceAttachment
+      ? { personalResourceAttachment: input.personalResourceAttachment }
+      : {}),
+    ...(options.authorization ? { authorization: options.authorization } : {}),
+    delivery: input.delivery,
+    origin: "human",
+    expectedDraftRevision: input.expectedDraftRevision,
+    clientEventId: input.clientEventId,
+    ...(input.controlEtag ? { controlEtag: input.controlEtag } : {}),
+  });
+
+  if (!result.draft) {
+    throw new Error("Accepted composer draft submission did not return its next draft");
+  }
+
+  return {
+    accepted: result.accepted,
+    turn: result.turn,
+    draft: result.draft,
+    receipt: result.receipt,
+    routing: result.routing,
+    interruptionCount: result.interruptionCount,
+    replay: result.replay,
+  };
+}

package/src/application/connect-authority.ts

@@ -0,0 +1,77 @@
+import type { Permission } from "@opengeni/contracts";
+import type { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { hasPermission } from "../access";
+import { requireExternalContinuationAuthority } from "./external-continuation";
+import {
+  getWorkspaceGrant,
+  resolveNamedManagedPersonalWorkspaceGrant,
+  lockExternalWorkspaceMembershipLifecycle,
+  withWorkspaceSubjectRls,
+  type Database,
+  lockConnectionSetupKeyAuthority,
+  nestedPostgresSqlState,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+/** Accept only a verified request owner or authenticated server-minted OAuth
+ * state. The callback does not need a browser cookie: it rechecks the stored
+ * principal against current authority before claiming and committing effects. */
+export async function requireConnectOwnerAuthority(
+  db: Database,
+  state: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    personalOwnerVerified?: boolean;
+    externalContinuation?: ExternalActorContinuation;
+  },
+  permission: Permission = "connections:write",
+  origin: ExternalActorContinuation | null = null,
+): Promise<void> {
+  async function requireExternal(continuation: ExternalActorContinuation) {
+    try {
+      await requireExternalContinuationAuthority(db, continuation, state, permission);
+    } catch (error) {
+      const denied =
+        nestedPostgresSqlState(error) === "42501" ||
+        (error instanceof Error && error.message === "External continuation authority unavailable");
+      throw new HTTPException(denied ? 403 : 503, {
+        message: denied
+          ? "Connection origin authority changed"
+          : "Connection origin authority unavailable",
+        cause: error,
+      });
+    }
+  }
+  // Current request authority cannot replace the original restriction. Native
+  // owners may resume their work, but an expired host/link origin still denies.
+  if (origin) await requireExternal(origin);
+  if (state.externalContinuation) {
+    await requireExternal(state.externalContinuation);
+    return;
+  }
+  if (state.subjectId.startsWith("external_user:"))
+    throw new HTTPException(403, { message: "External Connect continuation required" });
+  if (state.subjectId.startsWith("api_key:")) {
+    const authority = await lockConnectionSetupKeyAuthority(db, state);
+    if (!authority || !hasPermission(authority.permissions, permission, authority.permissionMode))
+      throw new HTTPException(403, { message: "Connection API key authority changed" });
+    return;
+  }
+  await withWorkspaceSubjectRls(db, state.workspaceId, state.subjectId, async (tx) => {
+    await lockExternalWorkspaceMembershipLifecycle(tx, state.accountId);
+    const membership = await getWorkspaceGrant(tx, state.subjectId, state.workspaceId);
+    const grant =
+      membership?.accountId === state.accountId
+        ? membership
+        : state.personalOwnerVerified
+          ? await resolveNamedManagedPersonalWorkspaceGrant(tx, state)
+          : null;
+    if (
+      !grant ||
+      grant.accountId !== state.accountId ||
+      !hasPermission(grant.permissions, permission)
+    )
+      throw new HTTPException(403, { message: "Connection owner authority changed" });
+  });
+}

package/src/application/connect-operation.ts

@@ -0,0 +1,80 @@
+import type { ConnectAttempt } from "@opengeni/contracts/connect";
+import { assertOrganizationIntegrationAllowed } from "@opengeni/contracts";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import { integrationKeyForConnectProvider } from "../domain/organization-integration-catalog";
+import {
+  claimConnectOperation,
+  finishConnectOperation,
+  type ConnectActorScope,
+  type ConnectOperationAuthorization,
+  type Database,
+} from "@opengeni/db";
+
+/** Provider result is deliberately not serializable: secrets can remain in its
+ * closure until encrypted credential persistence. Do not retain/log this value. */
+export type PreparedConnectOperation = {
+  commit: (tx: Database, current: ConnectAttempt) => Promise<ConnectAttempt>;
+};
+
+/** Internal provider-adapter boundary, not an HTTP authentication adapter.
+ *
+ * authorize is mandatory, including for a receipt replay. It must validate the
+ * exact saved key/actor/link authority and current permission under database
+ * locks. execute owns provider-specific proof, destination and cancellation.
+ * No remote effects may occur inside authorize or commit.
+ *
+ * A failed execute/authorization/commit keeps the durable claim occupied. It
+ * does not release or retry work whose provider outcome may be unknown.
+ */
+export async function executeConnectOperation(input: {
+  db: Database;
+  scope: ConnectActorScope;
+  attemptId: string;
+  expectedRevision: number;
+  operationId: string;
+  /** Caller computes a stable keyed digest if input contains low-entropy secrets. */
+  inputDigest: string;
+  /** Trusted server adapter classification, never derived from request data.
+   * Cancellation releases pending setup; it acquires no integration authority. */
+  purpose?: "acquisition" | "cancellation";
+  authorize: ConnectOperationAuthorization;
+  execute: (attempt: ConnectAttempt) => Promise<PreparedConnectOperation>;
+}): Promise<ConnectAttempt> {
+  // Snapshot caller-controlled identity before the first asynchronous boundary.
+  const { db, authorize, execute, purpose = "acquisition" } = input;
+  const scope = { ...input.scope };
+  const operation = {
+    attemptId: input.attemptId,
+    expectedRevision: input.expectedRevision,
+    operationId: input.operationId,
+    inputDigest: input.inputDigest,
+    authorize,
+  };
+  const claim = await withOrganizationIntegrationPolicyFence(db, scope, async (tx, policy) =>
+    claimConnectOperation(tx, scope, {
+      ...operation,
+      authorizeAcquisition: async (_tx, attempt) => {
+        if (purpose === "cancellation") return;
+        assertOrganizationIntegrationAllowed(
+          policy,
+          integrationKeyForConnectProvider(attempt.providerId),
+        );
+      },
+    }),
+  );
+  if (claim.status === "replayed") return claim.attempt;
+  const prepared = await execute(structuredClone(claim.attempt));
+  return withOrganizationIntegrationPolicyFence(db, scope, async (tx, policy) =>
+    finishConnectOperation(tx, scope, {
+      ...operation,
+      commit: prepared.commit,
+      authorizeAcquisition: async (_tx, attempt) => {
+        if (purpose === "cancellation") return;
+        assertOrganizationIntegrationAllowed(
+          policy,
+          integrationKeyForConnectProvider(attempt.providerId),
+        );
+      },
+    }),
+  );
+}