@opengeni/db 4.2.2 → 4.3.0-canary.0

package/src/connect-attempts.ts

@@ -0,0 +1,317 @@
+import { createHash } from "node:crypto";
+import { sql } from "drizzle-orm";
+import { ConnectAttempt, type ConnectAttempt as Attempt } from "@opengeni/contracts/connect";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { stableJson } from "@opengeni/contracts";
+import { rawRows, withWorkspaceSubjectRls, type Database } from "./database";
+
+export type ConnectActorScope = { accountId: string; workspaceId: string; subjectId: string };
+/** Live admission under the attempt transaction. Implementations must acquire
+ * their key/membership/link fences in a consistent order and hold them through
+ * commit. No network I/O. The attempt argument is an isolated copy. */
+export type ConnectOperationAuthorization = (
+  tx: Database,
+  attempt: Attempt,
+  origin: ExternalActorContinuation | null,
+) => Promise<void>;
+type Receipt = { digest: string; result: Attempt };
+type Row = {
+  id: string;
+  account_id: string;
+  workspace_id: string;
+  subject_id: string;
+  request_digest: string;
+  return_url: string;
+  projection: unknown;
+  operation_id: string | null;
+  operation_digest: string | null;
+  receipts: Record<string, Receipt>;
+  external_continuation: unknown;
+};
+
+export class ConnectAttemptConflictError extends Error {
+  readonly code = "CONNECT_ATTEMPT_CONFLICT";
+  constructor(message = "Connect attempt changed; reload its current state") {
+    super(message);
+  }
+}
+export class ConnectAttemptNotFoundError extends Error {
+  readonly code = "CONNECT_ATTEMPT_NOT_FOUND";
+  constructor() {
+    super("Connect attempt not found");
+  }
+}
+
+function projection(row: Row, scope: ConnectActorScope): Attempt {
+  const value = ConnectAttempt.parse(row.projection);
+  if (
+    row.account_id !== scope.accountId ||
+    row.workspace_id !== scope.workspaceId ||
+    row.subject_id !== scope.subjectId ||
+    value.id !== row.id ||
+    value.workspaceId !== scope.workspaceId
+  ) {
+    throw new ConnectAttemptNotFoundError();
+  }
+  return value;
+}
+function scoped<T>(
+  db: Database,
+  scope: ConnectActorScope,
+  run: (tx: Database) => Promise<T>,
+): Promise<T> {
+  return withWorkspaceSubjectRls(db, scope.workspaceId, scope.subjectId, run);
+}
+async function lockAttempt(
+  tx: Database,
+  scope: ConnectActorScope,
+  id: string,
+): Promise<Row & { expired: boolean }> {
+  const [row] = await rawRows<Row & { expired: boolean }>(
+    tx,
+    sql`select *, expires_at <= clock_timestamp() as expired from connect_attempts
+    where id = ${id}::uuid and account_id = ${scope.accountId}::uuid
+      and workspace_id = ${scope.workspaceId}::uuid and subject_id = ${scope.subjectId}
+    for update`,
+  );
+  if (!row) throw new ConnectAttemptNotFoundError();
+  return row;
+}
+
+function receiptFor(
+  row: Row,
+  operationId: string,
+  digest: string,
+  scope: ConnectActorScope,
+): Attempt | null {
+  if (!Object.hasOwn(row.receipts, operationId)) return null;
+  const receipt = row.receipts[operationId]!;
+  if (receipt.digest !== digest)
+    throw new ConnectAttemptConflictError("Connect operation ID was reused");
+  return projection({ ...row, projection: receipt.result }, scope);
+}
+function validateOperation(id: string, digest: string): void {
+  if (!id || new TextEncoder().encode(id).byteLength > 512 || !/^[0-9a-f]{64}$/.test(digest)) {
+    throw new ConnectAttemptConflictError("Invalid Connect operation identity");
+  }
+}
+
+/** Caller must establish live workspace/actor authority before this storage
+ * seam. RLS scope is a consistency boundary, not proof of authentication. */
+export async function beginConnectAttempt(
+  db: Database,
+  scope: ConnectActorScope,
+  input: {
+    idempotencyKey: string;
+    requestDigest: string;
+    returnUrl: string;
+    attempt: Attempt;
+    externalContinuation?: ExternalActorContinuation;
+  },
+): Promise<Attempt> {
+  const value = ConnectAttempt.parse(input.attempt);
+  const origin = input.externalContinuation
+    ? ExternalActorContinuation.parse(input.externalContinuation)
+    : null;
+  validateOperation(input.idempotencyKey, input.requestDigest);
+  if (value.workspaceId !== scope.workspaceId || value.revision !== 1)
+    throw new ConnectAttemptConflictError();
+  const key = createHash("sha256").update(input.idempotencyKey).digest("hex");
+  return scoped(db, scope, async (tx) => {
+    // Serialize per-actor creation and quota, not the provider's remote request.
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(
+      ${`connect:${scope.workspaceId}:${scope.subjectId}`}, 0))`);
+    // Bounded actor-local cleanup; no Connection credentials are deleted.
+    await tx.execute(sql`with expired as (
+      select id from connect_attempts where workspace_id = ${scope.workspaceId}::uuid
+        and account_id = ${scope.accountId}::uuid and subject_id = ${scope.subjectId}
+        and expires_at < now() - interval '30 days'
+      order by expires_at, id limit 100 for update skip locked
+    ) delete from connect_attempts where id in (select id from expired)`);
+    const [existing] = await rawRows<Row>(
+      tx,
+      sql`select * from connect_attempts
+      where workspace_id = ${scope.workspaceId}::uuid and subject_id = ${scope.subjectId}
+        and idempotency_key_hash = ${key} and account_id = ${scope.accountId}::uuid`,
+    );
+    if (existing) {
+      if (
+        existing.request_digest !== input.requestDigest ||
+        existing.return_url !== input.returnUrl ||
+        stableJson(existing.external_continuation ?? null) !== stableJson(origin)
+      ) {
+        throw new ConnectAttemptConflictError(
+          "Connect idempotency key was reused with different input",
+        );
+      }
+      return projection(existing, scope);
+    }
+    const [count] = await rawRows<{ count: number }>(
+      tx,
+      sql`select count(*)::int as count from connect_attempts
+      where workspace_id = ${scope.workspaceId}::uuid and subject_id = ${scope.subjectId}
+        and (expires_at > now() or operation_id is not null)
+        and projection->>'state' not in ('complete','cancelled','expired')`,
+    );
+    if ((count?.count ?? 0) >= 32)
+      throw new ConnectAttemptConflictError("Too many pending Connect attempts");
+    const [row] = await rawRows<Row>(
+      tx,
+      sql`insert into connect_attempts
+      (id, account_id, workspace_id, subject_id, idempotency_key_hash, request_digest, return_url, projection, expires_at, external_continuation)
+      values (${value.id}::uuid, ${scope.accountId}::uuid, ${scope.workspaceId}::uuid, ${scope.subjectId},
+        ${key}, ${input.requestDigest}, ${input.returnUrl}, ${JSON.stringify(value)}::jsonb, ${value.expiresAt}::timestamptz, ${origin ? JSON.stringify(origin) : null}::jsonb)
+      returning *`,
+    );
+    if (!row) throw new Error("Connect attempt insert returned no result");
+    return projection(row, scope);
+  });
+}
+
+export async function getConnectAttempt(
+  db: Database,
+  scope: ConnectActorScope,
+  id: string,
+): Promise<{
+  attempt: Attempt;
+  returnUrl: string;
+  operationInFlight: boolean;
+}> {
+  return scoped(db, scope, async (tx) => {
+    const row = await lockAttempt(tx, scope, id);
+    const current = projection(row, scope);
+    if (row.expired && !["complete", "cancelled", "expired", "uncertain"].includes(current.state)) {
+      const expired = ConnectAttempt.parse({
+        ...current,
+        revision: current.revision + 1,
+        state: row.operation_id ? "uncertain" : "expired",
+        nextAction: { type: "none" },
+      });
+      await tx.execute(sql`update connect_attempts set projection = ${JSON.stringify(expired)}::jsonb,
+        updated_at = now() where id = ${row.id}::uuid`);
+      row.projection = expired;
+    }
+    return {
+      attempt: projection(row, scope),
+      returnUrl: row.return_url,
+      operationInFlight: row.operation_id !== null,
+    };
+  });
+}
+
+export async function listPendingConnectAttempts(
+  db: Database,
+  scope: ConnectActorScope,
+): Promise<Attempt[]> {
+  return scoped(db, scope, async (tx) => {
+    const rows = await rawRows<Row>(
+      tx,
+      sql`select * from connect_attempts
+      where workspace_id = ${scope.workspaceId}::uuid and account_id = ${scope.accountId}::uuid
+        and subject_id = ${scope.subjectId} and (expires_at > now() or operation_id is not null)
+        and projection->>'state' not in ('complete','cancelled','expired')
+      order by created_at desc, id desc limit 32`,
+    );
+    return rows.map((row) => projection(row, scope));
+  });
+}
+
+/** A claim is committed before remote effects. Never expire/reclaim it merely
+ * because the caller timed out: the provider may have accepted the operation. */
+export async function claimConnectOperation(
+  db: Database,
+  scope: ConnectActorScope,
+  input: {
+    attemptId: string;
+    expectedRevision: number;
+    operationId: string;
+    inputDigest: string;
+    authorize?: ConnectOperationAuthorization;
+  },
+): Promise<{ status: "claimed"; attempt: Attempt } | { status: "replayed"; attempt: Attempt }> {
+  validateOperation(input.operationId, input.inputDigest);
+  return scoped(db, scope, async (tx) => {
+    const row = await lockAttempt(tx, scope, input.attemptId);
+    const current = projection(row, scope);
+    await input.authorize?.(
+      tx,
+      structuredClone(current),
+      row.external_continuation ? ExternalActorContinuation.parse(row.external_continuation) : null,
+    );
+    const receipt = receiptFor(row, input.operationId, input.inputDigest, scope);
+    if (receipt) {
+      return { status: "replayed", attempt: receipt };
+    }
+    if (row.operation_id)
+      throw new ConnectAttemptConflictError(
+        "Connect operation is in flight or uncertain; reconcile before retrying",
+      );
+    if (
+      Object.keys(row.receipts).length >= 64 ||
+      current.revision !== input.expectedRevision ||
+      row.expired ||
+      ["complete", "cancelled", "expired"].includes(current.state)
+    ) {
+      throw new ConnectAttemptConflictError();
+    }
+    await tx.execute(sql`update connect_attempts set operation_id = ${input.operationId},
+      operation_digest = ${input.inputDigest}, updated_at = now() where id = ${row.id}::uuid`);
+    return { status: "claimed", attempt: current };
+  });
+}
+
+/** Pass the same transaction to credential/installation persistence through
+ * commit so its receipt and the public setup result become visible atomically.
+ * Do not perform network effects inside commit. */
+export async function finishConnectOperation(
+  db: Database,
+  scope: ConnectActorScope,
+  input: {
+    attemptId: string;
+    operationId: string;
+    inputDigest: string;
+    commit: (tx: Database, current: Attempt) => Promise<Attempt>;
+    authorize?: ConnectOperationAuthorization;
+  },
+): Promise<Attempt> {
+  validateOperation(input.operationId, input.inputDigest);
+  return scoped(db, scope, async (tx) => {
+    const row = await lockAttempt(tx, scope, input.attemptId);
+    const current = projection(row, scope);
+    await input.authorize?.(
+      tx,
+      structuredClone(current),
+      row.external_continuation ? ExternalActorContinuation.parse(row.external_continuation) : null,
+    );
+    const receipt = receiptFor(row, input.operationId, input.inputDigest, scope);
+    if (receipt) {
+      return receipt;
+    }
+    if (row.operation_id !== input.operationId || row.operation_digest !== input.inputDigest)
+      throw new ConnectAttemptConflictError();
+    const next = ConnectAttempt.parse(await input.commit(tx, structuredClone(current)));
+    if (
+      next.id !== current.id ||
+      next.workspaceId !== current.workspaceId ||
+      next.providerId !== current.providerId ||
+      next.ownership !== current.ownership ||
+      next.completionRequirement !== current.completionRequirement ||
+      stableJson(next.installationTarget ?? null) !==
+        stableJson(current.installationTarget ?? null) ||
+      (current.source !== undefined && stableJson(next.source) !== stableJson(current.source)) ||
+      next.expiresAt !== current.expiresAt ||
+      next.revision !== current.revision + 1 ||
+      (current.credentialsCommitted && !next.credentialsCommitted) ||
+      (current.integrationInstalled && !next.integrationInstalled)
+    )
+      throw new ConnectAttemptConflictError();
+    const receipts = {
+      ...row.receipts,
+      [input.operationId]: { digest: input.inputDigest, result: next },
+    };
+    await tx.execute(sql`update connect_attempts set projection = ${JSON.stringify(next)}::jsonb,
+      receipts = ${JSON.stringify(receipts)}::jsonb, operation_id = null, operation_digest = null,
+      updated_at = now() where id = ${row.id}::uuid`);
+    return next;
+  });
+}

package/src/connection-authority.ts

@@ -14,6 +14,7 @@ import {
   type UserResourceDelegation,
 } from "@opengeni/contracts";
 import { sql } from "drizzle-orm";
+import { getExternalLinkTurnAuthorization } from "./external-link-work";
 import { rawRows, setSubjectRlsContext, withRlsContext, type Database } from "./database";
 import {
   issueSelfUserResourceGrant,
@@ -218,6 +219,14 @@ export async function resolveAcceptedConnectionUse(
     db,
     { accountId: input.accountId, workspaceId: input.workspaceId },
     async (scopedDb) => {
+      const linked = await getExternalLinkTurnAuthorization(scopedDb, input, input.turnId);
+      if (
+        linked &&
+        (!linked.authorized ||
+          (!linked.permissions.includes("connections:read") &&
+            !linked.permissions.includes("workspace:admin")))
+      )
+        return { status: "denied", reason: "grant_status_inactive" };
       const [row] = await rawRows<{
         authorizationStatus: "authorized" | "denied";
         denialReason: string | null;

package/src/connection-setup-authority.ts

@@ -0,0 +1,35 @@
+import { sql } from "drizzle-orm";
+import { Permission } from "@opengeni/contracts";
+import { rawRows, withRlsContext, type Database } from "./database";
+
+/** Callback authority for a server-signed API-key principal. No bearer is stored
+ * in OAuth state. Organization keys remain shared-workspace-only; workspace keys
+ * remain bound to their original workspace. Hold the row lock through commit. */
+export async function lockConnectionSetupKey(
+  db: Database,
+  input: { accountId: string; workspaceId: string; subjectId: string },
+): Promise<Permission[] | null> {
+  const match = /^api_key:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i.exec(
+    input.subjectId,
+  );
+  if (!match) return null;
+  return withRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (tx) => {
+      const [row] = await rawRows<{ permissions: unknown }>(
+        tx,
+        sql`
+      select k.permissions from api_keys k join workspaces w
+        on w.id = ${input.workspaceId}::uuid and w.account_id = k.account_id
+      where k.id = ${match[1]}::uuid and k.account_id = ${input.accountId}::uuid
+        and k.revoked_at is null and (k.expires_at is null or k.expires_at > clock_timestamp())
+        and get_workspace_kind(w.account_id, w.id) = 'shared'
+        and ((k.workspace_id is null and k.credential_kind = 'organization')
+          or k.workspace_id = w.id)
+      for share of k`,
+      );
+      return row ? Permission.array().parse(row.permissions) : null;
+    },
+  );
+}

package/src/connection-token-resolver.ts

@@ -11,6 +11,9 @@ import type {
   McpConnectionResourceScope,
   McpCredentialAuthNeededReason,
   McpCredentialsRequest,
+  McpCredentialResolution,
+  McpGatewayCredentialsRequest,
+  McpGatewayCredentialResolution,
   TurnInitiator,
   TurnInitiatorContext,
 } from "@opengeni/contracts";
@@ -183,6 +186,11 @@ export type HostMcpCredentialResolverContext = {
   initiator: TurnInitiator;
   initiatorContext: TurnInitiatorContext;
   surface: McpCredentialsRequest["surface"];
+  /** Backend-owned attempt liveness, independent of binding delegation. */
+  authorizeExecution?: (request: McpCredentialsRequest) => Promise<boolean>;
+  /** Backend-owned live validator. Never populate from caller JSON or a host
+   * credential response. Omission denies every explicit durable reference. */
+  authorizeDurableBinding?: (request: McpCredentialsRequest) => Promise<boolean>;
 };
 
 export class HostMcpCredentialScopeError extends Error {
@@ -247,8 +255,15 @@ function isOfficialGmailRestDestination(
  */
 export function buildHostConnectionTokenResolver(
   resolve: NonNullable<ConnectionCredentialsPort["mcpCredentials"]>,
-  context: HostMcpCredentialResolverContext,
+  suppliedContext: HostMcpCredentialResolverContext,
 ): (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult> {
+  // Bind the accepted execution once. A caller retaining its constructor
+  // object must not retarget later requests or replace the post-use validator.
+  const context: HostMcpCredentialResolverContext = {
+    ...suppliedContext,
+    initiator: structuredClone(suppliedContext.initiator),
+    initiatorContext: structuredClone(suppliedContext.initiatorContext),
+  };
   return async (input) => {
     if (input.workspaceId !== context.workspaceId) {
       throw new HostMcpCredentialScopeError("workspaceId");
@@ -281,6 +296,9 @@ export function buildHostConnectionTokenResolver(
         ...(input.connectionRef.authoritySource
           ? { authoritySource: input.connectionRef.authoritySource }
           : {}),
+        ...(input.connectionRef.hostBinding
+          ? { hostBinding: { ...input.connectionRef.hostBinding } }
+          : {}),
         ...(input.connectionRef.provider ? { provider: input.connectionRef.provider } : {}),
         ...(input.connectionRef.connectionId
           ? { connectionId: input.connectionRef.connectionId }
@@ -305,62 +323,173 @@ export function buildHostConnectionTokenResolver(
       ...(toolName ? { toolName } : {}),
       ...(input.subjectId ? { callerSubjectId: input.subjectId } : {}),
     };
-    const result = await resolve(request);
-    assertHostMcpCredentialScope(result, context);
-    assertHostMcpCredentialBinding(result, input.connectionRef);
-    if (result.status === "auth_needed") {
-      const authorizationUrl = normalizedAuthorizationUrl(result.authorizationUrl);
-      return {
-        status: "auth_needed",
-        reason: result.reason,
-        providerDomain: result.providerDomain,
-        authoritySource: "host",
-        ...(result.provider ? { provider: result.provider } : {}),
-        ...(result.connectionId ? { connectionId: result.connectionId } : {}),
-        ...(result.scopes ? { scopes: [...result.scopes] } : {}),
-        ...(result.resource ? { resource: result.resource } : {}),
-        ...(result.selectedResources
-          ? { selectedResources: copySelectedResources(result.selectedResources) }
-          : {}),
-        ...(authorizationUrl ? { authorizationUrl } : {}),
-      };
+    const snapshot = structuredClone(request);
+    const requestedRef = structuredClone(input.connectionRef);
+    const credentialTarget = input.credentialTarget ?? "mcp";
+    const durableDenial = (
+      reason: McpCredentialAuthNeededReason,
+    ): ResolveConnectionCredentialResult => ({
+      status: "auth_needed",
+      reason,
+      providerDomain: requestedRef.providerDomain,
+      authoritySource: "host",
+      ...(requestedRef.connectionId ? { connectionId: requestedRef.connectionId } : {}),
+    });
+    const authorized = async () => {
+      try {
+        if (
+          context.authorizeExecution &&
+          !(await context.authorizeExecution(structuredClone(snapshot)))
+        )
+          return "resource_scope_unavailable" as const;
+        if (
+          requestedRef.hostBinding &&
+          !(await context.authorizeDurableBinding?.(structuredClone(snapshot)))
+        )
+          return "personal_authority_unavailable" as const;
+        return null;
+      } catch {
+        return "refresh_failed" as const;
+      }
+    };
+    if (requestedRef.hostBinding && !context.authorizeDurableBinding)
+      return durableDenial("unsupported_auth");
+    const requiresAuthorization = Boolean(requestedRef.hostBinding || context.authorizeExecution);
+    if (requiresAuthorization) {
+      const denial = await authorized();
+      if (denial) return durableDenial(denial);
     }
-    if (result.connectionId.length === 0) {
-      throw new Error("host MCP credential returned an empty connectionId");
+    const result = await resolve(structuredClone(snapshot));
+    if (requiresAuthorization) {
+      const denial = await authorized();
+      if (denial) return durableDenial(denial);
     }
-    const explicitPlacements =
-      result.placements === undefined
-        ? undefined
-        : normalizedCredentialPlacements(result.placements);
-    const headers = normalizedHostCredentialHeaders(
-      result.headers,
-      explicitPlacements !== undefined,
-    );
-    if (explicitPlacements) {
-      if (!sameHeaderMap(headers, headerMapForPlacements(explicitPlacements))) {
-        throw new HostMcpCredentialBindingError("credentialPlacements");
-      }
-      if (
-        (input.credentialTarget ?? "mcp") !== "http_api" &&
-        explicitPlacements.some((placement) => placement.carrier !== "header")
-      ) {
-        throw new HostMcpCredentialBindingError("credentialPlacements");
-      }
+    assertHostMcpCredentialScope(result, context);
+    const normalized = normalizeHostCredentialResolution(result, requestedRef, credentialTarget);
+    return normalized.status === "ok" && requiresAuthorization
+      ? { ...normalized, authorizeProviderRequest: async () => (await authorized()) === null }
+      : normalized;
+  };
+}
+
+/** Authenticated request-time adapter. No synthetic session/turn authority and
+ * no durable binding admission; every physical use must retain live API proof. */
+export function buildHostGatewayConnectionTokenResolver(
+  resolve: NonNullable<ConnectionCredentialsPort["mcpGatewayCredentials"]>,
+  suppliedContext: Pick<McpGatewayCredentialsRequest, "accountId" | "workspaceId" | "authority">,
+  reauthorize: () => Promise<void>,
+): (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult> {
+  const context = structuredClone(suppliedContext);
+  return async (input) => {
+    const ref = structuredClone(input.connectionRef);
+    const deny = (reason: McpCredentialAuthNeededReason): ResolveConnectionCredentialResult => ({
+      status: "auth_needed",
+      reason,
+      authoritySource: "host",
+      providerDomain: ref.providerDomain,
+      ...(ref.connectionId ? { connectionId: ref.connectionId } : {}),
+    });
+    if (input.workspaceId !== context.workspaceId)
+      throw new HostMcpCredentialScopeError("workspaceId");
+    if (ref.authoritySource !== "host" || ref.hostBinding) return deny("unsupported_auth");
+    const destinationUrl = canonicalHttpUrl(input.destinationUrl);
+    if (
+      !destinationUrl ||
+      (!destinationHostMatchesProvider(destinationUrl, ref.providerDomain) &&
+        !isOfficialGmailRestDestination(destinationUrl, ref))
+    )
+      throw new HostMcpCredentialBindingError("destinationUrl");
+    const request: McpGatewayCredentialsRequest = {
+      ...structuredClone(context),
+      surface: "workspace_gateway",
+      requestId: crypto.randomUUID(),
+      destinationUrl,
+      credentialTarget: input.credentialTarget ?? "mcp",
+      serverId: input.serverId,
+      connectionRef: ref,
+      forceRefresh: input.forceRefresh === true,
+      ...((input.toolName ?? input.toolId) ? { toolName: input.toolName ?? input.toolId } : {}),
+    };
+    await reauthorize();
+    const result = await resolve(structuredClone(request));
+    await reauthorize();
+    for (const field of ["accountId", "workspaceId", "requestId"] as const) {
+      if (result[field] !== request[field])
+        throw new Error(`host gateway credential ${field} scope mismatch`);
     }
-    const expiresAt = parseHostCredentialExpiry(result.expiresAt);
+    const normalized = normalizeHostCredentialResolution(
+      result,
+      ref,
+      request.credentialTarget ?? "mcp",
+    );
+    if (normalized.status !== "ok") return normalized;
     return {
-      status: "ok",
-      headers,
+      ...normalized,
+      authorizeProviderRequest: async () => {
+        try {
+          await reauthorize();
+          return true;
+        } catch {
+          return false;
+        }
+      },
+    };
+  };
+}
+
+function normalizeHostCredentialResolution(
+  result: McpCredentialResolution | McpGatewayCredentialResolution,
+  requestedRef: McpServerConnectionRef,
+  credentialTarget: "mcp" | "http_api",
+): ResolveConnectionCredentialResult {
+  assertHostMcpCredentialBinding(result, requestedRef);
+  if (result.status === "auth_needed") {
+    const authorizationUrl = normalizedAuthorizationUrl(result.authorizationUrl);
+    return {
+      status: "auth_needed",
+      reason: result.reason,
+      providerDomain: result.providerDomain,
       authoritySource: "host",
-      ...(explicitPlacements ? { placements: explicitPlacements } : {}),
-      connectionId: result.connectionId,
-      ...(expiresAt !== undefined ? { expiresAt } : {}),
+      ...(result.provider ? { provider: result.provider } : {}),
+      ...(result.connectionId ? { connectionId: result.connectionId } : {}),
+      ...(result.scopes ? { scopes: [...result.scopes] } : {}),
+      ...(result.resource ? { resource: result.resource } : {}),
+      ...(result.selectedResources
+        ? { selectedResources: copySelectedResources(result.selectedResources) }
+        : {}),
+      ...(authorizationUrl ? { authorizationUrl } : {}),
     };
+  }
+  if (result.connectionId.length === 0) {
+    throw new Error("host MCP credential returned an empty connectionId");
+  }
+  const explicitPlacements =
+    result.placements === undefined ? undefined : normalizedCredentialPlacements(result.placements);
+  const headers = normalizedHostCredentialHeaders(result.headers, explicitPlacements !== undefined);
+  if (explicitPlacements) {
+    if (!sameHeaderMap(headers, headerMapForPlacements(explicitPlacements))) {
+      throw new HostMcpCredentialBindingError("credentialPlacements");
+    }
+    if (
+      credentialTarget !== "http_api" &&
+      explicitPlacements.some((placement) => placement.carrier !== "header")
+    ) {
+      throw new HostMcpCredentialBindingError("credentialPlacements");
+    }
+  }
+  const expiresAt = parseHostCredentialExpiry(result.expiresAt);
+  return {
+    status: "ok",
+    headers,
+    authoritySource: "host",
+    ...(explicitPlacements ? { placements: explicitPlacements } : {}),
+    connectionId: result.connectionId,
+    ...(expiresAt !== undefined ? { expiresAt } : {}),
   };
 }
 
 function assertHostMcpCredentialBinding(
-  result: Awaited<ReturnType<NonNullable<ConnectionCredentialsPort["mcpCredentials"]>>>,
+  result: McpCredentialResolution | McpGatewayCredentialResolution,
   requested: McpServerConnectionRef,
 ): void {
   if (result.providerDomain !== requested.providerDomain) {
@@ -446,7 +575,7 @@ function assertHostMcpCredentialScope(
   }
 }
 
-function normalizedHostCredentialHeaders(
+export function normalizedHostCredentialHeaders(
   headers: Record<string, string>,
   allowEmpty = false,
 ): Record<string, string> {