@opengeni/core 3.1.2 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "3.1.2",
+  "version": "3.2.2",
   "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.2",
-    "@opengeni/codex": "3.1.2",
-    "@opengeni/config": "3.1.2",
-    "@opengeni/contracts": "3.1.2",
-    "@opengeni/db": "3.1.2",
-    "@opengeni/documents": "3.1.2",
-    "@opengeni/events": "3.1.2",
-    "@opengeni/network": "3.1.2",
-    "@opengeni/observability": "3.1.2",
-    "@opengeni/runtime": "3.1.2",
-    "@opengeni/storage": "3.1.2",
-    "@opengeni/vaults": "3.1.2",
+    "@opengeni/capabilities": "3.2.2",
+    "@opengeni/codex": "3.2.2",
+    "@opengeni/config": "3.2.2",
+    "@opengeni/contracts": "3.2.2",
+    "@opengeni/db": "3.2.2",
+    "@opengeni/documents": "3.2.2",
+    "@opengeni/events": "3.2.2",
+    "@opengeni/network": "3.2.2",
+    "@opengeni/observability": "3.2.2",
+    "@opengeni/runtime": "3.2.2",
+    "@opengeni/storage": "3.2.2",
+    "@opengeni/vaults": "3.2.2",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

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/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;
+}

package/src/domain/vaults/index.ts

