@opengeni/core 3.1.3-canary.38890816741001 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "3.1.3-canary.38890816741001",
+  "version": "3.3.0",
   "description": "Opengeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -50,18 +50,18 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "3.1.3-canary.38890816741001",
-    "@opengeni/codex": "3.1.3-canary.38890816741001",
-    "@opengeni/config": "3.1.3-canary.38890816741001",
-    "@opengeni/contracts": "3.1.3-canary.38890816741001",
-    "@opengeni/db": "3.1.3-canary.38890816741001",
-    "@opengeni/documents": "3.1.3-canary.38890816741001",
-    "@opengeni/events": "3.1.3-canary.38890816741001",
-    "@opengeni/network": "3.1.3-canary.38890816741001",
-    "@opengeni/observability": "3.1.3-canary.38890816741001",
-    "@opengeni/runtime": "3.1.3-canary.38890816741001",
-    "@opengeni/storage": "3.1.3-canary.38890816741001",
-    "@opengeni/vaults": "3.1.3-canary.38890816741001",
+    "@opengeni/capabilities": "3.3.0",
+    "@opengeni/codex": "3.3.0",
+    "@opengeni/config": "3.3.0",
+    "@opengeni/contracts": "3.3.0",
+    "@opengeni/db": "3.3.0",
+    "@opengeni/documents": "3.3.0",
+    "@opengeni/events": "3.3.0",
+    "@opengeni/network": "3.3.0",
+    "@opengeni/observability": "3.3.0",
+    "@opengeni/runtime": "3.3.0",
+    "@opengeni/storage": "3.3.0",
+    "@opengeni/vaults": "3.3.0",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/access/index.ts

