@opengeni/db 0.7.3 → 0.9.3

package/src/connection-token-resolver.ts

@@ -3,6 +3,14 @@ import {
   type McpServerConnectionRef,
   type Settings,
 } from "@opengeni/config";
+import type {
+  ConnectionCredentialsPort,
+  McpConnectionResourceScope,
+  McpCredentialAuthNeededReason,
+  McpCredentialsRequest,
+  TurnInitiator,
+  TurnInitiatorContext,
+} from "@opengeni/contracts";
 import { Buffer } from "node:buffer";
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
@@ -20,11 +28,13 @@ export type ResolveConnectionCredentialResult =
   | { status: "ok"; headers: Record<string, string>; connectionId: string; expiresAt?: Date | null }
   | {
       status: "auth_needed";
-      reason: "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed";
+      reason: McpCredentialAuthNeededReason;
       providerDomain: string;
+      provider?: string;
       connectionId?: string;
       scopes?: string[];
       resource?: string;
+      selectedResources?: McpConnectionResourceScope[];
       authorizationUrl?: string;
     };
 type AuthNeededReason = Extract<
@@ -36,11 +46,266 @@ export type ResolveConnectionCredentialInput = {
   workspaceId: string;
   subjectId?: string;
   serverId: string;
+  toolName?: string;
+  /** @deprecated Use toolName. Retained for the API's pre-existing broker call shape. */
   toolId?: string;
   connectionRef: McpServerConnectionRef;
   forceRefresh?: boolean;
 };
 