@@ -2,6 +2,9 @@
 export { buildMissingSecretAskCard } from "@opengeni/contracts";
 export { isVaultError, VaultError, vaultErrorFromDatabase } from "@opengeni/db";
 export {
+  intersectProviderOperations,
+  providerOperationsForMode,
+  storedProviderOperations,
   toVaultItem,
   toVaultItemSummary,
   toVaultSummary,
@@ -10,6 +13,11 @@ export {
   vaultItemReferences,
   type VaultCallerAuthority,
 } from "./mapping";
+export {
+  effectiveProviderOperations,
+  type ProviderWriteOperation,
+  type ProviderWriteOutcome,
+} from "./provider-writes";
 export {
   chooseSecretCandidate,
   createSecretResolver,

package/src/domain/vaults/mapping.ts

@@ -6,10 +6,12 @@
 import {
   formatSecretReference,
   secretNameKey,
+  VaultProviderOperations,
   type VaultItem,
   type VaultItemField,
   type VaultItemReferences,
   type VaultItemSummary,
+  type VaultMode,
   type VaultSummary,
 } from "@opengeni/contracts";
 import {
@@ -18,6 +20,7 @@ import {
   type VaultItemRow,
   type VaultRow,
 } from "@opengeni/db";
+import { providerVaultFreshness } from "./provider-sync";
 
 /** What the caller may do beyond reading; decided by the route's grant. */
 export type VaultCallerAuthority = {
@@ -27,9 +30,90 @@ export type VaultCallerAuthority = {
   accountAdmin: boolean;
 };
 
+/** No writes at all: what a read-only link or a read-only provider vault allows. */
+export function withoutProviderWrites(
+  operations: VaultProviderOperations,
+): VaultProviderOperations {
+  return {
+    ...operations,
+    createItemTypes: [],
+    updateItem: false,
+    removeField: false,
+    archiveItem: false,
+    archiveKind: "none",
+    deleteItem: false,
+    restoreItem: false,
+    writeFiles: false,
+    createTotp: false,
+    updateTotp: false,
+    createVault: false,
+    restoreFieldHistory: false,
+  };
+}
+
+/** Operations both sides allow (an archive needs both to agree on its kind). */
+export function intersectProviderOperations(
+  left: VaultProviderOperations,
+  right: VaultProviderOperations,
+): VaultProviderOperations {
+  const archiveItem =
+    left.archiveItem &&
+    right.archiveItem &&
+    left.archiveKind === right.archiveKind &&
+    left.archiveKind !== "none";
+  return {
+    createItemTypes: left.createItemTypes.filter(
+      (type) => type !== "passkey" && right.createItemTypes.includes(type),
+    ),
+    updateItem: left.updateItem && right.updateItem,
+    removeField: left.removeField && right.removeField,
+    archiveItem,
+    archiveKind: archiveItem ? left.archiveKind : "none",
+    deleteItem: false,
+    restoreItem: left.restoreItem && right.restoreItem,
+    readFiles: left.readFiles && right.readFiles,
+    writeFiles: left.writeFiles && right.writeFiles,
+    createTotp: left.createTotp && right.createTotp,
+    updateTotp: left.updateTotp && right.updateTotp,
+    createVault: left.createVault && right.createVault,
+    restoreFieldHistory: left.restoreFieldHistory && right.restoreFieldHistory,
+  };
+}
+
+/**
+ * What a linked vault allows: the operations its provider last reported for
+ * it, narrowed by the link mode. Null for hosted vaults and for links not yet
+ * checked since operations were recorded (callers then ask the provider).
+ */
+export function storedProviderOperations(
+  row: Pick<VaultRow, "source" | "mode"> & {
+    providerOperations?: VaultProviderOperations | null;
+  },
+): VaultProviderOperations | null {
+  if (row.source === "opengeni" || !row.providerOperations) return null;
+  // Stored JSON is checked against the contract before it grants anything.
+  const parsed = VaultProviderOperations.safeParse(row.providerOperations);
+  return parsed.success ? providerOperationsForMode(parsed.data, row.mode) : null;
+}
+
+export function providerOperationsForMode(
+  operations: VaultProviderOperations,
+  mode: VaultMode,
+): VaultProviderOperations {
+  const normalized = intersectProviderOperations(operations, operations);
+  return mode === "read_write" ? normalized : withoutProviderWrites(normalized);
+}
+
+function providerAllowsAnyWrite(operations: VaultProviderOperations | null): boolean {
+  if (!operations) return true;
+  return operations.createItemTypes.length > 0 || operations.updateItem || operations.archiveItem;
+}
+
 export function vaultCanWrite(row: VaultRow, authority: VaultCallerAuthority): boolean {
   // Read-write connected vaults are edited through their provider (W5, OP-3).
   if (row.mode !== "read_write" || !authority.write) return false;
+  // A provider that reported no item writes for this vault makes it read-only here too.
+  if (!providerAllowsAnyWrite(storedProviderOperations(row))) return false;
   if (row.ownerKind === "user") return row.ownedByCaller;
   return true;
 }
@@ -47,7 +131,15 @@ export function vaultCanManage(row: VaultRow, authority: VaultCallerAuthority):
   }
 }
 
-export function toVaultSummary(row: VaultRow, authority: VaultCallerAuthority): VaultSummary {
+export function toVaultSummary(
+  row: VaultRow,
+  authority: VaultCallerAuthority,
+  options: { now?: Date; refreshing?: boolean } = {},
+): VaultSummary {
+  const operations = storedProviderOperations(row);
+  const freshness = providerVaultFreshness(row, options.now ?? new Date(), {
+    ...(options.refreshing ? { refreshing: true } : {}),
+  });
   return {
     id: row.id,
     workspaceId: row.workspaceId,
@@ -64,6 +156,8 @@ export function toVaultSummary(row: VaultRow, authority: VaultCallerAuthority):
     lastSyncedAt: row.lastSyncedAt,
     rateLimitedUntil: row.rateLimitedUntil,
     providerConnectionId: row.providerConnectionId,
+    ...(operations ? { providerOperations: operations } : {}),
+    ...(freshness ? { freshness } : {}),
     availability: row.availability,
     isDefault: row.isDefault,
     itemCount: Number(row.itemCount),

package/src/domain/vaults/provider-registry.ts

@@ -12,7 +12,12 @@ import {
   type VaultProvider,
   type VaultProviderErrorCode,
   type VaultProviderRegistry,
+  type VaultProviderAuthority,
 } from "@opengeni/vaults";
+import {
+  externalVaultProviderForConnection,
+  type ExternalVaultProviderFactories,
+} from "./external-provider-connections";
 
 /**
  * Provider error codes as vault API error codes (§10B.1.1). `provider_not_found`
@@ -170,6 +175,8 @@ export function createWorkspaceVaultProviderRegistry(input: {
   subjectId: string | null;
   hostVaultProvider?: VaultProvider | null;
   onePasswordVaultProvider?: OnePasswordVaultProviderFactory | null;
+  externalVaultProviders?: ExternalVaultProviderFactories | null;
+  executionContext?: Pick<VaultProviderAuthority, "sessionId" | "turnId" | "attemptId" | "siteId">;
 }): VaultProviderRegistry {
   const factory = input.onePasswordVaultProvider;
   const host = input.hostVaultProvider;
@@ -197,5 +204,27 @@ export function createWorkspaceVaultProviderRegistry(input: {
         }
       : {}),
     ...(host ? { host: async () => host } : {}),
+    ...Object.fromEntries(
+      Object.entries(input.externalVaultProviders ?? {}).map(([provider, providerFactory]) => [
+        provider,
+        async (connectionId: string | null) => {
+          if (!connectionId || !providerFactory)
+            throw new VaultProviderError(
+              "provider_unavailable",
+              "This vault has no available connection.",
+            );
+          return externalVaultProviderForConnection({
+            db: input.db,
+            settings: input.settings,
+            workspaceId: input.workspaceId,
+            subjectId: input.subjectId,
+            connectionId,
+            provider: provider as keyof ExternalVaultProviderFactories,
+            factory: providerFactory,
+            ...(input.executionContext ? { executionContext: input.executionContext } : {}),
+          });
+        },
+      ]),
+    ),
   });
 }