@@ -37,6 +37,7 @@ import {
   listWorkspacesForSubject,
   findActiveApiKeyByHash,
   getWorkspaceGrant,
+  subjectHasLiveWorkspaceAuthorityInScope,
   requireWorkspace,
   resolveNamedManagedPersonalWorkspaceGrant,
   type Database,
@@ -216,6 +217,7 @@ const delegatedHumanAuthorizationSchema = z.object({
 
 const delegatedHumanRequests = new WeakMap<Request, DelegatedHumanAuthorization>();
 const delegatedHumanContexts = new WeakMap<AccessContext, DelegatedHumanAuthorization>();
+const verifiedSiteViewerProofs = new WeakSet<DelegatedHumanAuthorization>();
 const delegatedHumanProfileSchema = z.object({
   id: z.string(),
   name: z.string().nullable(),
@@ -283,6 +285,48 @@ export function stampDelegatedHumanAuthorization(
   delegatedHumanRequests.set(request, Object.freeze(proof));
 }
 
+/**
+ * Verified published-Site dispatch only: the caller has verified the signed
+ * gateway, served host and opaque viewer cookie. This is exact-workspace
+ * ownership for session routes, not a console login or a generic Site bearer.
+ * Native people use the existing delegated-human resolver; external owning
+ * users reload their existing membership without provisioning a new identity.
+ */
+export function stampSiteViewerSessionAuthorization(
+  request: Request,
+  input: {
+    organizationId: string;
+    workspaceId: string;
+    subjectId: string;
+    permissions: Permission[];
+  },
+): void {
+  if (input.subjectId.startsWith("user:")) {
+    stampDelegatedHumanAuthorization(request, {
+      ...input,
+      workspaceScope: { kind: "selected", workspaceIds: [input.workspaceId] },
+    });
+    return;
+  }
+  if (delegatedHumanRequests.has(request) || accessResolvedRequests.has(request))
+    throw new HTTPException(403, { message: "request access authorization already resolved" });
+  const parsed = delegatedHumanAuthorizationSchema
+    .extend({
+      subjectId: z
+        .string()
+        .max(1024)
+        .regex(/^external_user:[^\s\u0000-\u001f\u007f]+$/),
+    })
+    .parse({ ...input, workspaceScope: { kind: "selected", workspaceIds: [input.workspaceId] } });
+  if (parsed.workspaceScope.kind !== "selected") throw new Error("Site workspace scope required");
+  Object.freeze(parsed.permissions);
+  Object.freeze(parsed.workspaceScope.workspaceIds);
+  Object.freeze(parsed.workspaceScope);
+  const proof = Object.freeze(parsed);
+  verifiedSiteViewerProofs.add(proof);
+  delegatedHumanRequests.set(request, proof);
+}
+
 /** Token prefix of personal API keys, which act as the person who made them. */
 export const PERSONAL_API_KEY_TOKEN_PREFIX = "ogp_";
 
@@ -1521,6 +1565,62 @@ async function resolveDelegatedHumanAccessContext(
       message: "delegated humans require native organization access",
     });
   }
+  if (verifiedSiteViewerProofs.has(proof)) {
+    const workspaceId =
+      proof.workspaceScope.kind === "selected" && proof.workspaceScope.workspaceIds.length === 1
+        ? proof.workspaceScope.workspaceIds[0]
+        : null;
+    if (!workspaceId)
+      throw new HTTPException(403, { message: "Site viewer workspace unavailable" });
+    const grant = await withWorkspaceSubjectRls(
+      deps.db,
+      workspaceId,
+      proof.subjectId,
+      async (tx) => {
+        if (
+          !(await subjectHasLiveWorkspaceAuthorityInScope(tx, {
+            accountId: proof.organizationId,
+            workspaceId,
+            subjectId: proof.subjectId,
+          }))
+        )
+          return null;
+        return getWorkspaceGrant(tx, proof.subjectId, workspaceId, {
+          principalKind: "human_session",
+        });
+      },
+    );
+    if (!grant || grant.accountId !== proof.organizationId)
+      throw new HTTPException(403, { message: "Site viewer membership unavailable" });
+    const bounded = Object.freeze({
+      ...grant,
+      permissionMode: "explicit" as const,
+      permissions: Object.freeze(
+        explicitPermissions(
+          Permission.options.filter(
+            (permission) =>
+              hasPermission(grant.permissions, permission) &&
+              hasPermission(proof.permissions, permission, "explicit"),
+          ),
+        ),
+      ) as Permission[],
+    });
+    const accountGrant = Object.freeze({
+      accountId: proof.organizationId,
+      subjectId: proof.subjectId,
+      permissions: Object.freeze([] as Permission[]) as Permission[],
+    });
+    const context: AccessContext = Object.freeze({
+      mode: "managed",
+      subjectId: proof.subjectId,
+      accountGrants: Object.freeze([accountGrant]) as AccountGrant[],
+      workspaceGrants: Object.freeze([bounded]) as AccessGrant[],
+      defaultAccountId: proof.organizationId,
+      defaultWorkspaceId: workspaceId,
+    });
+    delegatedHumanContexts.set(context, proof);
+    return context;
+  }
   const userId = proof.subjectId.slice("user:".length);
   const profiles = await getManagedUserProfilesByIds(deps.db, [userId]);
   const parsedProfile = delegatedHumanProfileSchema.safeParse(

package/src/application/site-session-cancellation.ts

@@ -0,0 +1,47 @@
+import { cancelSiteRuntimeConversation, type Database } from "@opengeni/db";
+import {
+  publishDurableSessionEvents,
+  publishDurableWorkspaceControlEvent,
+  type EventBus,
+} from "@opengeni/events";
+import type { SessionWorkflowClient } from "../dependencies";
+
+/** Internal host lifecycle, not a session-read/control API or a viewer grant. */
+export async function cancelPublishedSiteSession(
+  deps: {
+    db: Database;
+    bus: EventBus;
+    workflowClient: Pick<SessionWorkflowClient, "requestSessionWorkflowWakeDispatch">;
+  },
+  input: Parameters<typeof cancelSiteRuntimeConversation>[1],
+) {
+  const result = await cancelSiteRuntimeConversation(deps.db, input);
+  if (!result) return null;
+  // Capture only this command's event envelopes under its transaction witness.
+  // Never re-open private transcript visibility to do post-commit fanout.
+  const bySession = new Map<string, typeof result.events>();
+  for (const event of result.events) {
+    const group = bySession.get(event.sessionId) ?? [];
+    group.push(event);
+    bySession.set(event.sessionId, group);
+  }
+  const effects = await Promise.allSettled([
+    ...[...bySession].map(([sessionId, events]) =>
+      publishDurableSessionEvents(deps.bus, input.workspaceId, sessionId, events),
+    ),
+    ...(result.workspaceEvent
+      ? [publishDurableWorkspaceControlEvent(deps.bus, input.workspaceId, result.workspaceEvent)]
+      : []),
+    ...(result.wakeCount > 0 ? [deps.workflowClient.requestSessionWorkflowWakeDispatch()] : []),
+  ]);
+  if (effects.some((effect) => effect.status === "rejected"))
+    console.warn(
+      "[site-lifecycle] post-commit fanout failed; durable events and wake outbox retained",
+    );
+  return {
+    receiptId: result.receiptId,
+    replay: result.replay,
+    cancelledSessionCount: result.cancelledSessionCount,
+    cancelledTurnCount: result.cancelledTurnCount,
+  };
+}

package/src/dependencies.ts

@@ -12,6 +12,7 @@ import type {
 import type { Database, SessionWorkflowWakeDeliveryResult } from "@opengeni/db";
 import type { VaultConnectionCredentialsPort } from "@opengeni/vaults";
 import type { OnePasswordVaultProviderFactory } from "./domain/vaults/provider-registry";
+import type { ExternalVaultProviderFactories } from "./domain/vaults/external-provider-connections";
 import type { DocumentServices } from "@opengeni/documents";
 import type { EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
@@ -214,6 +215,8 @@ export type AppDependencies = {
    * 1Password vaults report `provider_unavailable`.
    */
   onePasswordVaultProvider?: OnePasswordVaultProviderFactory | null;
+  /** Lazy native/remote vault adapters; null disables the first-wave integrations. */
+  externalVaultProviders?: ExternalVaultProviderFactories | null;
   /**
    * Optional embedding-host session ACL. Unset preserves standalone workspace
    * authorization; once bound, every session-addressed surface fails closed on

package/src/domain/file-owner.ts

@@ -62,6 +62,7 @@ export async function fileOwnerContextForAgent(
     },
     subjectId: grant.subjectId,
     initiatingHumanSubjectId: attempt.initiatingHumanSubjectId,
+    agentRootSessionId: attempt.callerRootSessionId,
     privateFileOwnerSubjectId: snapshot.defaultScope === "personal" ? snapshot.subjectId : null,
   };
 }

package/src/domain/insights-usage.ts

@@ -4,8 +4,27 @@ import type {
   InsightsUsageQuery,
   InsightsUsageRange,
   InsightsUsageResponse,
+  InsightsSiteUsageQuery,
 } from "@opengeni/contracts/insights-usage";
-import { readInsightsCalls, readInsightsUsage, type Database } from "@opengeni/db";
+import {
+  readInsightsCalls,
+  readInsightsUsage,
+  readInsightsSiteUsage,
+  type Database,
+} from "@opengeni/db";
+
+export async function getInsightsSiteUsage(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    query: InsightsSiteUsageQuery;
+    viewerSubjectId: string | null;
+    now?: Date;
+  },
+) {
+  return readInsightsSiteUsage(db, { ...input, now: input.now ?? new Date() });
+}
 
 export type InsightsQueryScope = {
   accountId: string;

package/src/domain/realtime-voice-billing.ts

@@ -340,7 +340,10 @@ export function createRealtimeVoiceBilling(deps: { db: Database; settings: Setti
       }
       const attribution: CreditDebitAttribution =
         input.callerSubjectId === facts.ownerSubjectId ? input.attribution : { kind: "unknown" };
-      const cost = realtimeVoiceMinuteCreditMicros(voice.pricing);
+      const cost = realtimeVoiceMinuteCreditMicros(
+        voice.pricing,
+        deps.settings.creditMarginBpsOverride,
+      );
       const minutes = facts.connections.flatMap((connection) =>
         Array.from(
           { length: realtimeVoiceStartedMinutes(connection.startedAt, connection.observedUntil) },

package/src/domain/vaults/external-provider-connections.ts

@@ -0,0 +1,395 @@
+import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import { isDeepStrictEqual } from "node:util";
+import {
+  ExternalVaultProviderKind,
+  VaultProviderCredentials,
+  VaultProviderOperations,
+  type ConnectionMetadata,
+} from "@opengeni/contracts";
+import {
+  encryptEnvironmentValue,
+  getConnectionMetadata,
+  getProviderConnectionHomeWorkspace,
+  loadConnectionCredentialForBroker,
+  updateConnection,
+  type Database,
+} from "@opengeni/db";
+import {
+  providerOperations,
+  VaultProviderError,
+  type VaultProvider,
+  type VaultProviderAuthority,
+  type VaultProviderContext,
+} from "@opengeni/vaults";
+import { z } from "zod";
+
+export const EXTERNAL_VAULT_CREDENTIAL_ROLE = "external_vault_provider";
+
+const ExternalVaultConnectionDetails = z
+  .object({
+    version: z.literal(1),
+    provider: ExternalVaultProviderKind,
+    ownership: z.enum(["user", "workspace", "organization"]),
+    accountId: z.string().min(1).max(300).nullable(),
+    accountName: z.string().max(300).nullable(),
+    label: z.string().max(120).nullable(),
+    verifiedAt: z.string().datetime(),
+    operations: VaultProviderOperations,
+    verificationStatus: z.enum(["ready", "pending"]).optional(),
+  })
+  .strict();
+export type ExternalVaultConnectionDetails = z.infer<typeof ExternalVaultConnectionDetails>;
+
+export function externalVaultProviderDomain(provider: ExternalVaultProviderKind): string {
+  return `vault:${provider}`;
+}
+
+/** Metadata is a projection, never a credential/configuration passthrough. */
+export function externalVaultConnectionDetails(
+  metadata: Record<string, unknown> | null | undefined,
+): ExternalVaultConnectionDetails | null {
+  if (metadata?.credentialRole !== EXTERNAL_VAULT_CREDENTIAL_ROLE) return null;
+  const result = ExternalVaultConnectionDetails.safeParse(metadata.vaultProvider);
+  return result.success ? result.data : null;
+}
+
+export function isExternalVaultConnection(connection: ConnectionMetadata): boolean {
+  const details = externalVaultConnectionDetails(connection.metadata);
+  return (
+    details !== null &&
+    connection.kind === "api_key" &&
+    connection.providerDomain === externalVaultProviderDomain(details.provider) &&
+    (details.ownership === "user") === (connection.subjectId !== null)
+  );
+}
+
+/** Keeper bootstrap tokens are never a stored runtime credential. */
+export const StoredVaultProviderCredentials = z.union([
+  VaultProviderCredentials.options[0],
+  VaultProviderCredentials.options[1],
+  VaultProviderCredentials.options[2],
+  z
+    .object({
+      provider: z.literal("keeper"),
+      configuration: z
+        .record(z.string().max(100), z.string().max(65_536))
+        .refine((value) => Object.keys(value).length <= 32),
+    })
+    .strict(),
+]);
+export type StoredVaultProviderCredentials = z.infer<typeof StoredVaultProviderCredentials>;
+
+const PendingVaultCredentialEnvelope = z
+  .object({
+    vaultCredentialEnvelope: z.literal(1),
+    current: StoredVaultProviderCredentials.nullable(),
+    pending: StoredVaultProviderCredentials,
+  })
+  .strict();
+
+/** Encrypted only: preserve the working credential while a reconnect is checked. */
+export function pendingVaultCredentialBundle(
+  current: StoredVaultProviderCredentials | null,
+  pending: StoredVaultProviderCredentials,
+): Record<string, unknown> {
+  return { vaultCredentialEnvelope: 1, current, pending };
+}
+
+export type ExternalVaultProviderFactory = (input: {
+  credentials: VaultProviderCredentials | StoredVaultProviderCredentials;
+  /** Stable native connection identity; adapter sessions must not cross it. */
+  connectionId?: string;
+  /** Includes credential binding and setup, before ordinary provider calls. */
+  signal?: AbortSignal;
+  /** Persist any later SDK key rotation before reporting successful readiness. */
+  persistCredentials?: (credentials: StoredVaultProviderCredentials) => Promise<void>;
+  /** Verified setup capabilities; the adapter may narrow, never widen them. */
+  operations?: VaultProviderOperations;
+}) => Promise<{ provider: VaultProvider; credentials: StoredVaultProviderCredentials }>;
+
+export type ExternalVaultProviderFactories = Partial<
+  Record<ExternalVaultProviderKind, ExternalVaultProviderFactory>
+>;
+
+export function externalVaultConnectionMetadata(
+  details: ExternalVaultConnectionDetails,
+): Record<string, unknown> {
+  return {
+    credentialRole: EXTERNAL_VAULT_CREDENTIAL_ROLE,
+    vaultProvider: ExternalVaultConnectionDetails.parse(details),
+  };
+}
+
+function unavailable(): VaultProviderError {
+  return new VaultProviderError(
+    "provider_auth_invalid",
+    "This vault connection was removed or is not available to you. Reconnect it in Vaults.",
+  );
+}
+
+/** Credentials can only be decrypted after the native reach and connection tuple agree. */
+export async function loadExternalVaultConnection(
+  db: Database,
+  settings: Settings,
+  input: {
+    workspaceId: string;
+    connectionId: string;
+    subjectId: string | null;
+    provider: ExternalVaultProviderKind;
+    /** Setup-only recovery, after independent connection-management authorization. */
+    allowPendingVerification?: boolean;
+  },
+): Promise<{
+  connection: ConnectionMetadata;
+  details: ExternalVaultConnectionDetails;
+  credentials: StoredVaultProviderCredentials;
+  currentCredentials: StoredVaultProviderCredentials | null;
+  pendingCredentials: StoredVaultProviderCredentials | null;
+}> {
+  let connection = await getConnectionMetadata(
+    db,
+    input.workspaceId,
+    input.connectionId,
+    input.subjectId,
+  );
+  if (!connection) {
+    const home = await getProviderConnectionHomeWorkspace(
+      db,
+      input.workspaceId,
+      input.connectionId,
+      input.subjectId,
+    );
+    if (home && home !== input.workspaceId)
+      connection = await getConnectionMetadata(db, home, input.connectionId, input.subjectId);
+  }
+  if (!connection || !isExternalVaultConnection(connection)) throw unavailable();
+  const details = externalVaultConnectionDetails(connection.metadata)!;
+  if (details.provider !== input.provider) throw unavailable();
+  if (
+    connection.status !== "active" &&
+    !(
+      input.allowPendingVerification &&
+      (connection.status === "needs_reauth" || connection.status === "error")
+    )
+  )
+    throw new VaultProviderError(
+      "provider_auth_expired",
+      "This vault connection needs to be reconnected.",
+    );
+  if (connection.subjectId !== null && connection.subjectId !== input.subjectId)
+    throw unavailable();
+  const loaded = await loadConnectionCredentialForBroker(db, settings, {
+    workspaceId: connection.workspaceId,
+    connectionId: connection.id,
+    providerDomain: externalVaultProviderDomain(input.provider),
+    kind: "api_key",
+    ...(connection.subjectId !== null
+      ? { allowSubjectOwned: true, subjectId: input.subjectId }
+      : {}),
+  });
+  // The broker decrypts by exact ID, so repeat tuple/status/version checks on
+  // that same read rather than trusting the earlier metadata snapshot.
+  if (
+    !loaded ||
+    loaded.status !== connection.status ||
+    loaded.version !== connection.version ||
+    loaded.accountId !== connection.accountId ||
+    loaded.subjectId !== connection.subjectId ||
+    loaded.providerDomain !== connection.providerDomain ||
+    loaded.kind !== "api_key" ||
+    externalVaultConnectionDetails(loaded.metadata)?.provider !== input.provider
+  )
+    throw unavailable();
+  const envelope = PendingVaultCredentialEnvelope.safeParse(loaded.credential);
+  const raw = envelope.success
+    ? input.allowPendingVerification
+      ? envelope.data.pending
+      : envelope.data.current
+    : loaded.credential;
+  const parsed = StoredVaultProviderCredentials.safeParse(raw);
+  if (!parsed.success || parsed.data.provider !== input.provider) throw unavailable();
+  if (
+    envelope.success &&
+    (envelope.data.pending.provider !== input.provider ||
+      (envelope.data.current !== null && envelope.data.current.provider !== input.provider))
+  )
+    throw unavailable();
+  return {
+    connection,
+    details,
+    credentials: parsed.data,
+    currentCredentials: envelope.success ? envelope.data.current : parsed.data,
+    pendingCredentials: envelope.success ? envelope.data.pending : null,
+  };
+}
+
+/** A bound adapter never accepts model-supplied identity, even via a copied context. */
+export function bindVaultProviderAuthority(
+  provider: VaultProvider,
+  input: {
+    connectionId: string;
+    authority: VaultProviderAuthority;
+    operations: VaultProviderOperations;
+    revalidate: () => Promise<void>;
+  },
+): VaultProvider {
+  async function context(ctx: VaultProviderContext): Promise<VaultProviderContext> {
+    ctx.signal?.throwIfAborted();
+    await input.revalidate();
+    ctx.signal?.throwIfAborted();
+    return { ...ctx, connectionId: input.connectionId, authority: { ...input.authority } };
+  }
+  return {
+    id: provider.id,
+    capabilities: () => ({
+      ...provider.capabilities(),
+      operations: providerOperations(provider.capabilities(), { operations: input.operations }),
+    }),
+    validate: async (ctx) => provider.validate(await context(ctx)),
+    listVaults: async (ctx) => provider.listVaults(await context(ctx)),
+    listItems: async (ctx, vaultId) => provider.listItems(await context(ctx), vaultId),
+    readFields: async (ctx, vaultId, itemId, fields) =>
+      provider.readFields(await context(ctx), vaultId, itemId, fields),
+    writeItem: async (ctx, vaultId, item) => provider.writeItem(await context(ctx), vaultId, item),
+    archiveItem: async (ctx, vaultId, itemId) =>
+      provider.archiveItem(await context(ctx), vaultId, itemId),
+    ...(provider.listVaultPage
+      ? { listVaultPage: async (ctx, page) => provider.listVaultPage!(await context(ctx), page) }
+      : {}),
+    ...(provider.listItemPage
+      ? {
+          listItemPage: async (ctx, vaultId, page) =>
+            provider.listItemPage!(await context(ctx), vaultId, page),
+        }
+      : {}),
+    ...(provider.createVault
+      ? { createVault: async (ctx, value) => provider.createVault!(await context(ctx), value) }
+      : {}),
+  };
+}
+
+export async function externalVaultProviderForConnection(input: {
+  db: Database;
+  settings: Settings;
+  workspaceId: string;
+  subjectId: string | null;
+  connectionId: string;
+  provider: ExternalVaultProviderKind;
+  factory: ExternalVaultProviderFactory;
+  executionContext?: Pick<VaultProviderAuthority, "sessionId" | "turnId" | "attemptId" | "siteId">;
+}): Promise<VaultProvider> {
+  const loaded = await loadExternalVaultConnection(input.db, input.settings, input);
+  let connection = loaded.connection;
+  const prepared = await input.factory({
+    credentials: loaded.credentials,
+    connectionId: connection.id,
+    signal: AbortSignal.timeout(30_000),
+    operations: loaded.details.operations,
+    persistCredentials: async (next) => {
+      const parsed = StoredVaultProviderCredentials.safeParse(next);
+      if (!parsed.success || parsed.data.provider !== loaded.details.provider) throw unavailable();
+      const credentials = parsed.data;
+      const key = environmentsEncryptionKeyBytes(input.settings);
+      if (!key)
+        throw new VaultProviderError(
+          "provider_unavailable",
+          "Vault credential encryption is unavailable.",
+        );
+      const updated = await updateConnection(input.db, {
+        workspaceId: connection.workspaceId,
+        connectionId: connection.id,
+        visibleToSubjectId: input.subjectId,
+        expectedVersion: connection.version,
+        credentialEncrypted: encryptEnvironmentValue(
+          key,
+          JSON.stringify(
+            loaded.pendingCredentials
+              ? pendingVaultCredentialBundle(credentials, loaded.pendingCredentials)
+              : credentials,
+          ),
+        ),
+      });
+      if (updated) {
+        connection = updated;
+        return;
+      }
+      // Another API/worker may already have persisted the identical SDK key
+      // rotation. Reconcile that exact result without retrying a stale write.
+      // Loading again rechecks current reach, status, ownership and credentials.
+      const live = await loadExternalVaultConnection(input.db, input.settings, input);
+      if (
+        isDeepStrictEqual(
+          rotationConnectionIdentity(live.connection),
+          rotationConnectionIdentity(connection),
+        ) &&
+        isDeepStrictEqual(live.currentCredentials, credentials) &&
+        isDeepStrictEqual(live.pendingCredentials, loaded.pendingCredentials)
+      ) {
+        connection = live.connection;
+        return;
+      }
+      throw new VaultProviderError(
+        "provider_conflict",
+        "This vault connection changed while its credentials were renewed.",
+      );
+    },
+  });
+  if (prepared.provider.id !== input.provider) throw unavailable();
+  return bindVaultProviderAuthority(prepared.provider, {
+    connectionId: connection.id,
+    authority: {
+      accountId: connection.accountId,
+      workspaceId: input.workspaceId,
+      connectionWorkspaceId: connection.workspaceId,
+      subjectId: input.subjectId,
+      ...input.executionContext,
+    },
+    operations: loaded.details.operations,
+    revalidate: async () => {
+      // Revalidate cross-workspace reach as well as the exact connection generation.
+      if (connection.workspaceId !== input.workspaceId) {
+        const home = await getProviderConnectionHomeWorkspace(
+          input.db,
+          input.workspaceId,
+          connection.id,
+          input.subjectId,
+        );
+        if (home !== connection.workspaceId) throw unavailable();
+      }
+      const live = await getConnectionMetadata(
+        input.db,
+        connection.workspaceId,
+        connection.id,
+        input.subjectId,
+      );
+      if (
+        !live ||
+        !isExternalVaultConnection(live) ||
+        live.status !== "active" ||
+        live.accountId !== connection.accountId ||
+        live.subjectId !== connection.subjectId ||
+        live.providerDomain !== connection.providerDomain
+      )
+        throw unavailable();
+      if (live.version !== connection.version)
+        throw new VaultProviderError(
+          "provider_conflict",
+          "This vault connection changed. Reload it before starting another operation.",
+        );
+    },
+  });
+}
+
+/** Credential rotation changes generations and observation timestamps, not identity or grants. */
+function rotationConnectionIdentity(connection: ConnectionMetadata) {
+  const {
+    version: _version,
+    connectionAuthorityGeneration: _authorityGeneration,
+    updatedAt: _updatedAt,
+    updatedBySubjectId: _updatedBy,
+    lastUsedAt: _lastUsedAt,
+    lastRefreshAt: _lastRefreshAt,
+    ...identity
+  } = connection;
+  return identity;
+}