+export type HostMcpCredentialResolverContext = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  rootSessionId: string;
+  turnId: string;
+  attemptId: string | null;
+  executionGeneration: number;
+  initiator: TurnInitiator;
+  initiatorContext: TurnInitiatorContext;
+  surface: McpCredentialsRequest["surface"];
+};
+
+export class HostMcpCredentialScopeError extends Error {
+  constructor(field: "accountId" | "workspaceId" | "sessionId") {
+    super(`host MCP credential ${field} scope mismatch`);
+    this.name = "HostMcpCredentialScopeError";
+  }
+}
+
+export class HostMcpCredentialBindingError extends Error {
+  constructor(
+    field:
+      | "provider"
+      | "providerDomain"
+      | "connectionId"
+      | "scopes"
+      | "resource"
+      | "selectedResources",
+  ) {
+    super(`host MCP credential ${field} binding mismatch`);
+    this.name = "HostMcpCredentialBindingError";
+  }
+}
+
+/**
+ * Adapts the public embedding credential port to the runtime's connection
+ * resolver contract. Scope echoes are checked before credential headers can
+ * reach a request; the returned object is a fresh copy so a host cannot mutate
+ * headers after resolution.
+ */
+export function buildHostConnectionTokenResolver(
+  resolve: NonNullable<ConnectionCredentialsPort["mcpCredentials"]>,
+  context: HostMcpCredentialResolverContext,
+): (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult> {
+  return async (input) => {
+    if (input.workspaceId !== context.workspaceId) {
+      throw new HostMcpCredentialScopeError("workspaceId");
+    }
+    const toolName = input.toolName ?? input.toolId;
+    const request: McpCredentialsRequest = {
+      accountId: context.accountId,
+      workspaceId: context.workspaceId,
+      sessionId: context.sessionId,
+      rootSessionId: context.rootSessionId,
+      turnId: context.turnId,
+      attemptId: context.attemptId,
+      executionGeneration: context.executionGeneration,
+      initiator: context.initiator,
+      initiatorContext: { ...context.initiatorContext },
+      surface: context.surface,
+      serverId: input.serverId,
+      connectionRef: {
+        providerDomain: input.connectionRef.providerDomain,
+        ...(input.connectionRef.provider ? { provider: input.connectionRef.provider } : {}),
+        ...(input.connectionRef.connectionId
+          ? { connectionId: input.connectionRef.connectionId }
+          : {}),
+        ...(input.connectionRef.kind ? { kind: input.connectionRef.kind } : {}),
+        ...(input.connectionRef.scopes ? { scopes: [...input.connectionRef.scopes] } : {}),
+        ...(input.connectionRef.resource ? { resource: input.connectionRef.resource } : {}),
+        ...(input.connectionRef.selectedResources
+          ? { selectedResources: copySelectedResources(input.connectionRef.selectedResources) }
+          : {}),
+        ...(input.connectionRef.subjectScope
+          ? { subjectScope: input.connectionRef.subjectScope }
+          : {}),
+      },
+      forceRefresh: input.forceRefresh === true,
+      ...(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,
+        ...(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 expiresAt = parseHostCredentialExpiry(result.expiresAt);
+    return {
+      status: "ok",
+      headers: normalizedHostCredentialHeaders(result.headers),
+      connectionId: result.connectionId,
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    };
+  };
+}
+
+function assertHostMcpCredentialBinding(
+  result: Awaited<ReturnType<NonNullable<ConnectionCredentialsPort["mcpCredentials"]>>>,
+  requested: McpServerConnectionRef,
+): void {
+  if (result.providerDomain !== requested.providerDomain) {
+    throw new HostMcpCredentialBindingError("providerDomain");
+  }
+  if (result.provider !== requested.provider) {
+    throw new HostMcpCredentialBindingError("provider");
+  }
+  if (requested.connectionId && result.connectionId !== requested.connectionId) {
+    throw new HostMcpCredentialBindingError("connectionId");
+  }
+  if (!sameSelectedResources(result.selectedResources, requested.selectedResources)) {
+    throw new HostMcpCredentialBindingError("selectedResources");
+  }
+  if (result.status === "ok") {
+    if (!sameStringSet(result.scopes, requested.scopes)) {
+      throw new HostMcpCredentialBindingError("scopes");
+    }
+    if (result.resource !== requested.resource) {
+      throw new HostMcpCredentialBindingError("resource");
+    }
+  }
+}
+
+function sameStringSet(left: string[] | undefined, right: string[] | undefined): boolean {
+  if (left === undefined || right === undefined) return left === right;
+  if (left.length !== right.length) return false;
+  const sortedLeft = [...left].sort();
+  const sortedRight = [...right].sort();
+  return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
+
+function sameSelectedResources(
+  left: McpConnectionResourceScope[] | undefined,
+  right: McpConnectionResourceScope[] | undefined,
+): boolean {
+  if (left === undefined || right === undefined) return left === right;
+  const leftKeys = copySelectedResources(left)
+    .map((resource) => `${resource.kind}\0${resource.id}`)
+    .sort();
+  const rightKeys = copySelectedResources(right)
+    .map((resource) => `${resource.kind}\0${resource.id}`)
+    .sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((value, index) => value === rightKeys[index])
+  );
+}
+
+function copySelectedResources(
+  resources: McpConnectionResourceScope[],
+): McpConnectionResourceScope[] {
+  if (resources.length === 0 || resources.length > 256) {
+    throw new Error("host MCP credential returned an invalid selected resource count");
+  }
+  const seen = new Set<string>();
+  return resources.map((resource) => {
+    if (
+      resource.kind !== "repository" ||
+      typeof resource.id !== "string" ||
+      resource.id.length === 0 ||
+      resource.id.length > 512
+    ) {
+      throw new Error("host MCP credential returned an invalid selected resource");
+    }
+    const key = `${resource.kind}\0${resource.id}`;
+    if (seen.has(key)) {
+      throw new Error("host MCP credential returned duplicate selected resources");
+    }
+    seen.add(key);
+    return { kind: resource.kind, id: resource.id };
+  });
+}
+
+function assertHostMcpCredentialScope(
+  result: { accountId: string; workspaceId: string; sessionId: string },
+  context: HostMcpCredentialResolverContext,
+): void {
+  for (const field of ["accountId", "workspaceId", "sessionId"] as const) {
+    if (result[field] !== context[field]) {
+      throw new HostMcpCredentialScopeError(field);
+    }
+  }
+}
+
+function normalizedHostCredentialHeaders(headers: Record<string, string>): Record<string, string> {
+  const entries = Object.entries(headers);
+  if (entries.length === 0 || entries.length > 32) {
+    throw new Error("host MCP credential returned an invalid header count");
+  }
+  const normalized: Record<string, string> = {};
+  for (const [name, value] of entries) {
+    if (
+      name.length > 256 ||
+      !/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/.test(name) ||
+      value.length === 0 ||
+      value.length > 16_384 ||
+      /[\r\n\0]/.test(value)
+    ) {
+      throw new Error("host MCP credential returned an invalid header");
+    }
+    normalized[name] = value;
+  }
+  return normalized;
+}
+
+function normalizedAuthorizationUrl(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("host MCP credential returned an invalid authorizationUrl");
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) {
+    throw new Error("host MCP credential returned an invalid authorizationUrl");
+  }
+  return url.toString();
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  if (hostname === "localhost" || hostname === "::1") return true;
+  if (isIP(hostname) !== 4) return false;
+  const [first] = hostname.split(".");
+  return first === "127";
+}
+
+function parseHostCredentialExpiry(value: string | null | undefined): Date | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime())) {
+    throw new Error("host MCP credential returned an invalid expiresAt");
+  }
+  return parsed;
+}
+
 export type ConnectionBrokerDeps = {
   loadCredential: typeof loadConnectionCredentialForBroker;
   recordRefresh: typeof recordConnectionTokenRefresh;
@@ -65,6 +330,7 @@ const defaultDeps: ConnectionBrokerDeps = {
 
 const inflight = new Map<string, Promise<ConnectionCredentialForBroker>>();
 const REFRESH_WINDOW_MS = 60_000;
+const CONNECTION_REFRESH_TIMEOUT_MS = 10_000;
 
 export function buildConnectionTokenResolver(
   db: Database,
@@ -105,9 +371,13 @@ export function buildConnectionTokenResolver(
         status: "auth_needed",
         reason: "insufficient_scope",
         providerDomain: ref.providerDomain,
+        ...(ref.provider ? { provider: ref.provider } : {}),
         connectionId: cred.id,
         scopes: missingScopes,
         ...(ref.resource ? { resource: ref.resource } : {}),
+        ...(ref.selectedResources
+          ? { selectedResources: copySelectedResources(ref.selectedResources) }
+          : {}),
       };
     }
     const headers = headersForCredential(cred);
@@ -116,9 +386,13 @@ export function buildConnectionTokenResolver(
         status: "auth_needed",
         reason: "refresh_failed",
         providerDomain: ref.providerDomain,
+        ...(ref.provider ? { provider: ref.provider } : {}),
         connectionId: cred.id,
         ...(ref.scopes ? { scopes: ref.scopes } : {}),
         ...(ref.resource ? { resource: ref.resource } : {}),
+        ...(ref.selectedResources
+          ? { selectedResources: copySelectedResources(ref.selectedResources) }
+          : {}),
       };
     }
     await deps.recordUsed(db, cred.workspaceId, cred.id);
@@ -192,6 +466,13 @@ export function buildConnectionTokenResolver(
 
   return async (input) => {
     const ref = input.connectionRef;
+    // Repository-scoped provider bindings require a broker that can prove the
+    // selected-resource boundary. The generic standalone credential store has
+    // no provider-specific containment adapter, so it must fail closed instead
+    // of handing an account-wide token to the configured endpoint.
+    if (ref.selectedResources) {
+      return authNeeded(ref, "resource_scope_unavailable", ref.connectionId);
+    }
     let cred: ConnectionCredentialForBroker | null;
     try {
       cred = await load(input);
@@ -276,9 +557,13 @@ function authNeeded(
     status: "auth_needed",
     reason,
     providerDomain: ref.providerDomain,
+    ...(ref.provider ? { provider: ref.provider } : {}),
     ...(connectionId ? { connectionId } : {}),
     ...(ref.scopes ? { scopes: ref.scopes } : {}),
     ...(ref.resource ? { resource: ref.resource } : {}),
+    ...(ref.selectedResources
+      ? { selectedResources: copySelectedResources(ref.selectedResources) }
+      : {}),
   };
 }
 
@@ -394,6 +679,7 @@ export async function refreshOAuthConnectionCredential(
     headers,
     body,
     redirect: "manual",
+    signal: AbortSignal.timeout(CONNECTION_REFRESH_TIMEOUT_MS),
   });
   if (response.status >= 300 && response.status < 400) {
     throw new ConnectionRefreshHttpError(response.status);

package/src/event-payload-sanitizer.ts

@@ -1,3 +1,5 @@
+import { boundSessionEventPayload } from "@opengeni/contracts";
+
 /**
  * Last line of defense against a session event crashing a whole turn.
  *
@@ -8,12 +10,10 @@
  * such a payload reaches `INSERT INTO session_events`, the driver rejects it
  * ("Failed query: insert into session_events") and the turn dies.
  *
- * `sanitizeEventPayload` deep-walks any payload value (objects, arrays, nested)
- * and, for every string, strips NUL and rewrites invalid/lone UTF-16 surrogates
- * to the Unicode replacement char (U+FFFD), so the result is always valid UTF-8
- * that jsonb can store. It is cheap and total: only strings are touched, and only
- * the two disallowed classes of code unit -- no meaningful text is lost, no
- * truncation (truncation is handled elsewhere).
+ * `sanitizeEventPayload` deep-walks any payload value (objects, arrays, nested),
+ * repairs every string, redacts sensitive fields, then applies the canonical
+ * byte-bounded human/audit preview. Conversation truth uses
+ * `sanitizeModelPayload` below and remains a separate representation.
  */
 
 const REPLACEMENT = "�";
@@ -89,11 +89,22 @@ export function sanitizeEventString(value: string): string {
  * keys are sanitized too -- they are jsonb-constrained the same as values.
  */
 export function sanitizeEventPayload<T>(payload: T): T {
+  // Bound first. The preview walker caps depth/container fan-out and replaces
+  // inline media before this sanitizer allocates a deep clone. Reversing this
+  // order lets a cyclic, deeply nested, or multi-megabyte tool result exhaust
+  // the stack/heap before the durable 64 KiB event boundary can protect it.
+  return sanitizeEventPayloadDeep(boundSessionEventPayload(payload));
+}
+
+function sanitizeEventPayloadDeep<T>(payload: T): T {
   if (typeof payload === "string") {
     return sanitizeEventString(payload) as unknown as T;
   }
   if (Array.isArray(payload)) {
-    return payload.map((item) => sanitizeEventPayload(item)) as unknown as T;
+    return payload.map((item) => sanitizeEventPayloadDeep(item)) as unknown as T;
+  }
+  if (payload instanceof Date) {
+    return safeDateIso(payload) as unknown as T;
   }
   if (payload && typeof payload === "object") {
     const entries = Object.entries(payload as Record<string, unknown>).map(
@@ -115,21 +126,48 @@ export function sanitizeEventPayload<T>(payload: T): T {
  * performs only the database-safety repair (NUL removal and UTF-16 repair).
  */
 export function sanitizeModelPayload<T>(payload: T): T {
+  return sanitizeModelPayloadDeep(payload, new WeakSet<object>(), 0);
+}
+
+const MODEL_PAYLOAD_SANITIZE_MAX_DEPTH = 64;
+const MODEL_PAYLOAD_CYCLE_MARKER = "[OpenGeni omitted cyclic model payload]";
+const MODEL_PAYLOAD_DEPTH_MARKER = "[OpenGeni omitted model payload beyond database-safety depth]";
+
+function sanitizeModelPayloadDeep<T>(payload: T, seen: WeakSet<object>, depth: number): T {
   if (typeof payload === "string") {
     return sanitizeEventString(payload) as unknown as T;
   }
-  if (Array.isArray(payload)) {
-    return payload.map((item) => sanitizeModelPayload(item)) as unknown as T;
+  if (!payload || typeof payload !== "object") return payload;
+  if (payload instanceof Date) {
+    return safeDateIso(payload) as unknown as T;
   }
-  if (payload && typeof payload === "object") {
+  if (depth >= MODEL_PAYLOAD_SANITIZE_MAX_DEPTH) {
+    return MODEL_PAYLOAD_DEPTH_MARKER as unknown as T;
+  }
+  if (seen.has(payload)) return MODEL_PAYLOAD_CYCLE_MARKER as unknown as T;
+  seen.add(payload);
+  try {
+    if (Array.isArray(payload)) {
+      return payload.map((item) => sanitizeModelPayloadDeep(item, seen, depth + 1)) as unknown as T;
+    }
     return Object.fromEntries(
       Object.entries(payload as Record<string, unknown>).map(([key, value]) => [
         sanitizeEventString(key),
-        sanitizeModelPayload(value),
+        sanitizeModelPayloadDeep(value, seen, depth + 1),
       ]),
     ) as unknown as T;
+  } finally {
+    seen.delete(payload);
+  }
+}
+
+function safeDateIso(value: Date): string | null {
+  try {
+    const epoch = Date.prototype.getTime.call(value);
+    return Number.isFinite(epoch) ? Date.prototype.toISOString.call(value) : null;
+  } catch {
+    return null;
   }
-  return payload;
 }
 
 function sanitizeSensitiveEventField(key: string, value: unknown): unknown {
@@ -142,19 +180,19 @@ function sanitizeSensitiveEventField(key: string, value: unknown): unknown {
   if (SENSITIVE_FIELD_NAMES.has(normalizeFieldName(key))) {
     return REDACTED;
   }
-  return sanitizeEventPayload(value);
+  return sanitizeEventPayloadDeep(value);
 }
 
 function sanitizeSessionMcpServerList(value: unknown): unknown {
   if (!Array.isArray(value)) {
-    return sanitizeEventPayload(value);
+    return sanitizeEventPayloadDeep(value);
   }
   return value.map((item) => {
     if (!isPlainObject(item)) {
-      return sanitizeEventPayload(item);
+      return sanitizeEventPayloadDeep(item);
     }
     const { headers, headersEncrypted, ...rest } = item;
-    const cleaned = sanitizeEventPayload(rest) as Record<string, unknown>;
+    const cleaned = sanitizeEventPayloadDeep(rest) as Record<string, unknown>;
     const headerNames = safeHeaderNames(headers) ?? safeHeaderNames(headersEncrypted);
     if (headerNames) {
       cleaned.headerNames = headerNames;
@@ -165,14 +203,14 @@ function sanitizeSessionMcpServerList(value: unknown): unknown {
 
 function sanitizeMcpCredentialUpdateList(value: unknown): unknown {
   if (!Array.isArray(value)) {
-    return sanitizeEventPayload(value);
+    return sanitizeEventPayloadDeep(value);
   }
   return value.map((item) => {
     if (!isPlainObject(item)) {
-      return sanitizeEventPayload(item);
+      return sanitizeEventPayloadDeep(item);
     }
     const { headers, headersEncrypted, ...rest } = item;
-    const cleaned = sanitizeEventPayload(rest) as Record<string, unknown>;
+    const cleaned = sanitizeEventPayloadDeep(rest) as Record<string, unknown>;
     const headerNames = safeHeaderNames(headers) ?? safeHeaderNames(headersEncrypted);
     if (headerNames) {
       cleaned.headerNames = headerNames;